jsonapi-schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "JSON API Schema",
  "description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
  "oneOf": [
    {
      "$ref": "#/definitions/success"
    },
    {
      "$ref": "#/definitions/failure"
    }
  ],
  "definitions": {
    "success": {
      "type": "object",
      "required": [
        "data"
      ],
      "properties": {
        "meta": {
          "$ref": "#/definitions/meta"
        },
        "data": {
          "$ref": "#/definitions/data"
        },
        "included": {
          "$ref": "#/definitions/included"
        },
        "links": {
          "$ref": "#/definitions/topLevelLinks"
        }
      },
      "additionalProperties": false
    },
    "failure": {
      "type": "object",
      "required": [
        "errors"
      ],
      "properties": {
        "meta": {
          "$ref": "#/definitions/meta"
        },
        "errors": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/error"
          },
          "uniqueItems": true
        }
      },
      "additionalProperties": false
    },
    "meta": {
      "description": "Non-standard meta-information that can not be represented as an attribute or relationship.",
      "type": "object",
      "additionalProperties": true
    },
    "data": {
      "description": "Primary data **MUST** appear under a top-level key named \"data\". Primary data **MUST** be either a single resource object, an array of resource objects, or a value representing a resource relationship.",
      "oneOf": [
        {
          "$ref": "#/definitions/resource"
        },
        {
          "description": "An array of resource objects.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/resource"
          },
          "uniqueItems": true
        }
      ]
    },
    "resource": {
      "description": "\"Resource objects\" appear in a JSON API document to represent primary data and linked resources.",
      "type": "object",
      "required": [
        "type",
        "id"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "attributes": {
          "$ref": "#/definitions/attributes"
        },
        "relationships": {
          "$ref": "#/definitions/relationships"
        },
        "links": {
          "$ref": "#/definitions/links"
        },
        "meta": {
          "$ref": "#/definitions/meta"
        }
      },
      "additionalProperties": false
    },
    "included": {
      "description": "A list of resource objects that are related to the primary data and/or each other (\"included resources\").",
      "type": "array",
      "items": {
        "$ref": "#/definitions/resource"
      },
      "uniqueItems": true
    },
    "topLevelLinks": {
      "description": "URLs related to the primary data.",
      "type": "object",
      "allOf": [
        {
          "$ref": "#/definitions/links"
        },
        {
          "$ref": "#/definitions/pagination"
        }
      ]
    },
    "links": {
      "description": "A resource object **MAY** contain references to other resource objects (\"relationships\"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.",
      "type": "object",
      "properties": {
        "self": {
          "description": "A `self` member, whose value is a URL for the relationship itself (a \"relationship URL\"). This URL allows the client to directly manipulate the relationship. For example, it would allow a client to remove an `author` from an `article` without deleting the people resource itself.",
          "type": "string",
          "format": "uri"
        },
        "related": {
          "type": "string",
          "format": "uri"
        },
        "meta": {
          "$ref": "#/definitions/meta"
        }
      },
      "additionalProperties": false
    },

    "attributes": {
      "type": "object",
      "additionalProperties": true
    },

    "relationships": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          { "$ref": "#/definitions/relationshipToOne" },
          { "$ref": "#/definitions/relationshipToMany" }
        ]
      }
    },

    "relationshipToOne": {
      "description": "References to other resource objects in a to-one (\"relationship\"). Relationships can be specified by including a member in a resource's links object.",
      "type": "object",
      "required": ["data"],
      "properties": {
        "meta": {
          "$ref": "#/definitions/meta"
        },
        "links": {
          "$ref": "#/definitions/links"
        },
        "data": {
          "description": "Member, whose value represents \"resource linkage\".",
          "anyOf": [
            {
              "$ref": "#/definitions/empty"
            },
            {
              "$ref": "#/definitions/linkage"
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "relationshipToMany": {
      "description": "References to other resource objects in a to-many (\"relationship\"). Relationships can be specified by including a member in a resource's links object. This could be an empty array for empty to-many relationships.",
      "type": "object",
      "properties": {
        "meta": {
          "$ref": "#/definitions/meta"
        },
        "links": {
          "$ref": "#/definitions/links"
        },
        "data": {
          "description": "An array of objects each containing \"type\" and \"id\" members for to-many relationships.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/linkage"
          },
          "uniqueItems": true
        }
      },
      "additionalProperties": false
    },
    "empty": {
      "description": "Describes an empty to-one relationship.",
      "type": ["object", "null"],
      "properties": {},
      "additionalProperties": false
    },
    "linkage": {
      "description": "The \"type\" and \"id\" to non-empty members.",
      "type": "object",
      "required": [
        "type",
        "id"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "id": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "pagination": {
      "type": "object",
      "properties": {
        "first": {
          "description": "the first page of data",
          "type": "string",
          "format": "uri"
        },
        "last": {
          "description": "the last page of data",
          "type": "string",
          "format": "uri"
        },
        "prev": {
          "description": "the previous page of data",
          "type": "string",
          "format": "uri"
        },
        "next": {
          "description": "the next page of data",
          "type": "string",
          "format": "uri"
        }
      }
    },
    "error": {
      "type": "object",
      "properties": {
        "id": {
          "description": "A unique identifier for this particular occurrence of the problem.",
          "type": "string"
        },
        "href": {
          "description": "A URI that **MAY** yield further details about this particular occurrence of the problem.",
          "type": "string"
        },
        "status": {
          "description": "The HTTP status code applicable to this problem, expressed as a string value.",
          "type": "string"
        },
        "code": {
          "description": "An application-specific error code, expressed as a string value.",
          "type": "string"
        },
        "title": {
          "description": "A short, human-readable summary of the problem. It **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.",
          "type": "string"
        },
        "links": {
          "description": "An array of JSON Pointers [RFC6901] to the associated resource(s) within the request document [e.g. [\"/data\"] for a primary data object].",
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "paths": {
          "description": "An array of JSON Pointers to the relevant attribute(s) within the associated resource(s) in the request document. Each path **MUST** be relative to the resource path(s) expressed in the error object's \"links\" member [e.g. [\"/first-name\", \"/last-name\"] to reference a couple attributes].",
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        }
      },
      "additionalProperties": true
    }
  }
}