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
Was this helpful?