Schema

The schema section of the content describes the relationship between the view and the data. It breaks down properties of the model’s object into data-types, each with their own spot for validation, formatting, or default-values.

Structure

The root of the data object uses the ROOT keyword in the schema:

{
  "ROOT": {
    "myProperty1": {
      "type": "MyCustomType"
    }
  }
}

This describes a myProperty1 key on the data-model which corresponds to a type of MyCustomType. Structural data-types can be added to the schema as a sibling to ROOT and are referenced by name from the previous type.

To add a name property to the myProperty1 example:

{
  "ROOT": {
    "myProperty1": {
      "type": "MyCustomType"
    }
  },
  "MyCustomType": {
    "name": {
      "type": "StringType"
    }
  }
}

Now the path myProperty1.name in the model points to a StringType. There are a number of basic built-in core types, like StringType, that provide a base set of formatting/validation/default value support out of the box. Read more about those below.

Data Types

A DataType is a collection of the validation rules, formatting, and default values for a given path in the model. See the above structure docs on how to author these in JSON content.

As in the above StringType example, there are a number of pre-existing base types that can be utilized in the schema to describe a data type, and an extension mechanism for supplying additional base-types for use in the authored content. See the types-provider-plugin for an easy way to extend these.

For any given path described by the schema, Player will merge the rules defined by the base type (if one exists), and the rules defined specifically for that path in the authored content. Any custom formatter/default values take precedence over the default ones, and any custom validations are ran before the base ones.

Check out the CommonTypes plugin for a list of easy to consume DataTypes for your application.

Arrays

Sometimes the data you’re using represents an array or list of things. To indicate this in the schema add a isArray: true property to the reference of the top level array. For example, if the data you’re representing looks like:

{
  "pets": [
    {
      "name": "Frodo",
      "type": "cat"
    },
    {
      "name": "Ginger",
      "type": "dog"
    }
  ]
}

the corresponding schema would be:

{
  "ROOT": {
    "pets": {
      "type": "PetType",
      "isArray": true
    }
  },
  "PetType": {
    "name": {
      "type": "StringType"
    },
    "type": {
      "type": "StringType"
    }
  }
}

Each item in the array will be formatted/validated using the same rule-set.

Validation

To attach a validation to a path in the data-model, add a reference to a validator in the data-type definition for that path under a validation property:

{
  "MyCustomType": {
    "name": {
      "type": "StringType",
      "validation": [
        {
          "type": "length",
          "max": 20,
          "min": 5
        }
      ]
    }
  }
}

Each validation reference must include a type property which corresponds to the name of the validator to run. Player includes some validators out-of-the-box, and custom validators can be registered as well. See the Common Types Plugin docs for more details around which validators are supported, and how to add custom ones.

Any additional properties on the validation reference are passed as options to the validator. In the example above, a hypothetical length validator can take a min and max as the boundaries for the length of a string.

Formatting

Similar to adding validations, formatting is added to a data-type through a reference to a formatter.

{
  "MyCustomType": {
    "name": {
      "type": "NumberType",
      "format": {
        "type": "commaNumber",
        "decimalPlaces": 3
      }
    }
  }
}

Just like in validations, the type of the formatter corresponds to the name of a formatter to use (commaNumber in this case). This hypothetical commaNumber formatter would be responsible for translating the data stored in the model to/from what’s displayed to the user. Any additional properties on the format object get passed to the respective formatter function as options. In the above example, the options would include { decimalPlaces: 3 }.

Custom formatters can be registered with Player, and thus exposed for use within the authored content.

The transition from the data stored in the model to the user is considered formating where the inverse (what a user sees to the model is deformatting). Not every formatter has a handler for both formatting and deformatting, and it’s entirely up the formatter to define the requirements for data handling in these scenarios.

Read more about formatting here

Default Value

Any schema or data type can supply a default value to use when setting or getting the value from the data-model. Simply supply the default property in either the type reference in the schema or the base type definition. Any read from a binding with a default property will return it’s default if the underlying model’s value is undefined. Note: Reading a value (and it’s default) will not set the value in the model to it’s default. The exception to this rule is for bindings that are tracked for validations.