spectral-ruleset

👷🚧🛠️ in development 👷🚧🛠️

Custom Spectral API Linter ruleset for Zalando RESTful API Guidelines.

There are two flavors of the ruleset:

• zalando: Sticks to the Zalando RESTful API Guidelines
• baloise: Adapts some rules to the needs of baloise

Please refer to the table below for details.

The ruleset spectral:oas is disabled by default. If you like to enable these rules again use

echo "extends: [https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/zalando.yml, spectral:oas]" \
    > .spectral.yml

Use it

Possibility A: Reference via Github URL

# zalando flavor:
npx @stoplight/spectral-cli lint \
    --ruleset https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/zalando.yml \
    example/example-openapi.yml

# baloise flavor:
npx @stoplight/spectral-cli lint \
    --ruleset https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/baloise.yml \
    example/example-openapi.yml

Or just create a .spectral.yml extending it

echo "extends: [https://raw.githubusercontent.com/baloise-incubator/spectral-ruleset/main/baloise.yml]" \
    > .spectral.yml
npx @stoplight/spectral-cli lint example/example-openapi.yml

If you're behind a proxy you can pass it via PROXY environment variable:

PROXY=<PROXY URL> npx @stoplight/spectral lint <...>

Possibility B: Install via npm

npm i @baloise/spectral-rules

# zalando flavor:
npx @stoplight/spectral-cli lint \
    --ruleset ./node_modules/@baloise/spectral-rules/zalando.yml \
    example/example-openapi.yml

# baloise flavor:
npx @stoplight/spectral-cli lint \
    --ruleset ./node_modules/@baloise/spectral-rules/baloise.yml \
    example/example-openapi.yml

Or just create a .spectral.yml extending it

echo "extends: [./node_modules/@baloise/spectral-rules/baloise.yml]" > .spectral.yml
npx @stoplight/spectral-cli lint example/example-openapi.yml

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 zalando.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 ✔️ to the table below.
6. Create a PR

Alternative baloise rules are marked by appending the rule number with an a. For example zalando rule #115 versus baloise rule #115a. The zalando rule #115 is defined in zalando.yml. The baloise rule #115a is defined in baloise.yml while deactivating the original zalando rule #115a.

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

✔️ = rule implemented
❕ = rule implementation not possible or to complex

id	title	zalando.yml	baloise.yml	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	✔️	✔️	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	✔️	✔️	-
#113	SHOULD avoid versioning	❕	❕	B
#114	MUST use media type versioning	❕	❕	-
#115	MUST not use URI versioning	✔️	-	A
#115a	CAN use correct URI versioning: ^((?!.*\/v\d+(\/.*)?\/v\d+)\/.*)$	-	✔️	A
#116	MUST use semantic versioning	✔️	✔️	B
#118	MUST property names must be ASCII snake_case (and never camelCase): ^[a-z_][a-z_0-9]*$	✔️	-	A
#118a	MUST property names must be ASCII camelCase: ^[a-z]+((\d)([A-Z0-9][a-z0-9]+))*([A-Z])?$	-	✔️	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	✔️	✔️	A
#130	MUST use snake_case (never camelCase) for query parameters	✔️	-	B
#130a	MUST use camelCase (never snake_case) for query parameters	-	✔️	B
#132	SHOULD prefer hyphenated-pascal-case for HTTP header fields	✔️	✔️	B
#133	MAY use standardized headers	-	-	-
#134	MUST pluralize resource names	-	-	A
#135	SHOULD not use /api as base path	✔️	✔️	A
#136	MUST use normalized paths without empty path segments and trailing slashes	✔️	✔️	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	✔️	✔️	B
#147	SHOULD limit number of sub-resource levels	✔️	✔️	B
#148	MUST use HTTP methods correctly	❕	❕	A
#149	MUST fulfill common method properties	❕	❕	-
#150	MUST use standard HTTP status codes	✔️		-
#150a	MUST use additional standard HTTP status codes	-	✔️	-
#151	MUST specify success and error responses	✔️	✔️	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	✔️	✔️	B
#173	MUST use the common money object	❕	❕	-
#174	MUST use common field names and semantics	❕	❕	-
#176	MUST support problem JSON	✔️	✔️	-
#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	✔️	✔️	-
#216	SHOULD define maps using additionalProperties	-	-	-
#217	MUST use full, absolute URI	-	-	-
#218	MUST contain API meta information	✔️	✔️	-
#219	MUST provide API audience	✔️	-	-
#219a	MUST provide baloise 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	❕	❕	-
#233a	MUST request must use tracing headers	-	✔️	-
#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	✔️	✔️	-
#241	MAY expose compound keys as resource identifiers	❕	❕	-