Skip to content

Add JSON:API v1.1 support as an additive overlay #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
arjenblokzijl wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Add JSON:API v1.1 support as an additive overlay #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
af9edb0
Add JSON:API v1.1 ruleset as an additive overlay
arjenblokzijl Jun 23, 2026
84de6e1
Document JSON:API v1.1 ruleset in README
arjenblokzijl Jun 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,34 @@
![Node.js CI](https://github.com/jmlue42/spectral-jsonapi-ruleset/workflows/Node.js%20CI/badge.svg)
![CodeQL](https://github.com/jmlue42/spectral-jsonapi-ruleset/workflows/CodeQL/badge.svg)

> A [Stoplight/Spectral](https://github.com/stoplightio/spectral) linting ruleset for the [JSON:API specification v1.0](https://jsonapi.org/format/1.0).
> A [Stoplight/Spectral](https://github.com/stoplightio/spectral) linting ruleset for the [JSON:API specification](https://jsonapi.org/), supporting both [v1.0](https://jsonapi.org/format/1.0) and [v1.1](https://jsonapi.org/format/1.1).

## Installation
For ways to integrate this ruleset into your Spectral linting suite. See [Sharing & Distributing Rulesets](https://meta.stoplight.io/docs/spectral/docs/guides/7-sharing-rulesets.md) at <https://meta.stoplight.io/>

## Organization

`.spectral.yml` - Spectral Ruleset
`.spectral.yml` - Spectral Ruleset for JSON:API **v1.0**

The ruleset `extends` - `spectral:oas`, spectral's built-in OAS linting rules.
`jsonapi-1.1.yml` - Spectral Ruleset for JSON:API **v1.1**

Point Spectral at the file matching the JSON:API version your API targets:

```bash
# Lint a v1.0 API definition
spectral lint your-api.yml -r ./.spectral.yml

# Lint a v1.1 API definition
spectral lint your-api.yml -r ./jsonapi-1.1.yml
```

The v1.0 ruleset `extends` - `spectral:oas`, spectral's built-in OAS linting rules.

`jsonapi-1.1.yml` is an additive overlay: it `extends` `.spectral.yml` and only redefines the rules that changed in v1.1 (the `ext`/`profile` media type parameters, the expanded `links` object members, the `jsonapi` object `ext`/`profile`/`meta` members, and the `lid` local identifier). Everything else is inherited unchanged. (Note: Spectral does not inherit `aliases` through `extends`, so the alias block is duplicated in the overlay; keep the two in sync.)

The rules are generally organized by the JSON:API specification section the rule is mentioned in. Each rule notes the section url it realates to.

`examples` folder contains valid and invalid OAS3.1 examples
`examples` folder contains valid and invalid OAS3.1 examples. `examples/valid` is linted against the v1.0 ruleset and `examples/valid-1.1` against the v1.1 ruleset.

## Contributing
In lieu of a formal style guide (I know... ironic :grin:):
Expand Down
Loading