OpenAPI 3.0 schemas that comply with the JSON:API 1.0 specification

jsonapi_oas.yml

JSONAPIObject:
  description: Includes the current JSON:API version for this specification as well as optional meta information
  type: object
  required:
    - version
  properties:
    version:
      type: string
      default: '1.0'
      example: '1.0'
    meta:
      type: object

JSONAPIResourceIdentifierObject:
  title: JSON:API Resource Identifier Object
  description: |
    A JSON:API-compliant resource identifier object. An inheritable object schema that contains the basic framework of a Resource Identifier Object from the JSON:API spec.

    A “resource identifier object” is an object that identifies an individual resource.

    A “resource identifier object” MUST contain `type` and `id` members.

    A “resource identifier object” MAY also include a `meta` member, whose value is a meta object that contains non-standard meta-information. If necessary, the `meta` property should be added by the inheriting schema.
  type: object
  required:
    - type
    - id
  properties:
    type:
      $ref: '#/components/schemas/JSONAPIType'
    id:
      $ref: '#/components/schemas/JSONAPIId'

JSONAPIResourceObject:
  title: JSON:API Resource Object
  description: |
    A JSON:API-compliant resource object. An inheritable object schema that contains the basic framework of a Resource Object from the JSON:API spec.

    The `attributes`, `relationship`, and `meta` properties are added, as necessary, by the inheriting schema.
  type: object
  required:
    - type
  properties:
    type:
      $ref: '#/components/schemas/JSONAPIType'
    id:
      $ref: '#/components/schemas/JSONAPIId'
    links:
      $ref: '#/components/schemas/JSONAPILinksObject'

JSONAPIType:
  title: JSON:API type Member
  description: |
    The `type` member is used to describe resource objects that share common attributes and relationships.

    Note: The type member is required in every resource object throughout requests and responses in JSON:API. There are some cases, such as when POSTing to an endpoint representing heterogeneous data, when the type could not be inferred from the endpoint. However, picking and choosing when it is required would be confusing; it would be hard to remember when it was required and when it was not. Therefore, to improve consistency and minimize confusion, type is always required.
  type: string

JSONAPIId:
  title: JSON:API id Member
  description: Every resource object MUST contain an id member and a type member (exception-the id member is not required when the resource object originates at the client and represents a new resource to be created on the server). Within a given API, each resource object’s type and id pair MUST identify a single, unique resource.
  type: string

JSONAPILinksObject:
  title: JSON:API Links Object
  description: May contain `self`, `related`, or pagination links (first, last, prev, next).
  properties:
    self:
      $ref: '#/components/schemas/JSONAPILink'
    related:
      $ref: '#/components/schemas/JSONAPILink'
    first:
      $ref: '#/components/schemas/JSONAPILink'
    last:
      $ref: '#/components/schemas/JSONAPILink'
    prev:
      $ref: '#/components/schemas/JSONAPILink'
    next:
      $ref: '#/components/schemas/JSONAPILink'

JSONAPILink:
  title: JSON:API Link
  description: A JSON:API link can be either a URL string or a structured link object.
  oneOf:
    - $ref: '#/components/schemas/URL'
    - $ref: '#/components/schemas/JSONAPILinkObject'

URL:
  type: string
  format: url
  example: 'https://example.com/'

JSONAPILinkObject:
  title: JSON:API Link Object
  description: a structured representation of a URL
  type: object
  required:
   - href
  properties:
    href:
      type: string
      example: 'https://example.com/'
    meta:
      type: object
      example:
        count: '10'

JSONAPIRelationshipObject:
  title: JSON:API Relationship Object
  description: |
    This schema can be used when defining `relationships` objects within a JSON:API resource object.

    The value of the relationships key MUST be an object (a “relationships object”). Members of the relationships object (“relationships”) represent references from the resource object in which it’s defined to other resource objects.

    Relationships may be to-one or to-many.
  type: object
  oneOf:
    - type: object
      description: links object
      properties:
        links:
          $ref: '#/components/schemas/JSONAPILinksObject'
    - type: object
      description: |
        Resource linkage in a compound document allows a client to link together all of the included resource objects without having to GET any URLs via links.

        Resource linkage MUST be represented as one of the following:
        * null for empty to-one relationships.
        * an empty array ([]) for empty to-many relationships.
        * a single resource identifier object for non-empty to-one relationships.
        * an array of resource identifier objects for non-empty to-many relationships.
      properties:
        data:
          oneOf:
            - type: string
              description: null indicates an empty to-one relationship
              default: 'null'
            - type: array
              description: an empty array indicates an empty to-many relationship; an array with objects indicates a non-empty to-many relationship
              items:
                $ref: '#/components/schemas/JSONAPIResourceIdentifierObject'
            - $ref: '#/components/schemas/JSONAPIResourceIdentifierObject'
    - type: object
      description: a meta object that contains non-standard meta-information about the relationship
      properties:
        meta:
          type: object

JSONAPIErrorResponse:
  title: JSON:API Error Response
  description: A JSON:API-compliant error response. This object is inherited by the specific response type.
  type: object
  required:
    - errors
  properties:
    errors:
      description: An array of Error objects
      type: array
      minItems: 1
      items:
        description: A JSON:API-compliant error object. According to the JSON:API, none of the properties are required. For our purposes, we have made status and title required.
        type: object
        required:
          - status
          - title
        properties:
          id:
            description: a unique identifier for this particular occurrence of the problem
            type: string
            format: uuid
          links:
            description: a link to further details about this particular occurrence of the problem
            type: object
            properties:
              about:
                $ref: '#/components/schemas/JSONAPILink'
          status:
            description: the HTTP status code applicable to this problem
            type: string
            minLength: 3
            maxLength: 3
          code:
            description: an application-specific error code
            type: string
          title:
            description: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization
            type: string
          detail:
            description: a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized
            type: string
          source:
            description: contains references to the source of the error
            type: object
            properties:
              pointer:
                description: a JSON Pointer [RFC6901] to the associated entity in the request document
                type: string
              parameter:
                description: indicates which URI query parameter caused the error
                type: string
          meta:
            description: a JSON meta object with non-standard meta-information about the error
            type: object
            additionalProperties: true

.