React Form Component Core

Core functionality for the form component. Contains logic for parsing higher level custom YAML DSL into JSON Schema using JSONSchema generating functions and logic for validating data against a JSONSchema configuration.

Installation

$ yarn add @firstaccess/form-component-core@beta6

The package can then be used as

import { parseSchema, validate } from '@firstaccess/form-component-core'

or

const { parseSchema, validate } = require('@firstaccess/form-component-core')

API

The core API is composed of:

• parseSchema
• validate

parseSchema

Recursively expands high level custom schema into standard JSONSchema and an associated uiSchema. The JSONSchema details what to render while the uiSchema details how to render.

The schema is an object that can either have a sections field, a section with properties field or a property with a type field. In addition, if the schema is an object with a sections property, it can additionally hold other fields that will be maintained in the parsed schema.

Usage

At the very base, a custom schema is an object which has properties, and each property has a type.

Here's a product_life property:

const product_life = {
    title: 'Product Life',
    description: 'How long have you been selling this product?',
    type: 'NumberField', // This key has to be `type`.
    thousand: '',
    validation: {
        minimum: 4,
        maximum: 20,
    },
};

And here is an example product schema that has a product_life:

const product_schema = {
    product_life
};

This schema can be parsed by parseSchema:

const parsedSchema = parseSchema(product_schema);

Which will evaluate to:

{
  "product_life": {
    "title": "Product Life",
    "description": "How long have you been selling this product?",
    "thousand": "",
    "symbol": "",
    "showErrors": false,
    "type": "number",
    "minimum": 4,
    "maximum": 20
  },
  "uiSchema": {
    "product_life": {
      "ui:field": "numberField"
    }
  }
}

This, and similar, basic schemas can be composed to form more complex schema. This composition is created by making subschemas properties of other schemas. For example, a schema section containing a consumer_products schema may be created as:

const consumer_products = {
    title: 'Customer Products',
    properties: { // This key has to  be `properties`
        product_life,
        price_schema: {
            title: 'Product Prices',
            type: 'NumberField'
        }
    }
}

const sections = {
    consumer_products
}

which can then be parsed to (elided)

{
  "consumer_products": {
    "properties": {
      "product_life": {
        "title": "Product Life",
        ...
        "type": "number",
      },
      "price_schema": {
        "title": "Product Prices",
        ...
        "type": "number"
      }
    },
    "type": "object",
    "title": "Customer Products"
  },
  "uiSchema": {
    "consumer_products": {
      "product_life": {
        "ui:field": "numberField"
      },
      "price_schema": {
        "ui:field": "numberField"
      }
    }
  }
}

Notice that the uiSchema follows the structure of the schemas properties

Multiple schemas can be added to sections to create a multi-section configuration schema.

const config = {
    sections: {
        consumer_products,
        demographic_information: {
            title: 'Demographic Information',
            properties: {
                age: {
                    type: 'NumberField'
                }
            }
        }
    }
}

The config can contain other keys apart from sections. However, those other keys will be passed along untouched and won't be processed. For anything to be processed, it has to be under sections. Other keys can be useful for providing invariant metadata about this config.

The above config parses down to:

{
  "sections": {
    "type": "object",
    "properties": {
      "consumer_products": {
        ... // same as above
        "type": "object",
        "title": "Customer Products"
      },
      "demographic_information": {
        "properties": {
          "age": {
            "symbol": "",
            "showErrors": false,
            "type": "number"
          }
        },
        "type": "object",
        "title": "Demographic Information"
      },
    }
    "uiSchema": {
      "consumer_products": {
        ...
      },
      "demographic_information": {
        "age": {
          "ui:field": "numberField"
        }
      }
    }
  }
}

For a list of fields to use under the unparsed schema type key, see these docs.

Validation rules vary from field to field. For a list of validation rules, see these docs.

The fields documentation contains information about what validation every field accepts.

For more information about defining a form configuration in YAML, consult this documentation.

validate

A thin wrapper around jsonschema validator.

Accepts the data and schema to validate that data against.

validate(data, schema)
// => { valid: <bool>, errors: <array> }

Returns an object with two keys:

• valid - a boolean indicating whether that data is valid or not
• errors - an array containing the errors for schema fields that failed validation. Empty array if validation passes.

In addition, it also performs error transformation to generate more readable errors. Error messages provided by the user in the schema take precedence over autogenerated errors during the transformation.

Usage

See jsonschema's documentation for usage examples.

User defined errors can be added to the schema config as detailed in the fields documentation.