Skip to content

Latest commit

 

History

History
332 lines (250 loc) · 9.99 KB

Readme.md

File metadata and controls

332 lines (250 loc) · 9.99 KB
Raw

Schema to Yup schema

Build a Yup schema from a JSON Schema, GraphQL schema (type definition) or any other similar type/class and field/properties model or schema :)

See Advanced config for all the more advanced configuration options available to customize this builder to support any of your requirements.

JSON schema

The builder currently supports the most commonly used JSON Schema layout

To support other schemas see Advanced config

Typescript and Typings

You can use the YupBuilderConfig and TypeHandlerConfig type interfaces to facilitate building up the config object to pass to the YupBuilder.

Quick start

Install

npm install schema-to-yup -S or yarn add schema-to-yup

Create a JSON schema to validate against

const schema = {
  $schema: "http://json-schema.org/draft-07/schema#",
  $id: "http://example.com/person.schema.json",
  title: "Person",
  description: "A person",
  type: "object",
  properties: {
    name: {
      description: "Name of the person",
      type: "string",
    },
    email: {
      type: "string",
      format: "email",
    },
    foobar: {
      type: "string",
      matches: "(foo|bar)",
    },
    age: {
      description: "Age of person",
      type: "number",
      exclusiveMinimum: 0,
      required: true,
    },
    characterType: {
      enum: ["good", "bad"],
      enum_titles: ["Good", "Bad"],
      type: "string",
      title: "Type of people",
      propertyOrder: 3,
    },
  },
  required: ["name", "email"],
};

Create a config object to configure details of your validation

const config = {
  // for error messages...
  errMessages: {
    age: {
      required: "A person must have an age",
    },
    email: {
      required: "You must enter an email address",
      format: "Not a valid email address",
    },
  },
};

Create the yup schema using the builder method buildYup

const { buildYup } = require("schema-to-yup");
const yupSchema = buildYup(schema, config);

Use the yup schema methods such as isValid to validate

// console.dir(schema)
const valid = await yupSchema.isValid({
  name: "jimmy",
  age: 24,
});

console.log({
  valid,
});
// => {valid: true}

The above example would generate the following sort of Yup validation schema:

const schema = yup.object().shape({
  name: yup.string().required(),
  age: yup.number().required().positive(),
  // ...
});

Refs

Please note that this library does not currently resolve $ref (JSON Pointers) out of the box. You can use another library for that.

You could f.ex use json-schema-ref-parser to preprocess your schema. Also see:

Mode

By default, any property will be explicitly notRequired unless set to be required, either via required: true in the property constraint object or via the required list of properties of the object schema definition (of the property).

You can override the notRequired behavior by setting it on the new mode object of the configuration which can be used to control and fine-tune runtime behaviour.

const jsonSchema = {
  title: "users",
  type: "object",
  properties: {
    username: { type: "string" },
  },
};
const yupSchema = buildYup(jsonSchema, {
  mode: {
    notRequired: true, // default setting
  },
});

// will be valid since username is not required by default
const valid = yupSchema.validateSync({
  foo: "dfds",
});
const yupSchema = buildYup(jsonSchema, {
  mode: {
    notRequired: true, // default setting
  },
});
// will be invalid since username is required by default when notRequired mode is disabled
const valid = yupSchema.validateSync({
  foo: "dfds",
});

The new run time mode settings are demonstrated under sample-runs/mode

No validation error (prop not required unless explicitly specified):

$ npx babel-node sample-runs/modes/not-required-on.js

Validation error if not valid type:

$ npx babel-node sample-runs/modes/not-required-on.js

Shape

You can access the internal Yup shape, via shapeConfig on the yup schema returned by the buildYup schema builder function. Alternatively simply call propsToShape() on the yup builder.

This allows you to easily mix and match to suit more advanced requirements.

const { buildYup } = require("json-schema-to-yup");
const { shapeConfig } = buildYup(json, config);
// alternatively
// const shape = buildYup(json, config).propsToShape()
const schema = yup.object().shape({
  ...shapeConfig,
  ...customShapeConfig,
});

Types

Currently the following schema types are supported:

  • array
  • boolean
  • date
  • number
  • object
  • string

Mixed (any type)

  • strict
  • default
  • nullable
  • const
  • required
  • notRequired
  • oneOf (enum, anyOf)
  • notOneOf
  • refValueFor for confirm password scenario
  • typeError custom type error message (in config)
  • when
  • isType
  • nullable (isNullable)

Reference constraints

Reference constraints within the schema can be defined as follows:

schema = {
  required: ["startDate", "endDate"],
  type: "object",
  properties: {
    startDate: {
      type: "number",
    },
    endDate: {
      type: "number",
      min: "startDate",
    },
  },
};

Internally this will be resolved using Yup.ref as documented here in the Yup readme.

ref allows you to reference the value of a sibling (or sibling descendant) field to validate the current field.

Yup.ref is supported in the Yup docs for the following:

Array

  • ensure
  • compact
  • items (of)
  • maxItems (max)
  • minItems (min)
  • itemsOf (of)

Boolean

No keys

Date

  • maxDate (max)
  • minDate (min)

Number

  • integer
  • moreThan (exclusiveMinimum)
  • lessThan (exclusiveMaximum)
  • positive
  • negative
  • min (minimum)
  • max (maximum)
  • truncate
  • round

Object

  • camelCase
  • constantCase
  • noUnknown (propertyNames)

String

  • minLength (min)
  • maxLength (max)
  • pattern (matches or regex)
  • email (format: 'email')
  • url (format: 'url')
  • lowercase
  • uppercase
  • trim

For pattern (RegExp) you can additionally provide a flags property, such as flags: 'i'. This will be converted to a RegExp using new RegExp(pattern, flags)

For the pattern constraint you can also pass in excludeEmptyString to exclude empty string from being evaluated as a pattern constraints.

Similar projects

The library JSON Schema model builder is a powerful toolset to build a framework to create any kind of output model from a JSON schema.

If you enjoy this declarative/generator approach, try it out!

Advanced config

See Advanced config

Testing

Uses jest for unit testing.

  • Have unit tests that cover most of the constraints supported.
  • Could use some refactoring using the latest infrastructure (see NumericConstraint)
  • Please help add more test coverage and help refactor to make this lib even more awesome :)

Development

A new version is under development at schema-to-yup-mono which is this code ported to a lerna monorepo with a cleaner, mode modular structure. More work needs to be done in terms of TDD and unit testing. Ideally this repo should be ported to Nx

Ideas and suggestions

Please feel free to come with ideas and suggestions on how to further improve this library.

Author

2018 Kristian Mandrup (CTO@Tecla5)