jmlue42/spectral-jsonapi-ruleset

A Stoplight/Spectral linting ruleset for the JSON:API specification.

spectral-jsonapi-ruleset's Issues

Make available through unpkg

Per the docs you can use an http reference to extend a ruleset. When I try to access your ruleset via unpkg.com I get the following error

Cannot find package spectral-jsonapi-ruleset@latest

I believe this is because you haven't created the tag latest. Can you add that please?

Add a get-404-response-code rule (Section 6.2.1.2)

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.

Support of X-HTTP-Method-Override: PATCH

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

Add Stoplight.io compatible documentation explaining and giving examples to the project.

Tests do not work on Windows (with potential solution)

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.

new rule: verify page param is only used on collection routes

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

Section 6.6

new rule: verify paging links only exist on collection routes (Section 6.6)

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 data

Keys 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.

'resource-identification-property' fails with `allOf`

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?

Qualify rule names to simplify extending the ruleset

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.

Support format oas3 in addition to oas3.1?

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:

• the changes to the content definitions for requestBody do not appear to be relevant to the defined aliases
• given ... then statements within rules also don't appear to rely upon OAS 3.1 specific changes

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.

resource-object-id-required triggering on schemas using 'allOf'

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.

Rules covering Section 7.3 - Updating Relationships

Currently no rules exist covering this section of the spec.