Validation

Documents are by default validated against JSON API specification. Additional validation is possible using schema documents.

Validation is performed during create and update operations. During a create operation request payload (i.e. document) is directly validated against a schema. During an update operation request body (i.e. partial document) is merged with an existing document from the database and the result is validated against a schema.

When the document does not pass validation, one or many errors will be returned in the response. Example schema specifies attribute name as a string and attribute miles as an integer where attribute name is required and no additional attributes are allowed except name and miles:

{
  "attributes": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "miles": {
        "type": "integer"
      }
    },
    "required": [
      "name"
    ],
    "additionalProperties": false
  }
}

Trying to create a document:

{
  "data": {
    "type": "car",
    "attributes": {
      "title": "Tesla Roadster",
      "miles": "unknown"
    }
  }
}

Will result in errors:

{
  "errors": [
    {
      "code": "unwanted-property",
      "source": {
        "pointer": "/data/attributes"
      },
      "status": "400",
      "title": "Object contains unwanted property.",
      "detail": "Object contains unwanted property: 'title'."
    },
    {
      "code": "required-property-missing",
      "source": {
        "pointer": "/data/attributes"
      },
      "status": "400",
      "title": "Required property is missing.",
      "detail": "Required property: 'name' is missing."
    },
    {
      "code": "invalid-property-value",
      "source": {
        "pointer": "/data/attributes/miles"
      },
      "status": "400",
      "title": "Invalid value of a property.",
      "detail": "Value of type 'string' is not valid. Expected: 'integer'."
    }
  ]
}

Errors contain source pointer which is very helpful to client applications which need to process and present errors to a user. Mapping errors back to a user interface should be straightforward using source pointers.