[FEAT] links validation

[runspired]

An overview of things to validate.

Generic

• links is an object if present
• links has at least one member
• links only contains members that are strings or link objects.

Link Objects

• link objects MUST contain href // note the spec is too vague and could mean that either href or meta must be present, cc @dgeb
• link objects MAY contain meta
• link object contain no other members

Pagination Links

reach goal: if any of these is present then data for the document or relationship MUST be an array if present.

• If any of the below is present, all MUST be present.
• first MUST be null, a string, or a link object
• last MUST be null, a string, or a link object
• prev MUST be null, a string, or a link object
• next MUST be null, a string, or a link object

Document Links

• document links MAY contain pagination-links
• document links MAY contain self
• document links MAY contain related (when the document is for a relationship)
• no other members // spec implies but does not outright say this

Resource Links

• resource links MUST contain self // note: again, vague spec. Nothing else is described but self is described as a MAY. We are going to be more strict: if you define links for a resource it MUST be self
• no other members // spec implies but does not outright say this

Relationship Links

• relationship links MAY contain pagination-links if for a collection // we should warn for this though as ember-data cannot use them (yet)
• relationship links MAY contain self // ember-data does not use this
• relationship links MUST contain related // note: ember-data only uses this, so we upgrade to a MUST from a MAY
• no other members // spec implies but does not outright say this

Spec Info

Document Links

Document links have self with is a string or a links object (href + optional meta).
They appear at the same level as the primary document (e.g. alongside the data included meta members). Documents that contain collections (data is an array) may also have pagination links.

• http://jsonapi.org/format/#document-links
• http://jsonapi.org/format/#fetching-pagination

example:

{
  data: [],
  links: { self: 'https://api.example.com/foos' }
}

Resource Links

Resource links have the same rules as document links, and appear at the top level of the resource. e.g. alongside type id attributes and relationships. Resources cannot have pagination links.

example:

{
  data: {
    type: 'foo',
    id: '1',
    attributes: {},
    links: { self: 'https://api.example.com/foos/1' }
  }
}

Relationship Links

Relationship links appear within the Relationship Object. They have more requirements than document and resource links. The related link is the most important aspect that is different. Relationships that represent collections may have pagination links. In ember-data we currently only utilize the related link. This is actually a bug, because we should fall back to the self link when related is not present and error if links is present without either.

• http://jsonapi.org/format/#document-resource-object-relationships
• http://jsonapi.org/format/#fetching-pagination

{
  data: {
    type: 'foo',
    id: '1',
    relationships: {
       bars: {
         data: [],
         links: {
           related: 'https://api.example.com/foos/1/bars'
         }
       }
    }
  }
}