jsontypedef

jsontypedef

Syntactic sugar for creating JSON Type Definition (RFC 8927).

All types from Learn JSON Typedef in 5 Minutes are covered, preserving original naming with a few exceptions:

• enum is created via values(), because enum is a reserved keyword
• elements is created via array(), for brevity
• properties is called object(), for brevity
• discriminator is called match(), for brevity

Install

npm install jsontypedef

Example

Write:

import { string, number, object } from 'jsontypedef'

console.log(object({
  propertyA: string(),
  propertyB: object({
    innerPropertyC: number(),
  })
}))

Get:

{
  properties: {
    propertyA: { type: 'string' },
    propertyB: {
      properties: {
        innerPropertyC: { type: 'float64' }
      }
    }
  }
}

Saves you a good deal of typing maintaining big type definitions.

See all examples in the test suite.

API: Basic Types

• empty(metadata)
• boolean(metadata)
• string(metadata)
• timestamp(metadata)
• float64(metadata) (JavaScript numbers)
• number(metadata) # alias to float64()
• integer(metadata) # alias to float64()

API: Specialized Numeric Types

For compatibility with other languages and full JTD support:

• float32(metadata)
• int8(metadata)
• uint8(metadata)
• int16(metadata)
• uint16(metadata)
• int32(metadata)
• uint32(metadata)

API: Advanced Types

• values(items, metadata) is an alias to create the enum JTD form.
  • enum is a reserved word in JavaScript.
• array(type, metadata) creates the elements JTD form
• object(props, optional, additional) creates the properties JTD form
• match(field, mapping, metadata) creates the discriminator JTD form

API: Nullable Types

A nullable helper is provided for easily creating nullable rules.

const { nullable } = require('jsontypedef')

• nullable.empty(metadata)
• nullable.boolean(metadata)
• nullable.string(metadata)
• nullable.timestamp(metadata)
• nullable.float64(metadata) (JavaScript numbers)
• nullable.number(metadata) # alias to float64()
• nullable.integer(metadata) # alias to float64()
• nullable.float32(metadata)
• nullable.int8(metadata)
• nullable.uint8(metadata)
• nullable.int16(metadata)
• nullable.uint16(metadata)
• nullable.int32(metadata)
• nullable.uint32(metadata)
• nullable.values(items, metadata) is an alias to create the enum JTD form.
  • enum is a reserved word in JavaScript.
• nullable.array(type, metadata) creates the elements JTD form
• nullable.object(props, optional, additional) creates the properties JTD form

JSON Schema compatibility

Functionality-wise, JSON Type Definition is a subset of JSON Schema, with one exception: JSON Schema doesn't support tagged unions (the discriminator JTD form). There are no data constraints, so you can't say a string is supposed to have a length of 5, you can only say a string is a string.

Fastify uses ajv for validation and serialization, but only supports JSON Schema out of the box, although its addSchema() method could be reworked to recognize JTD in the future. Although ajv itself already supports JSON Type Definition, it might take a while for the support to come to Fastify.

That is not a problem because we can easily translate JTD schemas to JSON Schema with the jsonschema submodule provided by this library. which offers all methods from the main API but will output JSON Schema compatible schemas. So you can use it with Fastify:

import Fastify from 'fastify'
import { object, string } from 'jsontypedef/jsonschema'

const schema = {
  headers: object({
    'x-foo': string()
  }),
}

fastify.post('/the/url', { schema }, (req, reply) => {
  reply.send('ok')
})

The jsonschema submodule also includes number() and integer() for convenience.

See the full test suite for more usage examples.