Skip to content

Metadata Template

A Metadata Template is a predefined metadata structure associated with a Device Type that ensures consistency and standardization across devices of the same type. Metadata templates define the expected metadata keys, their value types and default values that should be applied to devices.

Overview

Metadata templates serve as blueprints for metadata that should be consistently applied to devices of a specific device type.

Structure

A metadata template consists of the following properties:

Property Type Description Required
id UUID Unique identifier for the template Auto-generated
tenantId UUID Identifier of the tenant that owns the template Yes
deviceTypeId UUID Identifier of the device type this template is associated with Yes
key String The metadata key (must be unique per device type) Yes
valueType Enum The expected data type: string, number, boolean, or object Yes
defaultValue JSON Default value to apply when creating metadata (must match valueType) No
nullable Boolean Whether the metadata value can be null (default: true) No

Access

To create, update or delete a metadata template, the principal need to have the update permission on the associated device type.

How Metadata Templates Work

Template Association

Metadata templates are associated with a specific Device Type within a Tenant. This means that if the device type is shared between many tenants (through inheritance) the metadata template will be the same for all tenants.

Automatic Application

When a metadata template is created, it is automatically applied to all existing devices of the associated device type:

  1. If defaultValue is provided, metadata with that value is created on all existing devices
  2. New devices created with the device type will automatically receive metadata from templates

Creating Metadata Templates

Prerequisites

  • Permission: Update.Device Type permission on the tenant
  • Consistency: If nullable is defined at false, a defaultValue must be provided or the creation will fail

Behavior on Creation

When a metadata template is created all existing devices of that device type automatically receive metadata matching the template:

  • If defaultValue is provided, it is used
  • If nullable is true and no defaultValue, metadata is created with null value

Constraints

  • The valueType cannot be changed after creation
  • If nullable is set to false, a defaultValue must be provided
  • The new key must not conflict with existing templates or custom metadata

Updating Metadata Templates

Updateable Fields

  • key: Can be changed (will update all associated metadata keys)
  • defaultValue: Can be updated
  • nullable: Can be changed

Update Behavior

When a metadata template is updated:

  1. Key changes: If the key is updated, all existing metadata with the old key is updated to use the new key
  2. Nullable changes: If nullable is changed from true to false, all existing metadata with null values are updated to use the defaultValue
  3. Default value changes: The default value is updated, but existing device metadata values are not automatically changed, unless nullable is changed from true to false in the same request

Constraints

  • The valueType cannot be changed after creation
  • If nullable is set to false, a defaultValue must be provided
  • The new key must not conflict with existing templates or custom metadata

Deleting Metadata Templates

Behavior

When a metadata template is deleted, existing metadata on devices that were created from this template are also deleted

Using Metadata Templates with Devices

Automatic Template Application

When creating a device, if no metadata corresponding to the templates are provided the template will be automatically applied with its default value.

Manual Application

When creating or updating device metadata:

If a metadata key matches a template key, the system validates the value against the template. If the value type of the existing metadata the one of the template, the whole operation is rejected. The metadata is then automatically marked as type TEMPLATE and linked to the template

Example: Device Creation with Templates

Consider a device type "Temperature Sensor" with the following templates:

  • location (string, nullable: false, defaultValue: "Unknown")
  • floor (number, nullable: true, defaultValue: null)
  • room (string, nullable: true, defaultValue: null)

When creating a device:

Request:

{
  "name": "Sensor-001",
  "deviceTypeId": "...",
  "metadata": [
    { "key": "location", "value": "Building A" },
    { "key": "floor", "value": 3 }
  ]
}

Result:

  • location: "Building A" (validated against template, type: TEMPLATE)
  • floor: 3 (validated against template, type: TEMPLATE)
  • room: null (automatically added from template, type: TEMPLATE)

Limitations

  • The valueType cannot be changed after creation
  • Templates cannot be shared across device types (each device type needs its own templates)