json-api/resource-type-unique

This rule ensures that all resource schemas in a JSON:API have unique resource IDs.

Rule Details

Within the JSON:API specification a uniqueness of a resource depends on a uniqueness of its type. Therefore, we need a way to check the latter.

The json-api/resource-type-unique rule is designed to ensure that all resource schemas in a JSON:API have unique resource IDs. This rule is specifically useful for APIs that adhere to the JSON:API specification.

To determine the resource type, the rule checks both the const and enum properties of corresponding JSON schemas.

Configuration

None.

Examples

Good. The following schema defines two resources with unique types.

openapi: 3.1.0
info: ...
paths: ...
components:
  schemas:
    User:
      type: object
      properties:
        type:
          type: string
          const: user
        ...
    Employee:
      type: object
      properties:
        type:
          type: string
          enum:
            - employee
        ...

Bad. The following schema does not define allowed value for a resource.

openapi: 3.1.0
info: ...
paths: ...
components:
    schemas:
        User:
            type: object
            properties:
                type:
                    # this property does not specify allowed values
                    type: string
                ...

Bad. The following schema defines two distinct resources with identical resource types.

openapi: 3.1.0
info: ...
paths: ...
components:
    schemas:
        User:
            type: object
            properties:
                type:
                    type: string
                    const: person
                ...
        Employee:
            type: object
            properties:
                type:
                    type: string
                    enum:
                        - person
                ...

When Not to Use It

When you do not use the JSON:API specification.

Compatibility

This rule is compatible with all OpenAPI 3.x version.