Object Model Validation Rules

Overview

The following article describes the ABB Ability™ object model attributes, definitions for which are stored in the type definition registry service for model definition and/or type definition. Attributes are validated with model definition, type definition, object model, or reference operations using either create or update.

Both information model and type definition registry services validate attributes:

1. Type Definition Registry: validates attribute definitions on create/update model definition or type definition operations.
2. Information Model: validates attribute values on create/update object model or reference operations.

Type Definition

An attribute can only be present in a property, variable or reference definition in a type definition if, and only if:

• It is a reserved platform attribute as defined here.
• It is platform defined validation keyword as defined here.
• It has been defined in the "attributes" section of the current type definition or one of its base types and one of the appliesTo entries in the attribute definition matches the dataType of the property/variable/reference it is defined for. Alternatively, if appliesTo is empty all data types are allowed.

TDR Validation Rules

• The absence of a unique array is treated as “no uniqueness is set”. This means that uniqueness may be defined in a child type.

• When uniqueness is set, none of the further child types are allowed to redefine uniqueness (neither remove, nor add unique properties).

• It is also forbidden to explicitly define a 'unique' property for the type definition, as it is already defined by the parent type.

• The type definition cannot inherit from two types that have uniqueness defined, even if the uniqueness definitions of the two types are the same.

• RelatedModels validation stays as is and validation occurs via a holistic representation of the required type definitions.

• Starting from the first inherited type definition, where 'unique' was set, all heirs will belong to the type named in the unique group.

Information Model

An attribute may be present in a property or variable in an object model if, and only if, it has been defined in the corresponding property/variable definition in the corresponding type or one of its base types.

Platform Defined Attributes

Attribute: description

• Human readable description explaining the element it is applied to (model definition, type definition, object model, property, variable, etc.).
• dataType: string
• Applicable to all elements (properties, variables, type definitions).

Attribute: tags

• Used as a basis for semantic identifiers as defined here. A list of tags that are commonly used can also be found there.
• dataType: array (of string).
• Applicable to all elements (properties, variables, type definitions).
• Can also be defined in object models to add additional tags on instance level.
• Gives a list of tags to identify a certain type, property, etc.
• Used as a basis for semantic identifiers as defined here.
• A list of tags that are commonly used can also be found here.

Attribute: value

• When present on a type definition, this defines the default value of the property it is defined on. When present on an object model it defines value of a property only for that object
• dataType: defined by the dataType keyword more information here.
• Only applicable to properties

Validation Rules

Allowed Root Level Attributes

When making an update or a creating a new object model using the Information Model API there are number of validation checks that should be considered while designing and building your object model.

First, every object model has a predefined list of properties that are allowed on the root level. The list of these approved properties contains the following keys:

• model
• type
• objectId
• name
• description
• tags
• properties
• variables

Inclusion of any additional attributes will be rejected.

Validation Keywords

Validation keywords in a property/variable definition impose requirements for successful validation of a value of a specific property/variable/reference in the object model/telemetry message.

All validation keywords are modeled as Platform Defined Attributes and are therefore reserved in their usage (i.e., cannot be defined again in the attributes section of a type definition).

Most of the semantics of the following validation keywords follow the JSON schema validation specification with some minor variations.

In the below definitions, the word “instance” refers to the corresponding object model or telemetry message depending on whether used in a property or variable definition respectively.

Validation Keywords for Any Data Type

Attribute: dataType

Defines the dataType the "value" that a property or variable can have.

• Applicable to properties and variables.
• The value of this keyword MUST be a string.
• Permitted values: "boolean", "array", "map", "number", "string", "integer"

Required keywords per data type:

• array: items
• map: values

TIP

You can learn more about data types here.

Attribute: isMandatory

Defines a property’s requirement to be set in an object model or if it can be omitted.

• Applicable to properties.
• The value of this keyword MUST be a Boolean.
• If it has value 'true', the instance the value needs to exist in each object model
• Default value is 'false'

isMandatory has some relation to the default value:

• If isMandatory: true and there is no default value: The value has to be in the object model, otherwise the instance is invalid.
• If isMandatory: true and there is a default value: If there is no value in the object model, the default value will be used once an instance is created.

In cases where isMandatory is false, the proeprty is treated like any property without this attribute specified at all.

Attribute: enum

Defines the set of possible values of a property or variable.

• Applicable to properties and variables.
• The value of this keyword MUST be an array. This array MUST have at least one element. Elements in the array MUST be unique within that array.
• An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value.
• Elements in the array MUST be valid instances of the specified data type.

Validation Keywords for Arrays

Attribute: items

Defines the set of possible values of an array valued property or variable by data type.

• The value of "items" MUST be a valid property definition or a string (implicit dataType keyword) of one of the following primitive data types: string, boolean, number or integer.
• This keyword determines how child instances validate for arrays, and does not directly validate the immediate instance.
• Validation succeeds if all the elements in the array successfully validate against that definition.

Attribute: enum

Enumerates the set of possible values of a property or variable with an array data type.

NOTE

The semantics of enum in the context of arrays depend on whether its value is a simple array or an array of arrays.

• Applicable to properties and variables where data type is array.
• The value of this keyword MUST be an array. This array MUST have at least one element. Elements in the array MUST be unique within that array.
• An instance validates successfully against this keyword if its value only contains elements that are given in this keyword's array value.
• Elements in the array MUST be valid instances of the specified datatype in "items".

EXAMPLE

If data type is an array and items are string, the contents of the enum array have to be of type string as well. E.g., "enum" : ["one", "two","three", "four"]. Which would allow e.g., "value" : ["one", "four"] but not "value":["one", "five"].

Validation Keywords for Maps

Attribute: values

Defines the allowed values of keys inside a map value property or variable.

• Applicable to properties and variables.
• The value of "values" MUST be either a valid property definition or a string (implicit dataType keyword).
• This keyword determines how child instances validate for maps, and does not directly validate the immediate instance.
• Validation succeeds if each of the child instances successfully validates against that definition.