jmlue42 / spectral-jsonapi-ruleset Goto Github PK
View Code? Open in Web Editor NEWA Stoplight/Spectral linting ruleset for the JSON:API specification.
License: MIT License
A Stoplight/Spectral linting ruleset for the JSON:API specification.
License: MIT License
Per Section 6.2.1.2 of JSON:API v1:
A server MUST return
404 Not Found
when processing a request to fetch a relationship link URL that does not exist.
A rule needs to be written to be written to verify a 404 response is supported on GET paths that return a single resource.
Per Supporting Clients Lacking PATCH:
Some clients, like IE8, lack support for HTTP’s PATCH method. API servers that wish to support these clients are recommended to treat POST requests as PATCH requests if the client includes the
X-HTTP-Method-Override: PATCH
header. This allows clients that lack PATCH support to have their update requests honored, simply by adding the header
Currently the ruleset does not take this method into consideration when checking POST and PATCH routes.
Add Stoplight.io compatible documentation explaining and giving examples to the project.
The current npm test
results in the following when executing on Windows:
'.' is not recognized as an internal or external command, operable program or batch file.
Changing the current scripts from:
"scripts": {
"test": "./node_modules/.bin/spectral lint examples/valid/* -r ./.spectral.yml",
"prepare": "husky install"
},
to
"scripts": {
"test": "spectral lint examples/valid/* -r ./.spectral.yml",
"prepare": "husky install"
},
fixes the problem on Windows. I'm currently unable to test this on Unix right now, but believe this should also work there as ./node_modules/.bin
is apparently added to the start of the PATH by node or npm.
Note: I haven't PRed this as I need someone to verify it won't break compatibility on other platforms first.
Currently the page
parameter schema is being linted. A new rule needs to be created to verify the page
parameter is only used on collection routes.
This page parameter is listed as a SHOULD so recommend severity level: warn
or info
Per Section 6.6 of JSON:API v1:
The following keys MUST be used for pagination links:
first
: the first page of data
last
: the last page of data
prev
: the previous page of data
next
: the next page of dataKeys MUST either be omitted or have a null value to indicate that a particular link is unavailable.
A new rule needs to created to verify these link names only exist on collection routes.
First, thanks a lot for your work you put into this ruleset! I unfortunately encountered an issue I need you help with. See the given spec:
$defs:
resource_id:
description: Resource objects appear in a JSON API document to represent resources.
type: object
required:
- type
- id
additionalProperties: false
properties:
type:
type: string
id:
type: string
allOf:
- $ref: "#/$defs/resource_id"
- type: object
properties:
attributes:
type: object
properties:
foo:
type: string
When running spectral with you linter rule I get this error
23:18 error resource-identification-property Every resource object MUST contain an id member and a type member. The values of the id and type members MUST be strings. allOf[1].properties.attributes
But debugging the json path, all properties type
, id
and foo
are selected. How come this rule fails? Any idea?
Currently this ruleset uses simple rule names like "content-type". If you want to extend this ruleset, simple, unqualified names like this increase the chances of name clashes when combining them with other rulesets.
The OWASP ruleset ( https://github.com/stoplightio/spectral-owasp-ruleset/blob/main/src/ruleset.ts ) uses a URN style naming scheme that makes name clashes extremely unlikely. Changing the rule names of the JSON:API spectral ruleset to align with this naming scheme would make it easier for others to adopt and extend this ruleset.
e.g. rule content-type
could become rule json:api:1:sec4:content-type
.
I'll submit a PR soon implementing this change.
The current ruleset includes support for format oas3.1 but not oas3.
A superficial check of the changes ( https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0 ) and the ruleset indicates it doesn't make use of any OAS 3.1 specific features. In particular:
Can we please add oas3 to the supported formats list? i.e.
formats:
- oas3.1
- oas3
I've already changed this in a local copy of the ruleset and it appears to be working OK.
Rule: resource-object-id-required
is triggering on allOf items that fail the rule even though another item passes the check:
Example doc snippet:
MyResourceResponseObject:
allOf:
- $ref: '#/components/schemas/IdentifierObject'
- type: object
required:
- attributes
- relationships
properties:
type:
enum:
- resources
attributes:
type: object
required:
- name
properties:
account_id:
type: string
name:
type: string
example: do-hickey
description:
type: string
example: thing that does stuff
The rule checks for the presence of id
, in the above example the $ref
item contains the id
, the rule continues to try and validate the second item which fails and throws the alert.
Expected behavior: schema passes as one of the items meets the id
requirment.
Currently no rules exist covering this section of the spec.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.