Constraints

System level validation rules

Field-Level Constraints

Field-level constraints allow you to indicate additional validations that will be applied to fields of a Sheet. These constraints are in addition to the implicit constraints based on types of data. (eg: String, Number)

For example, a value is required for every record (RequiredConstraint), or every record must contain a unique value for the field (UniqueConstraint).

Required Constraint

Required Constraints indicate that the given field must be provided with a non-null value.

A null value in this case constitutes an empty cell.

// within the context of a create Workbook API call
 "fields": [
  {
    "key": "firstName",
    "type": "string",
    "label": "First Name",
    "constraints": [
      {
        "type": "required"
      }
    ]
  }
]

Unique Constraint

Unique Constraints indicate that the given field value must only appear once in all the values for that field.

null values will appear many times because they are not considered unique as there is no value to compare.

// within the context of a create Workbook API call
 "fields": [
  {
    "key": "internalCustomerId",
    "type": "number",
    "label": "Internal Customer Id",
    "constraints": [
      {
        "type": "unique"
      }
    ]
  }
]

Computed Value

You might notice a ComputedValue type within the Blueprint code. Please do not use this value at this time as it is unsupported and may be deprecated without notice.

Sheet-Level

Composite Uniqueness

Composite Uniqueness is a feature where a combination of two or more fields must be unique across an entire Sheet.

To implement composite uniqueness, add the following parameters to the constraints property:

• name defines the name of the constraint

• fields array of field keys to consider

• type defines the type of the constraint

• strategy defines how to determine uniqueness

  Can either be:

  concat concatenates values from each field defined inside the fields array

  or hash creates a sha1 hash using of the values of each field

"sheets": [
  {
    "name": "Products",
    "description": "A list of products available for sale",
    "slug": "products",
    "constraints": [
      {
        "name": "constraint name",
        "fields": ["field_key_one", "field_key_two"],
        "type": "unique",
        "strategy": "concat"
      }
    ],
  }
]