json-api-spec.md

// Success response
{
  // Document's primary data - resource or collection of resources targeted by request
  // (a.k.a. - either object or array of objects)

  // Single resouce variant (null in case it is not available)
  data: {
    // Required
    id: 'xyz' // Must be string - not required when the resource object originates at the client
    type: 'user' // Must be string
    // Optional
    attributes: {
      name: 'Ondrej'
      age: 16
    }
    // Optional - describes relationships between the resource and other JSON:API resources
    relationships: {
      // relationship must contain at least one of the following - links / data / meta
      author: {
        // links must contain at least one of the following - self / related
        links: {
          // link for the relationship itself  
          self: "/articles/1/relationships/author"
          // related resource link - provides access to resource objects linked in relationship
          related: "/articles/1/author"
        }
        // null for empty to-one relationships
        // [] for empty to-many relationships
        // single resource identifier for non-empty to-one relationships
        // an array of resource identifiers for non-empty to-many relatiopnships
        data: {
          type: people
          id: 9 
        }
        // Meta object that contains non-standard meta-information about the relationship
        meta: {}
      }
    }
    // Optional - contains links related to resource
    links: {
      self: "http://example.com/articles/1"
    }
  }

  // Collection of resources (empty array in case it is empty)
  data: []

  // Optional
  // an object describing the server's implementation
  jsonapi: {
  }

  // Optional
  // Links object related to the primary data
  links: {
    // Optional - link that generated the current response document
    self: 'https://...';
    // Optional - a related resource link when the primary data represents a resource relationship
    related: 'https://...';
    // Optional - all 4 folloginw pros are considered 'pagination' links
    first: '';
    last: '';
    prev: '';
    next: '';
  }

  // Optional
  // an array of resource objects that are related to the primary data
  // a.k.a - Compound document
  // every resource with type+id must be included just once (even if referenced multiple times)
  included: [
    {
      "type": "people",
      "id": "9",
      "attributes": {
        "first-name": "Dan",
        "last-name": "Gebhardt",
        "twitter": "dgeb"
      },
      "links": {
        "self": "http://example.com/people/9"
      }
    }, 
    {
      "type": "comments",
      "id": "5",
      "attributes": {
        "body": "First!"
      },
      "relationships": {
        "author": {
          "data": { "type": "people", "id": "2" }
        }
      },
      "links": {
        "self": "http://example.com/comments/5"
      }
    }
  ]

  // Optional
  // meta object can contain non standard meta-information (like pagination info)
  // must be object
  meta: {
    copyright: "Copyright 2015 Example Corp."
    authors: [
      "Steve Klabnik",
      "Dan Gebhardt",
      "Tyler Kellen"
    ]
  }
}

// Error response
{
  // An array of error objects
  errors: [

    // Erro may have any of the following members
    {
      id: ''
      links: {
        // A link that leads to further details about this particular occurence of the problem
        about: ''
      }
      // HTTP status code
      status: 415
      // Application specific error code
      code: ''
      // Human readeable summary
      title: ''
      // Human readeable explanation 
      detail: ''
      // an object containing references to the source of the error
      source: {
        // JSON pointer to associated entity
        pointer: '/data/attributes/title'
        // String indication which URI query parameter caused the error
        parameter: ''
      }
      // Meta object - can contain arbitrary data about the error
      meta: {
      }
    }
  ];
}