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 objectwhen itstypedoes 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:APIfor a property other thandata,errors,meta,jsonapi,linksandincluded;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 typeand, in responses and inincluded,... does not declare id, for each resource object ofdataandincluded(the schema of the member, the items of an array, the branches ofanyOfandoneOf) that declares properties;JSON:API resource object schema declares member '...' outside attributes and relationshipsfor a property other thantype,id,lid,attributes,relationships,linksandmeta.
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