5.0.0 • Published 7 years ago

aniame v5.0.0

Weekly downloads
3
License
MIT
Repository
github
Last release
7 years ago

Aniame

A simple JSON schema specification & utility.

npm version npm downloads build status coverage status

This README contains:

WARNING: This package does not comply with the IETF's JSON Schema drafts, although there are some similarities. If full compliance is what you're looking for, there's ajv, djv, and more.

JSON schema specification

To describe a JavaScript primitive or data structure (a resource) with an Aniame schema, we use small, nestable objects called descriptors.

For example, the following array:

['Homer', 'Marge', 'Bart', 'Lisa', 'Maggie']

Is described by the following schema:

{
  type: 'array',
  items: {
    type: 'string'
  }
}

Where both:

{
  type: 'array',
  items: ...
}

And:

{
  type: 'string'
}

Are descriptors.

Descriptors are JSON objects that have the following properties:

  • a required type property (either string, number, boolean, object, array or ref).
  • other required properties depending on the type.
  • an optional required property (must be a boolean).
  • any other property that you may want to add.

Objects

type: 'object'

Used to indicate that the resource should be a JSON object.

With objects, the descriptor must contain the properties property to describe what the object should contain. properties's value should be an object containing the descriptors of each expected property on the resource.

{
  type: 'object',
  properties: {
    address: {
      type: 'object',
      properties: {
        street: {
          type: 'string',
          required: true
        },
        number: {
          type: 'number'
        },
        city: {
          type: 'string'
        }
      }
    }
  }
}

The following object is valid under the above schema.

{
  address: {
    street: 'Evergreen Terrace',
    number: 742
  }
}

Arrays

type: 'array'

Used to indicate that the resource should be an array.

With arrays, the descriptor must contain the items property, whose value is itself the descriptor of the items of the array.

{
  type: 'object',
  properties: {
    nicknames: {
      type: 'array',
      required: false,
      items: {
        type: 'string'
      }
    }
  }
}

The following object is valid under the above schema.

{
  nicknames: ['Bart', 'El Barto']
}

References

type: 'ref'

Used to indicate that the resource should be a reference to another resource, itself compliant with this or another schema.

With type: 'ref', the descriptor must contain the ref property, whose value is a string, the name of the schema that the referenced resource should be compliant with.

References can be anything, as they will be validated by an optional, user-provided callback. If no callback is provided, Aniame will assume that the value is the referenced resource itself, and will validate it against the schema specified by the ref property.

{
  type: 'object',
  properties: {
    father: {
      type: 'ref',
      ref: 'person'
    },
    pets: {
      type: 'array',
      items: {
        type: 'ref',
        ref: 'animal'
      }
    }
  }
}

The following object is valid under the above schema.

{
  father: {
    // the full 'person' object
  },
  // alternatively, database IDs, or anything else
  pets: ['5abe33597d745c1992804194', '5afddf517195746608d181c5']
}

How to use

Installation

Just do:

npm install --save aniame

And then:

const Aniame = require('aniame');

Schema validation

Aniame.validateSchema(schema[, schemaNames])

This method checks that a schema is valid under the Aniame spec. It returns a boolean and receives the following parameters:

  • the schema, a JSON object.
  • optionally, schemaNames, an array of strings, the names of other schema definitions that can be referenced with type: 'ref'.

For example:

Aniame.validateSchema({
  type: 'object',
  properties: {
    nicknames: {
      type: 'array',
      required: false,
      items: {
        type: 'string'
      }
    }
  }
});

Will return true.

Resource validation

Aniame.validateResource(resource, schema[, schemas, enforceRequired, refCallback])

This asynchronous method checks that a value is valid under a given schema. It returns a Promise that resolves to an array and receives the following parameters:

  • the resource, the value to validate.
  • the schema, the Aniame schema to check the resource against. It can either be the full schema, or just the name of the schema, in which case the full schema will be pulled from schemas.
  • optionally, schemas, a JSON object. Each property on schemas should be the name of a specific schema, and its associated value should be the schema definition.
  • optionally, enforceRequired, a boolean to indicate whether to enforce required: true. The default is true.
  • optionally, refCallback(node, schemaName), an asynchronous function that will run on each type: 'ref' node. If it resolves to the keyword 'valid', the node is considered valid and the validation moves on. If it resolves to the keyword 'false', the node is considered invalid and the validation also moves on. If it resolves to anything else, or if no callback is provided, the node will be checked against the appropriate schema, pulled from schemas.

The resulting array contains the paths within the validated object where the validation failed. If the array is empty, the validation is successful.

For example:

const schemas = {
  person: {
    type: 'object',
    properties: {
      name: {
        type: 'string',
        required: true
      },
      email: {
        type: 'string',
        required: true
      },
      job: {
        type: 'ref',
        ref: 'job'
      }
    }
  },
  job: {
    type: 'object',
    properties: {
      company: {
        type: 'string',
        required: true
      },
      position: {
        type: 'string',
        required: true
      }
    }
  }
};

Aniame.validateResource({
  name: 'Homer Simpson',
  email: 45
}, 'person', schemas);

Will return a Promise that will resolve to:

[
  ['email']
]

Copyright & license

Copyright 2018 Ludovic Cyril Michel. Licensed under MIT.

5.0.0

7 years ago

4.0.0

7 years ago

3.0.0

7 years ago

2.0.0

7 years ago

1.3.0

7 years ago

1.2.3

7 years ago

1.2.2

7 years ago

1.2.1

7 years ago

1.2.0

7 years ago

1.1.0

7 years ago

1.0.0

7 years ago

0.1.1

7 years ago

0.1.0

7 years ago