Replicant Validation

As of 0.8.4, bundle authors may define an optional schema for the Replicants in their bundle. If present, NodeCG will validate every change made to the Replicant against this schema. If any change fails validation, either on the server or on the client, an error will be synchronously thrown.

All schemas are in the JSON Schema format. To add a schema to a Replicant, create a .json file with the same name as your Replicant in your bundle's schemas folder. For example, if my-bundle has a Replicant called foo, the schema would be located at nodecg/bundles/my-bundle/schemas/foo.json. NodeCG will automatically see and load this schema on startup. Changes to the schema require restarting NodeCG.

If a Replicant's schema has defaults defined, NodeCG will use those defaults to automatically build a defaultValue for the Replicant. This auto-generated defaultValue is overridden by any defaultValue that is provided during Replicant declaration.

If for any reason a Replicant's persisted value becomes invalid, NodeCG will discard this value on startup.

Example

nodecg/bundles/my-bundle/schemas/foo.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "bar": {
      "type": "string",
      "description": "The value of bar, which is a String.",
      "default": "hello world"
    },
    "baz": {
      "type": "number",
      "description": "The value of baz, which is a Number.",
      "default": 0
    }
  },
  "required": ["bar", "baz"]
}

nodecg/bundles/my-bundle/extension.js

module.exports = function (nodecg) {
  // We don't need to specify a `defaultValue` here, it will be automatically generated from the defaults
  // in the schema.
  const foo = nodecg.Replicant('foo');

  /* You can override this by specifying your own `defaultValue` when declaring the Replicant.
  const foo = nodecg.Replicant('foo', {
    defaultValue: {
      bar: "hi",
      baz: 5
    }
  }); */

  console.log(foo.value.bar); //=> "hello world"
  console.log(foo.value.baz); //=> 0

  foo.value.bar = "greetings planet"; // Valid change, no error will be thrown.
  foo.value.baz = "this should be a number!"; // Invalid change, an error will be thrown.
};

Example#

Example