Trimble OpenAPI Spectral rules

This repository contains Spectral rules for linting Trimble OpenAPI specification documents. These rules are a companion to the Trimble Web API Standard.

How to use the Spectral ruleset

Dependencies

Using the Spectral CLI requires NodeJS. This ruleset is tested with NodeJS 16.x.

Installation

See the Spectral installation instructions for complete details.

npm install -g @stoplight/spectral-cli

Usage

Updated August 2025

We have depricated the develop branch and are implementing tags/releases.

Current release v1.0

https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/refs/tags/1.0/spectral.yaml

You can specify the ruleset directly on the command line:

spectral lint -r https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/refs/tags/1.0/spectral.yaml <api definition file>

Latest unreleased

Access the latest pre release version:

https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/refs/heads/main/spectral.yaml

Example use in the command line:

spectral lint -r https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/refs/heads/main/spectral.yaml <api definition file>

Extend the ruleset

You can create a Spectral configuration file (.spectral.yaml) that references the ruleset:

extends:
  - https://raw.githubusercontent.com/trimble-oss/openapi-spectral-rules/main/spectral.yaml

In this way you can create a custom ruleset that extends the Trimble ruleset.

Trimble Rules

✅ tdp-minimum-spec-version

Warn if spec version is not 3.0 or higher

✅ tdp-tag-pascal-case

Tag names cannot use Pascal Case

✅ tdp-tag-camel-case

Tag names cannot use Camel Case

✅ tdp-tag-no-versions

Tag names cannot have version information

✅ tdp-operation-summary-description

Operation summaries and descriptions should not match. Descriptions should be longer than summaries.

✅ tdp-operation-post-201-202-status-code

All POST methods should have a 201 or 202 response. POST (create) - Successful Responses

✅ tdp-operation-delete-204-status-code

All DELETE methods should have a 204 response.

✅ tdp-operation-400-response-body

All 400 responses must include a response body.

References

Learn about writing rules here: https://docs.stoplight.io/docs/spectral/d3482ff0ccae9-rules

Learn about custom function here: https://docs.stoplight.io/docs/spectral/a781e290eb9f9-custom-functions

JSONPath documentation: https://goessner.net/articles/JsonPath/index.html

Useful web based tool for testing youe JSONPath values: http://jsonpath.com/

Petstore examples are from OpenAPI Initiative