Skip to content
/ json-schema-sugar Public

Create a JSON Schema without the pain of writing it 🍦

License

MIT license
20 stars 3 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

bjrmatos/json-schema-sugar

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
src
src
 
 
test
test
 
 
.babelrc
.babelrc
 
 
.editorconfig
.editorconfig
 
 
.eslintignore
.eslintignore
 
 
.eslintrc
.eslintrc
 
 
.flowconfig
.flowconfig
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
.npmignore
.npmignore
 
 
.npmrc
.npmrc
 
 
.tern-project
.tern-project
 
 
.travis.yml
.travis.yml
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
package.json
package.json
 
 
yarn.lock
yarn.lock
 
 

Repository files navigation

json-schema-sugar

NPM VersionLicenseBuild Status

Create a JSON Schema without the pain of writing it

This module let you write JSON Schemas v4 in a "sugar" way (using a chainable API). The API and style is stolen heavily inspired by Joi and Yup.

Usage

Define and create schema objects. Schema objects are immutable, so each call of a method returns a new schema object.

var sugar = require('json-schema-sugar');

var schema = sugar.object().keys({
  name: sugar.string().required(),
  age: sugar.number().integer().required(),
  email: sugar.string(),
  website: sugar.string()
});

var jsonSchema = schema.generate({
  name: 'jimmy',
  age: 24
});

console.log(jsonSchema);

Output:

{
  type: 'object',
  properties: {
    name: {
      type: 'string'
    },
    age: {
      type: 'integer'
    },
    email: {
      type: 'string'
    },
    website: {
      type: 'string'
    }
  },
  required: ['name', 'age']
}

API

sugar

The module export.

var sugar = require('json-schema-sugar');

sugar.mixed // also aliased as sugar.any
sugar.nullable
sugar.string
sugar.number
sugar.boolean
sugar.object
sugar.array

mixed

Creates a schema that matches a general type. All types inherit from this base type

var schema = sugar.mixed();
schema.generate();
// => {}

mixed.clone(): Schema

Creates a deep copy of the schema. Clone is used internally to return a new schema with every schema state change (making schema instances inmutable).

mixed.title(title: string): Schema

Adds a title in the schema.

mixed.description(description: string): Schema

Adds a description in the schema.

mixed.default(default: any): Schema

Adds a default value in the schema.

mixed.meta(field: string | object, value: ?any): Schema Alias: extra

Adds custom fields to the schema, multiple calls to .meta will accumulate data with previous calls.

With field:

var schema = sugar.object().keys({
  name: sugar.string().required().meta('example', 'Bob').meta('isMain', true),
});

schema.generate();

Output:

{
  type: 'object',
  properties: {
    name: {
      type: 'string',
      example: 'Bob',
      isMain: true
    }
  }
}

With an Object:

var schema = sugar.object().keys({
  name: sugar.string().required().meta({ example: 'Bob', isMain: true }),
});

schema.generate();

Output:

{
  type: 'object',
  properties: {
    name: {
      type: 'string',
      example: 'Bob',
      isMain: true
    }
  }
}

mixed.enum(values: Array<any>): Schema

Restricts a value in the schema to a fixed set of values.

mixed.required(): Schema

When used inside an object schema specifies that a property is required.

var schema = sugar.object().keys({
  name: sugar().string().required(),
  email: sugar().string().required(),
  address: sugar.string()
});

schema.generate();

Output:

{
  type: 'object',
  properties: {
    name: {
      type: 'string'
    },
    email: {
      type: 'string'
    },
    address: {
      type: 'string'
    }
  },
  required: ['name', 'email']
}

mixed.requiredWhen(dependantProp: string | Array<string>): Schema

When used inside an object schema specifies that a property must be present (required) when another property/properties are present, making a property dependency. dependantProp can be an array of strings, or multiple strings can be passed as individual arguments.

var schema = sugar.object().keys({
  name: sugar.string().required(),
  creditCard: sugar.number(),
  billingAddress: sugar.string().requiredWhen('creditCard', 'name'),
  billingDistrict: sugar.string().requiredWhen('creditCard')
});

schema.generate();

Output:

{
  type: 'object',
  properties: {
    name: {
      type: 'string'
    },
    creditCard: {
      type: 'number'
    },
    billingAddress: {
      type: 'string'
    },
    billingDistrict: {
      type: 'string'
    }
  },
  required: ['name'],
  dependencies: {
    creditCard: ['billingAddress', 'billingDistrict'],
    name: ['billingAddress']
  }
}

mixed.when(dependantProp: string | Array<string>): Schema

When used inside an object schema specifies that when a property is present the schema should be different, making a schema dependency. dependantProp can be an array of strings, or multiple strings can be passed as individual arguments.

var schema = sugar.object().keys({
  name: sugar.string(),
  creditCard: sugar.number(),
  billingAddress: sugar.mixed().when('creditCard', sugar.string().required())
});

schema.generate();

Output:

{
  type: 'object',
  properties: {
    name: {
      type: 'string'
    },
    creditCard: {
      type: 'number'
    }
  },
  dependencies: {
    creditCard: {
      properties: {
        billingAddress: {
          type: 'string'
        }
      },
      required: ['billingAddress']
    }
  }
}

mixed.definitions(definitions: object): Schema

Adds definitions to the schema, definitions are standardized placeholder in which you can define inline subschemas to be used in a schema.

var schema = sugar.object().keys({
  billingAddress: sugar.any().ref('#/definitions/address')
}).definitions({
  address: sugar.object().keys({
    streetAddress: sugar.string().required(),
    city: sugar.string().required(),
    state: sugar.string().required()
  })
});

schema.generate();

Output:

{
  type: 'object',
  properties: {
    billingAddress: {
      $ref: '#/definitions/address'
    }
  },
  definitions: {
    address: {
      type: 'object',
      properties: {
        streetAddress: {
          type: 'string'
        },
        city: {
          type: 'string'
        },
        state: {
          type: 'string'
        }
      },
      required: ['streetAddress', 'city', 'state']
    }
  }
}

mixed.allOf(schemas: Array<Schema>): Schema

Adds a restriction that the given data must be valid against all of the given subschemas.

var schema = sugar.mixed().allOf([
  sugar.string(),
  sugar.string().minLength(2),
  sugar.string().maxLength(5)
]);

Output:

{
  allOf: [{
    type: 'string'
  }, {
    minLength: 2
  }, {
    maxLength: 5
  }]
}

mixed.anyOf(schemas: Array<Schema>): Schema

Adds a restriction that the given data must be valid against any (one or more) of the given subschemas.

var schema = sugar.mixed().anyOf([
  sugar.string().maxLength(5),
  sugar.number().minimum(0)
]);

Output:

{
  anyOf: [{
    type: 'string',
    maxLength: 5
  }, {
    type: 'number',
    minimum: 0
  }]
}

mixed.oneOf(schemas: Array<Schema>): Schema

Adds a restriction that the given data must be valid against exactly one of the given subschemas.

var schema = sugar.mixed().oneOf([
  sugar.number().multipleOf(3),
  sugar.number().multipleOf(5)
]);

Output:

{
  oneOf: [{
    type: 'number',
    multipleOf: 3
  }, {
    type: 'number',
    multipleOf: 5
  }]
}

mixed.not(schema: Schema): Schema

Declares that a instance validates if it doesn’t validate against the given subschema.

var schema = sugar.mixed().not(sugar.string());

Output:

{
  not: {
    type: 'string'
  }
}

mixed.noType(): Schema

Declares that a schema should not include the type property in the output.

var schema = sugar.number().multipleOf(5).noType();

Output:

{
  multipleOf: 5
}

mixed.canBe(type: Schema | Array<Schema>): Schema

Specify multiple types for a schema. type can be an array of schemas, or multiple schemas can be passed as individual arguments. This method is only available to mixed schemas (schemas created directly with sugar.mixed())

var schema = sugar.mixed().canBe(sugar.string(), sugar.number());
schema.generate();
// => { type: ['string', 'number'] }

mixed.ref(refUri: string): Schema

Creates a reference to a schema located in refUri. This method is only available to mixed schemas (schemas created directly with sugar.mixed())

var schema = sugar.object().keys({
  billingAddress: sugar.any().ref('#/definitions/address'),
  shippingAddress: sugar.any().allOf([
    sugar.any().ref('#/definitions/address'),
    sugar.object().keys({
      type: sugar.any().enum(['residential', 'business']).required()
    })
  ])
}).definitions({
  address: sugar.object().keys({
    streetAddress: sugar.string().required(),
    city: sugar.string().required(),
    state: sugar.string().required()
  })
});

Output:

{
  type: 'object',
  properties: {
    billingAddress: {
      $ref: '#/definitions/address'
    },
    shippingAddress: {
      allOf: [{
        $ref: '#/definitions/address'
      }, {
        properties: {
          type: {
            enum: ['residential', 'business']
          }
        },
        required: ['type']
      }]
    }
  },
  definitions: {
    address: {
      type: 'object',
      properties: {
        streetAddress: {
          type: 'string'
        },
        city: {
          type: 'string'
        },
        state: {
          type: 'string'
        }
      },
      required: ['streetAddress', 'city', 'state']
    }
  }
}

mixed.generate(options: ?object): string

Generates a JSON Schema based on the constructed schema.

The options (optional) argument is an object hash and can contain the following properties:

options = {
  obj: boolean = false,
  removeType: boolean = false,
  space: ?number = undefined,
  $schema: ?string = undefined,
  id: ?string = undefined
};
  • obj: return the JSON Schema as object instead of string.
  • removeType: don't include the type property in the JSON Schema.
  • space: Specifies the space option for JSON.stringify, adding the ability to return the json string with white space.
  • $schema: Specifies a custom $schema entry in the JSON Schema.
  • id: Specifies an id entry in the JSON Schema.

nullable

Creates a schema that matches a null type. Supports all the same methods as mixed.

var schema = sugar.nullable();
schema.generate();
// => { type: 'null' }

boolean

Creates a schema that matches a boolean type. Supports all the same methods as mixed.

var schema = sugar.boolean();
schema.generate();
// => { type: 'boolean' }

number

Creates a schema that matches a number type. Supports all the same methods as mixed.

var schema = sugar.number();
schema.generate();
// => { type: 'number' }

number.integer(): Schema

Defines that the schema should be an integer.

var schema = sugar.number().integer();
schema.generate();

Output:

{
  type: 'integer'
}

number.multipleOf(value: number): Schema

Defines that the schema should be multiple of value.

var schema = sugar.number().multipleOf(3);
schema.generate();

Output:

{
  type: 'number',
  multipleOf: 3
}

number.minimum(value: number): Schema

Defines that the schema should be a minimum numeric value.

var schema = sugar.number().minimum(5);
schema.generate();

Output:

{
  type: 'number',
  minimum: 5
}

number.maximum(value: number): Schema

Defines that the schema should be a maximum numeric value.

var schema = sugar.number().maximum(10);
schema.generate();

Output:

{
  type: 'number',
  maximum: 10
}

number.exclusiveMinimum(value: boolean): Schema

When value is true, it indicates that the range excludes the minimum value, i.e., x > minx > min. When false (or not included), it indicates that the range includes the minimum value, i.e., x ≥ minx ≥ min.

var schema = sugar.number().minimum(5).exclusiveMinimum(true);
schema.generate();

Output:

{
  type: 'number',
  minimum: 5,
  exclusiveMinimum: true
}

number.exclusiveMaximum(value: boolean): Schema

When value is true, it indicates that the range excludes the maximum value, i.e., x < maxx <max. When false (or not included), it indicates that the range includes the maximum value, i.e., x ≤ maxx ≤ max.

var schema = sugar.number().maximum(10).exclusiveMaximum(true);
schema.generate();

Output:

{
  type: 'number',
  maximum: 10,
  exclusiveMaximum: true
}

string

Creates a schema that matches a string type. Supports all the same methods as mixed.

var schema = sugar.string();
schema.generate();
// => { type: 'string' }

string.minLength(value: number): Schema

Defines that a string should have a minimum length of value.

var schema = sugar.string().minLength(2);
schema.generate();

Output:

{
  type: 'string',
  minLength: 2
}

string.maxLength(value: number): Schema

Defines that a string should have a maximum length of value.

var schema = sugar.string().maxLength(8);
schema.generate();

Output:

{
  type: 'string',
  maxLength: 8
}

string.pattern(pattern: string | RegExp): Schema

Defines that a string should satisfies a pattern.

var schema = sugar.string().pattern(/abc/);
schema.generate();

Output:

{
  type: 'string',
  pattern: 'abc'
}

string.format(format: string): Schema

Defines a format for the string. format can be any standardized format like date-time, email, etc.

var schema = sugar.string().format('email');
schema.generate();

Output:

{
  type: 'string',
  format: 'email'
}

object

Creates a schema that matches a object type. Supports all the same methods as mixed.

var schema = sugar.object().keys({
  name: sugar.string()
});

schema.generate();
// => { type: 'object', properties: { name: { type: 'string' } } }

object.keys(properties: object): Schema

Defines properties for the object. Each key in the properties hash object must have a Schema as value.

var schema = sugar.object().keys({
  foo: sugar.boolean(),
  value: sugar.number(),
  address: sugar.string(),
  unknown: sugar.nullable()
});

schema.generate();

Output:

{
  type: 'object',
  properties: {
    foo: {
      type: 'boolean'
    },
    value: {
      type: 'number'
    },
    address: {
      type: 'string'
    },
    unknown: {
      type: 'null'
    }
  }
}

object.additionalProperties(value: boolean | Schema): Schema

Defines if an object can have additional properties or not. If value is a Schema then all additional properties must be valid against the given schema.

var schema = sugar.object().keys({
  foo: sugar.boolean(),
  value: sugar.number(),
  address: sugar.string(),
  unknown: sugar.nullable()
}).additionalProperties(sugar.string());

schema.generate();

Output:

{
  type: 'object',
  properties: {
    foo: {
      type: 'boolean'
    },
    value: {
      type: 'number'
    },
    address: {
      type: 'string'
    },
    unknown: {
      type: 'null'
    }
  },
  additionalProperties: {
    type: 'string'
  }
}

object.patternProperties(value: object): Schema

Defines that if there is any property in an object that match a given pattern, that property must be valid against a schema.

Each key in the value hash object must have a Schema as value.

var schema = sugar.object().keys({
  foo: sugar.boolean(),
  value: sugar.number(),
  address: sugar.string(),
  unknown: sugar.nullable()
}).patternProperties({
  '^S_': sugar.string(),
  '^I_': sugar.number().integer()
});

schema.generate();

Output:

{
  type: 'object',
  properties: {
    foo: {
      type: 'boolean'
    },
    value: {
      type: 'number'
    },
    address: {
      type: 'string'
    },
    unknown: {
      type: 'null'
    }
  },
  patternProperties: {
    '^S_': {
      type: 'string'
    },
    '^I_': {
      type: 'integer'
    }
  }
}

object.minProperties(value: number): Schema

Defines that an object should have a minimum number of properties.

var schema = sugar.object().keys({
  foo: sugar.boolean(),
  value: sugar.number(),
  address: sugar.string(),
  unknown: sugar.nullable()
}).minProperties(2);

schema.generate();

Output:

{
  type: 'object',
  properties: {
    foo: {
      type: 'boolean'
    },
    value: {
      type: 'number'
    },
    address: {
      type: 'string'
    },
    unknown: {
      type: 'null'
    }
  },
  minProperties: 2
}

object.maxProperties(value: number): Schema

Defines that an object should have a maximum number of properties.

var schema = sugar.object().keys({
  foo: sugar.boolean(),
  value: sugar.number(),
  address: sugar.string(),
  unknown: sugar.nullable()
}).maxProperties(3);

schema.generate();

Output:

{
  type: 'object',
  properties: {
    foo: {
      type: 'boolean'
    },
    value: {
      type: 'number'
    },
    address: {
      type: 'string'
    },
    unknown: {
      type: 'null'
    }
  },
  maxProperties: 3
}

array

Creates a schema that matches a array type. Supports all the same methods as mixed.

var schema = sugar.array().items(sugar.number());
schema.generate();
// => { type: 'array', items: { type: 'number' } }

array.items(items: object | Schema | Array<Schema>): Schema

When items is an object or Schema specifies that all items in an array must be valid against the given schema. When items is an array specifies that items in an array must be valid and appear in the same order of the given schemas (tuple validation).

var schema = sugar.array().items({
  name: sugar.string(),
  email: sugar.string()
});

schema.generate();

Output:

{
  type: 'array',
  items: {
    type: 'object',
    properties: {
      name: {
        type: 'string'
      },
      email: {
        type: 'string'
      }
    }
  }
}

Tuple example:

var schema = sugar.array().items([
  sugar.number(),
  sugar.string()
]);

schema.generate();

Output:

{
  type: 'array',
  items: [{
    type: 'number'
  }, {
    type: 'string'
  }]
}

array.additionalItems(value: boolean): Schema

Defines if an array can have additional items or not.

var schema = sugar.array().items([
  sugar.string(),
  sugar.number()
]).additionalItems(false);

schema.generate();

Output:

{
  type: 'array',
  items: [{
    type: 'string'
  }, {
    type: 'number'
  }],
  additionalItems: false
}

array.minItems(value: number): Schema

Defines that an array should have a minimum number of items.

var schema = sugar.array().items({
  value: sugar.number()
}).minItems(2);

schema.generate();

Output:

{
  type: 'array',
  items: {
    type: 'object',
    properties: {
      value: {
        type: 'number'
      }
    }
  },
  minItems: 2
}

array.maxItems(value: number): Schema

Defines that an array should have a maximum number of items.

var schema = sugar.array().items({
  value: sugar.number()
}).maxItems(2);

schema.generate();

Output:

{
  type: 'array',
  items: {
    type: 'object',
    properties: {
      value: {
        type: 'number'
      }
    }
  },
  maxItems: 2
}

array.uniqueItems(value: boolean): Schema

Defines that items in an array should be unique.

var schema = sugar.array().items({
  value: sugar.number()
}).uniqueItems(true);

schema.generate();

Output:

{
  type: 'array',
  items: {
    type: 'object',
    properties: {
      value: {
        type: 'number'
      }
    }
  },
  uniqueItems: true
}

About

Create a JSON Schema without the pain of writing it 🍦

Topics

json-schema json-schema-sugar schema-objects

Resources

Readme

License

MIT license
Activity

Stars

20 stars

Watchers

6 watching

Forks

3 forks
Report repository

Releases

3 tags

Packages

No packages published

Languages