json-api/schema-validation

Since 0.0.1 · In the rulesets: JsonApi at error

This rule checks that the schemas of the JSON:API request bodies and responses describe JSON:API documents: a top-level object with data, errors or meta, and resource objects with type and id.

Rule details

A JSON:API document has a fixed shape, and a schema that departs from it (a bare array, a string) produces clients that cannot be JSON:API clients.

The rule reads the schema of every application/vnd.api+json request body and response, with references followed and the parts of an allOf taken together, and reports:

  • JSON:API document schema is not an object when its type does not allow an object;
  • JSON:API document schema declares none of data, errors and meta, when it declares properties;
  • JSON:API document schema declares member '...', which is not a top-level member of JSON:API for a property other than data, errors, meta, jsonapi, links and included;
  • JSON:API document schema requires both data and errors;
  • JSON:API errors member is not an array;
  • JSON:API resource object schema does not declare type and, in responses and in included, ... does not declare id, for each resource object of data and included (the schema of the member, the items of an array, the branches of anyOf and oneOf) that declares properties;
  • JSON:API resource object schema declares member '...' outside attributes and relationships for a property other than type, id, lid, attributes, relationships, links and meta.

A property with a colon, the namespaced member of a JSON:API extension, is accepted everywhere. A schema without properties, such as a bare type: object, describes no members and passes. A schema shared by several operations is reported once. The rule is part of the json-api ruleset.

Examples

Good. The smallest document schema JSON:API allows.

paths:
  /users/current:
    get:
      responses:
        "200":
          description: The current user.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  jsonapi:
                    type: object
                  data:
                    type: object

Bad. A string is not a JSON:API document.

paths:
  /users/current:
    get:
      responses:
        "200":
          description: The current user.
          content:
            application/vnd.api+json:
              schema:
                type: string

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.

commands:
  lint:
    rules:
      json-api/schema-validation: off
Was this helpful?