Graph Validation

When using nodes in the graph editor, the user needs quick validation that input fields have correctly set values or have the correct number of incoming links. Graph validation occurs whenever a user previews or stages a graph. Error notifications for fields that fail validation are presented in the UI so the user can make appropriate changes.

Graphs are validated against a set of validation rules that are specified in the node schema for the channel. Validation is performed by a function that takes a graph as input, compares it against the validation rules in the schema and reports any validation errors.

The rules for validation are derived from a subset of the 2020-12 draft of JSON Schema format rules plus additional capabilities that are Rendered.ai specific. The rules validate node inputs (values and links). Rules are specified via the “validation” keyword in the schema.

Here is an example of how input validation rules are implemented in the schema:

CODE

schemas:
  PlaceCars:
    inputs:
    - name: Number
      description: Number of cars to place
      default: 5
      validation:
        type: integer

The above schema defines a node called “PlaceCars” which has one input field called “Number”. The validation rule for the “Number” field is specified under the “validation” keyword.

The validation rule is a “type” rule as indicated by the “type” keyword. This rule specifies that the field requires an input value of data type “integer”.

If the user enters anything other than an integer in the “Number” field and then attempts to stage or preview the graph, then the GUI will highlight the field and indicate that it contains an invalid value.

Rule Categories

All validation rules have a category. The category is indicated by use of a specific keyword in the rule. Currently there are three rule categories.

type - A type rule specifies that the field must be of a certain data type. A type rule is indicated by use of the “type” keyword.
number-of-links - A number-of-links rule specifies that the field must have a certain number of input links attached to it. A number-of-links rule is indicated by the “numLinks” keyword.
compound - A compound rule specifies that multiple rules must be evaluated to determine field validity. Compound rules apply a logic operation to a list of rules. A compound rule is indicated by use of one of the following keywords: “oneOf” (exclusive or), “anyOf” (or), “allOf” (and), and “noneOf” (not).

Note that since fields will often allow either a value to be entered or an input link to be attached, many rules will be compound using the “oneOf” keyword, e.g. a field can have either an input value of a certain type or it can have an input link attached to it. See <typical use cases> for more details.

Type Rules

A type rule specifies that the field must contain a value of a certain data type. A type rule is indicated by use of the “type” keyword. A type rule can optionally include type-specific qualifiers. Here’s the format of a type rule:

CODE

type: <data-type>
<type-specific-qualifier-1>
<type-specific-qualifier-2>
...

The <data-type> is a string that specifies the name of the data type to be matched by the rule. Currently the following data types are supported:

type	description
string	string of text
number	a numeric value that can be either an integer or a float
integer	a numeric value that must be an integer
array	zero, one, or more ordered elements, separated by a comma and surrounded by square brackets [ ]
boolean	true or false
null	null value

String Type

The string type is used for strings of text. Note the string type will match any string of text including numeric strings so be careful when using the string type in a compound rule.

Length

The length of a string can be constrained using the “minLength” and “maxLength” type-specific qualifiers.

Here is an example of a string validation rule using length qualifiers:

CODE

validation:
  type: string
  minLength: 1
  maxLength: 20

The above example specifies that the field must be of data type “string” and that it has a minimum length of 1 and a maximum length of 20. If the user enters an empty string or a string that is longer than 20 characters then the field will be invalid.

Format

The “format” keyword allows for basic semantic identification of certain kinds of string values that are commonly used.

Currently only one built-in format from the JSON Schema spec is supported:

"uri": A universal resource identifier (URI), according to RFC3986.

Here is an example of a string rule with the format qualifier

CODE

validation:
  type: string
  format: uri

In this example, the field must contain a string that is in URI format.

Numeric Types

Two numeric types are supported - “number” and “integer”.

The “number” type is used for any numeric type, either integers or floating point numbers.

The “integer” type is used for integral numbers that do not have a fractional portion.

Range

Ranges of numbers are specified using a combination of the “minimum” and “maximum” keywords, (or “exclusiveMinimum” and “exclusiveMaximum” for expressing exclusive range).

If x is the value being validated, the following must hold true:

x ≥ minimum
x > exclusiveMinimum
x ≤ maximum
x < exclusiveMaximum

Here is an example of a numeric rule:

CODE

validation:
  type: integer
  minimum: 0
  maximum: 255

In this example, the field must contain an integer value greater than or equal to 0 and less than or equal to 255.

Array Type

The “array” type is for an ordered sequence of elements. An array contains zero, one, or more ordered elements, separated by a comma and surrounded by square brackets [ ].

Length

The length of the array can be specified using the “minItems” and “maxItems” qualifiers.

Here is example of an array rule:

CODE

validation:
  type: array
  minItems: 3
  maxItems: 3

In this example, the field must contain an array of length 3. Note item validation is not specified so items may be of any data type.

Item validation

There are two mechanisms for validating the individual items within an array - list validation and tuple validation. These are described below.

List validation

The list validation option is useful for arrays of arbitrary length where each item matches the same rule. For this kind of array, set the “items” keyword to a single rule that will be used to validate all of the items in the array.

Here is the schema for a filed that is an array of red, green, and blue color values, each ranging from 0-255:

CODE

schemas:
  ChangeColor:
    inputs:
    - name: rgb
      description: The red, green, and blue values specified as an array
      validation:
        type: array
        items:
          type: integer
          minimum: 0
          maximum: 255
        minItems: 3
        maxItems: 3

Tuple validation

Tuple validation is useful when the array is a collection of items where each has a different rule and the ordinal index of each item is meaningful.

The “prefixItems” keyword indicates tuple validation is to be used. The “prefixItems” is an array, where each item is a rule that corresponds to each index of the document’s array. That is, an array where the first element validates the first element of the input array, the second element validates the second element of the input array, etc.

Here is an example of tuple validation for an array that contains red, green, and blue which are integers ranging 0-255, and an alpha value which is a number ranging from 0-1.0.

CODE

schemas:
  ChangeColor:
    inputs:
    - name: rgba
      description: The red, green, blue, and alpha values specified as an array
      validation:
        type: array
        prefixItems:
        - type: integer
          minimum: 0
          maximum: 255
        - type: integer
          minimum: 0
          maximum: 255
        - type: integer
          minimum: 0
          maximum: 255
        - type: number
          minimum: 0
          maximum: 1.0

Note the “minItems” and “maxItems” keywords do not apply to tuple validation as it must contain the exact number of elements as specified in the “prefixItems”.

Boolean Type

The “boolean” type matches only two special values: true and false. Note that values that evaluate to true or false, such as 1 and 0, are not accepted by the rule.

Null Type

The “null” type matches the JSON null special value. Note that although graphs support null values, there is currently no mechanism for specifying a null in the GUI. However null can be specified as a default value value for a field.

Number-of-links rules

A number-of-links rule specifies that the field must have a certain number of input links attached to it. A number-of-links rule is indicated by the “numLinks” keyword.

The number of links allowed is indicated by the following:

zero - no links
zeroOrOne - zero or one link
zeroOrMany - zero or many links
one - exactly one link
oneOrMany - one or many links

Note that although all of these are supported for completeness, a typical number-of-links rule will use either “one” or “oneOrMany”.

Here is an example of a number-of-links rule:

CODE

validation:
  numLinks: one

The above rule specifies that the field must be connected to exactly one link.

Composite rules

The validation spec includes a few keywords for combining rules together. These keywords correspond to the boolean algebra concepts AND, OR, XOR, and NOT. You can use these keywords to express complex constraints that can’t otherwise be expressed with standard validation keywords.

The keywords used to combine rules are:

allOf: (AND) Must be valid against all of the rules
anyOf: (OR) Must be valid against any of the rules
oneOf: (XOR) Must be valid against exactly one of the rules

All of these keywords must be set to an array, where each item is a rule.

In addition, there is:

not: (NOT) Must not be valid against the given rule

Note that although all of these are rules supported for completeness, a typical compound rule will use the “oneOf” keyword.

Here is an example of a composite rule:

CODE

validation:
  oneOf:
    - type: integer
    - numLinks: one

In this example, the field must either contain an integer value or it must be connected to exactly one link.