spectral-ruleset

👷🚧🛠️ in development 👷🚧🛠️

Custom Spectral API Linter ruleset for Zalando RESTful API Guidelines.

Use it

# default openapi ruleset defined in .spectral.yml
npx @stoplight/spectral lint example/example-openapi.yml

# or reference the ruleset via url
npx @stoplight/spectral lint example/example-openapi.yml --ruleset https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/.spectral.yml

# if you're behind a proxy
PROXY=<PROXY URL> npx @stoplight/spectral lint <...>

Development

Adding a new Rule

1. Choose a new, unsupported rule from the table below. For example #151 MUST specify success and error responses.
2. Make sure tests/fixtures/base-openapi.yml satisfies the rule.
3. Add a test tests/151-MUST-specify-success-and-error-responses.test.ts that
   1. Takes the base-openapi.yaml as input
   2. Modifies it to break the new rule
   3. Expect that spectral finds the error (this will fail for now)
4. Extend .spectral.yml with the new rule, so that the previously added test succeeds. See https://meta.stoplight.io/docs/spectral/docs/guides/4-custom-rulesets.md on how to define custom rules.
5. Add a :heavy_check_mark: to the table below.
6. Create a PR

Setup

npm install
npm run test
npm run lint
npm run lint-fix # format source files

Currently supported rules from the zalando restful-api-guidelines

| id | title |supported | prio (A, B, C)| | --- | --- | --- | --- | | #100 | MUST follow API first principle | - | B | | #101 | MUST provide API specification using OpenAPI | - | A | | #102 | SHOULD provide API user manual | - | C | | #103 | MUST write APIs using U.S. English | - | A | | #104 | MUST secure endpoints with OAuth 2.0 | - | B | | #105 | MUST define and assign permissions (scopes) | - | B | | #106 | MUST not break backward compatibility | - | B | | #107 | SHOULD prefer compatible extensions | - | ? | | #108 | MUST prepare clients accept compatible API extensions | - | C | | #109 | SHOULD design APIs conservatively | - | ? | | #110 | MUST always return JSON objects as top-level data structures | :heavy_check_mark: | A | | #111 | MUST treat Open API specification as open for extension by default | - | - | | #112 | SHOULD used open-ended list of values (x-extensible-enum) for enumerations | :heavy_check_mark: | - | | #113 | SHOULD avoid versioning | - | B | | #114 | MUST use media type versioning | - | - | | #115 | MUST not use URI versioning | :heavy_check_mark: | A | | #116 | MUST use semantic versioning | :heavy_check_mark: | B | | #118 |~~MUST property names must be ASCII snake_case (and never camelCase): ^[a-z_][a-z_0-9]*$~~| :x: | A | | #118a | MUST property names must be ASCII camelCase: ^[a-z]+((\d)([A-Z0-9][a-z0-9]+))*([A-Z])?$ | :heavy_check_mark: | A | | #120 | SHOULD pluralize array names | - | B | | #122 | MUST not use null for boolean properties | - | - | | #123 | MUST use same semantics for null and absent properties | - | - | | #124 | SHOULD not use null for empty arrays | - | - | | #125 | SHOULD represent enumerations as strings | - | - | | #126 | SHOULD define dates properties compliant with RFC 3339 | - | - | | #127 | SHOULD define time durations and intervals properties conform to ISO 8601 | - | - | | #128 | SHOULD use standards for country, language and currency codes | - | - | | #129 | MUST use lowercase separate words with hyphens for path segments | :heavy_check_mark: | A | | #130 | MUST use snake_case (never camelCase) for query parameters | :heavy_check_mark: | B | | #132 | SHOULD prefer hyphenated-pascal-case for HTTP header fields | :heavy_check_mark: | B | | #133 | MAY use standardized headers | - | - | | #134 | MUST pluralize resource names | - | A | | #135 | SHOULD not use /api as base path | :heavy_check_mark: | A | | #136 | MUST use normalized paths without empty path segments and trailing slashes | :heavy_check_mark: | B | | #137 | MUST stick to conventional query parameters | - | - | | #138 | MUST avoid actions — think about resources | - | A | | #139 | SHOULD model complete business processes | - | - | | #140 | SHOULD define useful resources | - | - | | #141 | MUST keep URLs verb-free | - | A | | #142 | MUST use domain-specific resource names | - | - | | #143 | MUST identify resources and sub-resources via path segments | - | - | | #144 | SHOULD only use UUIDs if necessary | - | - | | #145 | MAY consider using (non-)nested URLs | - | - | | #146 | SHOULD limit number of resource types | :heavy_check_mark: | B | | #147 | SHOULD limit number of sub-resource levels | :heavy_check_mark: | B | | #148 | MUST use HTTP methods correctly | - | A | | #149 | MUST fulfill common method properties | - | - | | #150 | MUST use standard HTTP status codes | :heavy_check_mark: | - | | #151 | MUST specify success and error responses | :heavy_check_mark: | B | | #152 | MUST use code 207 for batch or bulk requests | - | C | | #153 | MUST use code 429 with headers for rate limits | - | C | | #154 | MUST define collection format of header and query parameters | - | - | | #155 | SHOULD reduce bandwidth needs and improve responsiveness | - | - | | #156 | SHOULD use gzip compression | - | - | | #157 | SHOULD support partial responses via filtering | - | - | | #158 | SHOULD allow optional embedding of sub-resources | - | - | | #159 | MUST support pagination | - | - | | #160 | SHOULD prefer cursor-based pagination, avoid offset-based pagination | - | - | | #161 | SHOULD use pagination links where applicable | - | - | | #162 | MUST use REST maturity level 2 | - | - | | #163 | MAY use REST maturity level 3 - HATEOAS | - | - | | #164 | MUST use common hypertext controls | - | - | | #165 | SHOULD use simple hypertext controls for pagination and self-references | - | - | | #166 | MUST not use link headers with JSON entities | - | - | | #167 | MUST use JSON to encode structured data | - | - | | #168 | MAY use non JSON media types for binary data or alternative content representations | - | - | | #169 | MUST use standard date and time formats | - | A | | #170 | SHOULD use standards for country, language and currency codes | - | B | | #171 | MUST define format for number and integer types | - | - | | #172 | SHOULD prefer standard media type name application/json | :heavy_check_mark: | B | | #173 | MUST use the common money object | - | - | | #174 | MUST use common field names and semantics | - | - | | #176 | MUST support problem JSON | :heavy_check_mark: | - | | #177 | MUST not expose stack traces | - | - | | #178 | MUST use Content-* headers correctly | - | - | | #179 | MAY use Content-Location header | - | - | | #180 | SHOULD use Location header instead of Content-Location header | - | - | | #181 | MAY consider to support Prefer header to handle processing preferences | - | - | | #182 | MAY consider to support ETag together with If-Match/If-None-Match header | - | - | | #183 | SHOULD use only the specified proprietary Zalando headers | - | - | | #184 | MUST propagate proprietary headers | - | - | | #185 | MUST obtain approval of clients before API shut down | - | - | | #186 | MUST collect external partner consent on deprecation time span | - | - | | #187 | MUST reflect deprecation in API specifications | - | - | | #188 | MUST monitor usage of deprecated API scheduled for sunset | - | - | | #189 | SHOULD add Deprecation and Sunset header to responses | - | - | | #190 | SHOULD add monitoring for Deprecation and Sunset header | - | - | | #191 | MUST not start using deprecated APIs | - | B | | #192 | MUST publish Open API specification | - | A | | #193 | SHOULD monitor API usage | - | - | | #194 | MUST treat events as part of the service interface | - | - | | #195 | MUST make event schema available for review | - | - | | #196 | MUST ensure event schema conforms to Open API schema object | - | - | | #197 | MUST ensure that events are registered as event types | - | - | | #198 | MUST ensure that events conform to a well-known event category | - | - | | #199 | MUST ensure that events define useful business resources | - | - | | #200 | MUST ensure that events do not provide sensitive data | - | - | | #201 | MUST use the general event category to signal steps and arrival points in business processes | - | - | | #202 | MUST use data change events to signal mutations | - | - | | #203 | SHOULD provide means for explicit event ordering | - | - | | #204 | SHOULD use the hash partition strategy for data change events | - | - | | #205 | SHOULD ensure that data change events match the APIs resources | - | - | | #207 | MUST indicate ownership of event types | - | - | | #208 | MUST define event payloads compliant with overall API guidelines | - | - | | #209 | MUST maintain backwards compatibility for events | - | - | | #210 | SHOULD avoid additionalProperties in event type definitions | - | - | | #211 | MUST use unique event identifiers | - | - | | #212 | SHOULD design for idempotent out-of-order processing | - | - | | #213 | MUST follow naming convention for event type names | - | - | | #214 | MUST prepare event consumers for duplicate events | - | - | | #215 | MUST provide API identifiers | :heavy_check_mark: | - | | #216 | SHOULD define maps using additionalProperties | - | - | | #217 | MUST use full, absolute URI | - | - | | #218 | MUST contain API meta information | :heavy_check_mark: | - | | #219 | MUST provide API audience | - | - | | #220 | MUST use most specific HTTP status codes | - | - | | #223 | MUST-SHOULD use functional naming schema | - | - | | #224 | MUST follow naming convention for hostnames | - | - | | #225 | MUST follow naming convention for permissions (scopes) | - | - | | #226 | MUST document implicit filtering | - | - | | #227 | MUST document cachable GET, HEAD, and POST endpoints | - | - | | #228 | MUST use URL-friendly resource identifiers: [a-zA-Z0-9:._-/]* | - | A | | #229 | SHOULD consider to design POST and PATCH idempotent | - | - | | #230 | MAY consider to support Idempotency-Key header | - | - | | #231 | Should use secondary key for idempotent POST design | - | - | | #233 | MUST support X-Flow-ID | - | - | | #234 | MUST only use durable and immutable remote references | - | - | | #235 | SHOULD name date/time properties with _at suffix | - | - | | #236 | SHOULD design simple query languages using query parameters | - | - | | #237 | SHOULD design complex query languages using JSON | - | - | | #238 | SHOULD use standardized property formats | - | - | | #239 | SHOULD encode embedded binary data in base64url | - | - | | #240 | SHOULD declare enum values using UPPER_SNAKE_CASE format | :heavy_check_mark: | - | | #241 | MAY expose compound keys as resource identifiers | - | - |