Ability™ Developer Portal v23.1
Try Sandbox for free
Get a month of free access to ABB Ability™ Platform to learn and experiment!
API Playground
Play with ABB Ability™ Platform APIs (no time limits)

# Reusable Definitions

Reusable Definitions are standardized, centrally defined data structures that can be referenced multiple times across different type definitions in a system—without redefining them each time. Instead of writing the same structure over and over, you define it once and reuse it wherever needed.

# How Reusability Works

  1. Define Once
    You create a reusable definition with a unique ID and version.

  2. Reference Anywhere
    Instead of redefining the structure, you reference the ID in your type definition.

  3. Customize Where Allowed
    You can override certain values (like default values), but not the structure.

# Types of Reusable Definitions in TDR

Definition Type Used In
dataTypeDefinition Properties, Variables
propertyDefinition Properties
variableDefinition Variables
alarmDefinition Alarms
eventDefinition Events
functionDefinition Functions
attributeDefinition Attributes

# DataTypeDefinition

The dataTypeDefinition is a reusable component in the Type Definition Registry (TDR) that allows users to define primitive data types once and reuse them across multiple type definitions.

Reusable Definition

# Example

{
  "dataTypeDefinitionId": "abb.ability.common.voltage",
  "version": "1.0.0",
  "dataType": "integer",
  "min": 0,
  "max": 6553.5,
  "scale": 10,
  "pollingType": "fast",
  "targetDataType": "unum",
  "invalidValue": 65535
}

# Reuse in type definition

{
  "model": "abb.control",
  "typeId": "abb.process",
  "version": "1.0.0",
  "properties": {
    "voltage": {
      "dataType": "abb.ability.common.voltage@1"
    }
  }
}

# Valid dataTypeDefinition Examples

# 1. Primitive Integer Definition (Generic Use)

{
  "dataTypeDefinitionId": "abb.ability.common.int64",
  "version": "1.0.0",
  "dataType": "integer",
  "max": 9223372036854775807,
  "min": -9223372036854775807
}

# 2. Primitive Enum Definition (Model-Specific)

{
  "dataTypeDefinitionId": "abb.ability.my.definition",
  "model": "abb.ability.configuration",
  "version": "1.0.0",
  "dataType": "string",
  "enum": ["high", "low"]
}

# 3. Array Definition for Properties and Variables

{
  "dataTypeDefinitionId": "abb.ability.propertyTypes.arrayOf",
  "version": "1.0.0",
  "dataType": "array",
  "items": "string",
  "enum": ["small", "medium", "large", "extra-large"]
}

# 4. Integer with Unit

{
  "dataTypeDefinitionId": "abb.ability.variablesTest.dataTypes.uidType",
  "version": "1.0.0",
  "dataType": "integer",
  "unit": "Ml"
}

# 5. Minimal Integer Definition

{
  "dataTypeDefinitionId": "abb.ability.common.int64.constant",
  "version": "1.0.0",
  "dataType": "integer"
}

# 6. Map of Strings

{
  "dataTypeDefinitionId": "abb.common.simpleLanguageMap",
  "version": "1.0.0",
  "dataType": "map",
  "values": "string"
}

# 7. Map of Maps

{
  "dataTypeDefinitionId": "abb.common.objectLanguageMap",
  "version": "1.0.0",
  "dataType": "map",
  "values": {
    "dataType": "map",
    "values": "string"
  }
}

# ❌ Invalid dataTypeDefinition Examples

# 1. Reserved System Name

{
  "dataTypeDefinitionId": "boolean",
  "version": "1.0.0",
  "dataType": "boolean"
}

❌ Invalid because boolean is a reserved system keyword.

# 2. Forbidden Attribute (isMandatory)

{
  "dataTypeDefinitionId": "abb.ability.custom.boolean",
  "version": "1.0.0",
  "dataType": "boolean",
  "isMandatory": true
}

❌ Invalid because isMandatory should be defined at the point of use, not in the reusable definition.

# 3. Default Value in Primitive Definition

{
  "dataTypeDefinitionId": "abb.ability.variablesTest.dataTypes.broken",
  "version": "1.0.0",
  "dataType": "string",
  "value": "default value for this property"
}

❌ Invalid because default values in primitive reusable definitions restrict flexibility and reusability.

# PropertyDefinition

The propertyDefinition functionality allows users to declare reusable property sets that can be referenced in type definitions and extensions.

Structure of a propertyDefinition example

{  
      "propertyDefinitionId": "abb.ability.common.EmpInfo",  
      "version": "1.0.0",    
      "dataType": "object",   
      "dataElements": { 
        "name": {
          "firstname" : {  
           "dataType": "string", 
           "isMandatory" : true 
        },
        "lastname" : {  
          "dataType": "string", 
    	"value": "ABB"  
        },
         },  
        "weight": {  
          "dataType": "number", 
          "value": 70 
        }  
      }  
    }

# Reuse in type definition

{ 
      "model": "abb.test.model", 
      "typeId": "abb.employee.type", 
      "version": "1.0.0", 
      "properties": { 
            "EmpInfo": { 
                 "propertyDefinitionId": [ "abb.ability.common.EmpInfo@1"] 
             } 
      }
    } 
    }

# HolisticView in TD

{
    	"model": "abb.test.model",
    	"typeId": "abb.employee.type",
    	"version": "1.0.0",
    	"properties": {
    		"EmpInfo": {
    			"name": {
    				"firstname": {
    					"dataType": "string",
    					"isMandatory": true
    				},
    				"lastname": {
    					"dataType": "string",
    					"value": "ABB"
    				}
    			},
    			"weight": {
    				"dataType": "number",
    				"value": 70
    			}
    		}
    	}
    }

# Valid Examples

# 1. Nested Property Category

{
  "propertyDefinitionId": "abb.ability.common.name",
  "version": "1.0.0",
  "dataType": "object",
  "dataElements": {
    "name": {
      "firstname": { "dataType": "string" },
      "lastname": { "dataType": "string" }
    }
  }
}

# 2. With Descriptions and Tags

{
  "propertyDefinitionId": "abb.ability.common.name",
  "version": "1.0.0",
  "dataType": "object",
  "description": "Name property",
  "tags": ["name"],
  "dataElements": {
    "name": {
      "firstname": {
        "dataType": "string",
        "description": "firstname",
        "isMandatory": true
      },
      "lastname": {
        "dataType": "string",
        "value": "ABB"
      }
    }
  }
}

# 3. With Constraints

{
  "propertyDefinitionId": "abb.ability.common.prop",
  "version": "1.0.0",
  "dataType": "object",
  "dataElements": {
    "longitude": {
      "dataType": "number",
      "min": 10,
      "max": 20
    },
    "elec": {
      "dataType": "number",
      "unit": "KW"
    }
  }
}

# 4. With Zone of Visibility

{
  "propertyDefinitionId": "abb.ability.common.geoLocation",
  "model": "abb.ability.device",
  "version": "1.0.0",
  "dataType": "object",
  "dataElements": {
    "longitude": { "dataType": "number" },
    "latitude": { "dataType": "number" }
  }
}

# 5. Array Type

{
  "propertyDefinitionId": "abb.ability.common.myprop",
  "version": "1.0.0",
  "dataType": "object",
  "dataElements": {
    "accept-encoding": {
      "description": "List of accepted device encodings",
      "dataType": "array",
      "items": "string",
      "enum": ["utf-8", "gzip", "deflate"]
    },
    "prop2": { "dataType": "number" }
  }
}

# 6. Map of Maps

{
  "propertyDefinitionId": "abb.common.objectLanguageMap",
  "version": "1.0.0",
  "dataType": "object",
  "dataElements": {
    "translations": {
      "dataType": "map",
      "values": {
        "dataType": "map",
        "values": "string"
      },
      "value": {
        "displayName": {
          "en": { "value": "Display Name" },
          "de": { "value": "Anzeigename" }
        },
        "voltage": {
          "en": { "value": "Voltage" },
          "de": { "value": "Spannung" }
        }
      }
    }
  }
}

# Reuse in Type Definitions

# 1. Under a Property

{
  "model": "abb.test.model",
  "typeId": "abb.employee.type",
  "version": "1.0.0",
  "properties": {
    "EmpInfo": {
      "propertyDefinitionId": ["abb.ability.common.name@1"]
    }
  }
}

# 2. Directly in Properties

{
  "model": "abb.test.model",
  "typeId": "abb.employee.type",
  "version": "1.0.0",
  "properties": {
    "propertyDefinitionId": ["abb.ability.common.name@1"]
  }
}

# 3. Multiple Definitions

{
  "model": "abb.test.model",
  "typeId": "abb.employee.type",
  "version": "1.0.0",
  "properties": {
    "propertyDefinitionId": [
      "abb.ability.common.name@1",
      "abb.ability.common.geoLocation@1"
    ]
  }
}

# Extension and Override

# 1. Override Values

Override/Provide values to properties defined in property definition

{
  "model": "abb.ability.device",
  "typeId": "abb.location.MSK.type",
  "version": "1.0.0",
  "properties": {
    "geoLocation": {
      "propertyDefinitionId": ["abb.ability.common.geoLocation@1"],
      "longitude": { "value": 55.75 },
      "latitude": { "value": 37.61 }
    }
  }
}

# 2. Add New Property

Adding new property along with propertydefinitionId

{
  "model": "abb.ability.device",
  "typeId": "abb.location.MSK.type",
  "version": "1.0.0",
  "properties": {
    "geoLocation": {
      "propertyDefinitionId": ["abb.ability.common.geoLocation@1"],
      "height": {
        "dataType": "number",
        "value": 10
      },
      "longitude": { "value": 55.75 },
      "latitude": { "value": 37.61 }
    }
  }
}

# Invalid Type Definitions with reusable property definitions

# 1. Forbidden to override the platform attribute value:

{
        "model": " abb.substations",
      "typeId": "abb.variablesTest.type",
      "version": "1.0.0",
      "properties": {
    	"deviceUid": {
          "propertyDefinitionId": [ "abb.ability.common.geoLocation@1"]
          "unit": "Overriding of Ml" // it is forbidden to overwrite platform attributes predefined in reusable definition 
           }
    	}
    }

# 2. Forbidden utility of property definition as property failing while trying to overwrite predefined default value:

{
        "model": " abb.substations",
      "typeId": "abb.variablesTest.type",
      "version": "1.0.0",
      "properties": {
    	"deviceUid": {
                "propertyDefinitionId": [ "abb.ability.common.geoLocation@1"],
    // originally: "enum": ["small", "medium", "large", "extra-large"],
                "enum": ["S", "M", "L", "XL"]
    // it is forbidden to overwrite properties predefined in reusable definition 
    // same here "enum": ["super-small", "small", "medium", "large", "extra-large"]
    // it is forbidden to increase array of allowed attributes
               	}
    	}
    }

# 3. Reusing property definitions having common properties

  • scenario-1
{  
      "propertyDefinitionId": "propSet1",  
      "version": "1.0.0",    
      "dataType": "object",   
      "dataElements": {
          "prop1" : {  
           "dataType": "number"
        },
          "prop2" : {                   // common prop with below property definition
           "dataType": "number"
        }  
    }

{  
      "propertyDefinitionId": "propSet2",  
      "version": "1.0.0",    
      "dataType": "object",   
      "dataElements": {
          "prop2" : {  
           "dataType": "number"
        },
          "prop3" : {  
           "dataType": "number"
        }  
    }

# Use in TD

{ 
      "model": "abb.test.model", 
      "typeId": "abb.employee.type", 
      "version": "1.0.0", 
      "properties": { 
      "propertyDefinitionId": ["propSet1@1","propSet2@1"] // Valid
      }
    }

# - scenario-2

{  
      "propertyDefinitionId": "propSet1",  
      "version": "1.0.0",    
      "dataType": "object",   
      "dataElements": {
          "prop1" : {  
           "dataType": "number"
        },
          "prop2" : {                   // common prop with different dataType in below property definition
           "dataType": "number"
        }  
    }

{  
      "propertyDefinitionId": "propSet2",  
      "version": "1.0.0",    
      "dataType": "object",   
      "dataElements": {
          "prop1" : {  
           "dataType": "string"
        },
          "prop3" : {  
           "dataType": "number"
        }  
    }

# Use in TD

{ 
      "model": "abb.test.model", 
      "typeId": "abb.employee.type", 
      "version": "1.0.0", 
      "properties": { 
    "propertyDefinitionId": ["propSet1@1","propSet2@1"] // InValid
      }
    }

Invalid - Will give error message that prop2 exists in both the property definition

# VariableDefinition

The variableDefinition functionality allows users to declare reusable variable sets that can be referenced in type definitions and extensions.

Structure of a variableDefinition example

Complex variable definition for two properties with system attributes:

{ 
      "variableDefinitionId": "abb.ability.common.capacity", 
      "version": "1.0.0",  
      "dataType": "object", 
      "dataElements": { 
        "width": { 
          "dataType": "number",
    	"max": 1111,
      	"min": 1
        }, 
        "height": { 
          "dataType": "number",
          "unit": ["m", "mm", "cm", "inch"]	 
        },
        "volume": {
          "dataType": "number",
          "enum": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]	 
        }   
      } 
    }

# Reuse in TD:

{
      "model": "abb.ability.device",                                   
      "typeId": "typeA",
      "version": "4.1.0",
      "variables": {
       "variableDefinitonId" : [ "abb.ability.common.capacity@1" ]
       }
    }

# Holistic view

{
      "model": "abb.ability.device",                                   
      "typeId": "typeA",
      "version": "4.1.0",
      "variables": {
         "width": { 
          "dataType": "number",
    	"max": 1111,
      	"min": 1
        }, 
        "height": { 
          "dataType": "number",
          "unit": ["m", "mm", "cm", "inch"]	 
        },
        "volume": {
          "dataType": "number",
          "enum": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]	 
        }   
          }
    }

"All rules and constraints that apply to the propertyDefinition section—such as restrictions on overriding predefined attributes, maintaining data type consistency, and proper reuse—also apply equally to the variableDefinition section."

# AttributeDefinition

The attributeDefinition functionality allows users to declare reusable attribute sets that can be referenced in type definitions and extensions.

structure of attributeDefiniton

{
  "attributeDefinitionId": "Attributes_Pump",
  "version": "1.0.0",
  "dataType": "object",
  "dataElements": {
    "connectionInterface": {
      "dataType": "string",
      "appliesTo": ["property"],
      "enum": ["bluetooth", "ethernet", "rs-485"]
    },
    "scale": {
      "dataType": "integer",
      "appliesTo": ["number", "integer"]
    }
  }
}

# Reuse in type definition

{
  "typeId": "my.typeA",
  "model": "abb.ability.device",
  "version": "1.0.0",
  "properties": {
    "weight": {
      "dataType": "number",
      "description": "Physical mass of the object",
      "connectionInterface": "bluetooth",
      "scale": 100
    }
  },
  "attributes": {
    "attributeDefinitionId": ["Attributes_Pump@1"]
  }
}

# Holistic view

{
        "typeId": "my.typeA",
        "model": "abb.ability.device",
        "version": "1.0.0",
        "properties": {
            "weight": {
                "dataType": "number",
                "description": "Physical mass of the object",
                "connectionInterface": "bluetooth",
                "scale": 100
            }
        },
        "attributes": {
            "connectionInterface": {
                "dataType": "string",
                "appliesTo": [
                    "property"
                ],
                "enum": [
                    "bluetooth",
                    "ethernet",
                    "rs-485"
                ]
            },
            "scale": {
                "dataType": "integer",
                "appliesTo": [
                    "number",
                    "integer"
                ]
            }
        }
    }

# AlarmDefinition

The alarmDefinition functionality allows users to declare reusable alarm sets that can be referenced in type definitions and extensions.

# Example payload

{
  "alarmDefinitionId": "abb.ability.alarm.limitAlarm",
  "version": "1.0.0",
  "state": {
    "limitState": {
      "dataType": "string",
      "enum": ["low", "normal", "high"],
      "isMandatory": true
    },
    "limitStateTs": {
      "dataType": "string"
    }
  }
}

# Reuse in type defintiion

{
       "modelId" : "abb.ability.device",
       "typeId" : "abb.alarmTest.typeWithAlarm",
       "version" : "1.0.0",
       "variables" : {
           "tankLevel" : {
              "dataType" : "number"
           },
          "boilerLevel" : {
              "dataType" : "number"
           }
       },
       "alarms" : {
          "tankLevelAlarm" : {
             "dataType" : "abb.ability.common.alarms.limitAlarm@1",
}
}

# EventDefinition

The eventDefinition functionality allows users to declare reusable event sets that can be referenced in type definitions and extensions.

Example payload

{
  "eventDefinitionId": "abb.ability.event.motorStarted",
  "version": "1.0.0",
  "acknowledge": {
    "isAcknowledged": {
      "dataType": "boolean"
    },
    "limitStateTs": {
      "dataType": "string"
    }
  }
}

# Reuse in type defintiion

{
       "modelId" : "abb.ability.device",
       "typeId" : "abb.eventTest.typeWithEvent",
       "version" : "1.0.0",
       "variables" : {
           "tankLevel" : {
              "dataType" : "number"
           },
          "boilerLevel" : {
              "dataType" : "number"
           }
       },
       "events" : {
          "events" : {
                "pumpMotorStarted" : {
                      "dataType" : "abb.ability.event.motorStarted@1"
               }
       }
}
Last updated: 5/29/2025, 9:17:29 AM

← Supported Data Types →

Feedback