json-api/resource-type-unique
Since 0.0.1 · In the rulesets: JsonApi at error
This rule checks that every resource object schema of the JSON:API responses declares its type
as a const or a one-value enum, and that no two of them declare the same type.
Rule details
In JSON:API, a resource is identified by its type and id, so two resource schemas with the
same type are the same resource to every client, and a client cannot tell which of the two shapes
it receives.
The rule reads the data and included members of every application/vnd.api+json response:
the schema of the member, the items of an array and the branches of anyOf and oneOf, after
references; a schema counts as a resource object when it declares properties. It reports
Resource object schema does not declare its type as a const or a one-value enum and
Resource type '...' is the type of another resource object schema too, the second on every
schema after the first with that type.
Request bodies are left out: the resource a client creates or updates is usually a schema of its
own, without id or with fewer attributes, under the type of the resource the server returns. A
resource object without a type property is left to
json-api/schema-validation.
Examples
Good. Two resources with distinct types, one as const, one as enum.
paths:
/users:
get:
responses:
"200":
description: The users and their employers.
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/User"
included:
type: array
items:
$ref: "#/components/schemas/Employer"
components:
schemas:
User:
type: object
properties:
type:
type: string
const: user
id:
type: string
Employer:
type: object
properties:
type:
type: string
enum: [employer]
id:
type: string
Bad. With the same response, both resource schemas declare the type person.
components:
schemas:
User:
type: object
properties:
type:
type: string
const: person
id:
type: string
Employer:
type: object
properties:
type:
type: string
enum: [person]
id:
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/resource-type-unique: off