ember-data / json-api-validator

[WIP] json-api validation utils for applications built with ember-data

@ember-data/json-api-validator

This package provides json-api validation utilities for applications built with ember-data.

ember-data expects users to normalize API payloads into json-api via serializers or other means before the data is pushed to the store. This is true for all requests, both manual and those made via "finders" such as query or findRecord.

Most obscure "why doesn't ember-data work" errors can be caught earlier with more clarity by using this package to validate the payloads given to the store.

Installation

ember install @ember-data/json-api-validator

Usage

This addon automatically hooks into the ember-data store and validates data pushed into it against the json-api spec taking into account available model definitions and ember-data quirks (member names must be camelCase, type must be singular and dasherized).

Unknown attributes and relationships are ignored by default; however, you can choose to warn or assert unknown attributes or relationships instead.

For relationships, it validates that synchronous relationships are indeed included when specified. You may choose to make this a warning instead.

For polymorphic associations, it validates that pushed types are indeed polymorphic sub-classes of the base type.

In addition to automatically adding validation to the store, this addon provides an additional validateJsonApiDocument method on the store. You may also import and use the individual validation methods to validate generic json-api payloads without the additional context of available Model schemas.

Contributing

Installation

• git clone <repository-url>
• cd @ember-data/json-api-validator
• yarn install

Linting

• yarn lint:js
• yarn lint:js --fix

Running tests

• ember test – Runs the test suite on the current Ember version
• ember test --server – Runs the test suite in "watch mode"
• ember try:each – Runs the test suite against multiple Ember versions

Running the dummy application

• ember serve
• Visit the dummy application at http://localhost:4200.

For more information on using ember-cli, visit https://ember-cli.com/.

License

This project is licensed under the MIT License.

json-api-validator's Issues

[FEAT] links validation

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'
         }
       }
    }
  }
}

[FEAT] typescript

Exposing Typings would significantly help us and help consumers of this library.

[FEAT] everything in lib should be stripped from prod builds

We should strip all code this library provides from production builds.

[QUEST] First Release!

Each of the below needs to be filled out and tested per spec. If you are working on one, claim it below and I will update the list with the person who has claimed it and the associated PR.

• validate document members
• validate meta
• validate jsonapi member
• validate links (#5)
• validate resources
  • validate type is correctly normalized and id is a string
  • validate attributes (warn for unknown, error for those that should be relationships, configurable error for missing attributes, error for missing attributes that are present as non-normalized members)
  • validate relationships (error for unknown, configurable error for missing relationships, error for missing relationships that are present as non-normalized members)
    • validate resource-identifiers only have type id and optional meta
    • validate type is correctly normalized, and a valid type (check polymorphic)
• validate absence of resource identifiers in data and included

Additional chores:

• Strip all code in production builds (#6)