uns-structure-design

name: UNS Structure Design description: Guidelines for designing and validating Unified Namespace (UNS) namespace tree structures — node types, type folders, topic fields, and data type inference.

UNS Structure Design Skill

This skill defines the rules for designing UNS (Unified Namespace) namespace tree structures in the Tier0 platform. The focus is on the namespace hierarchy: how PATH and TOPIC nodes are organized, how topicType drives data type inference, and how fields are defined.

Node Types

Every node in the namespace tree has a type field:

Namespace Hierarchy

The namespace is a recursive tree of PATH and TOPIC nodes. The typical pattern:

{Version} / {Site} / {Area} / {TypeFolder} / {Topic}

Example tree:

v1
└── Plant_Name
    └── SMT-Area-1
        ├── State        (PATH, topicType: STATE)
        │   ├── current_job   (TOPIC)
        │   └── productA      (TOPIC)
        ├── Action       (PATH, topicType: ACTION)
        │   ├── start_job     (TOPIC)
        │   └── stop_job      (TOPIC)
        └── Metric       (PATH, topicType: METRIC)
            ├── board_cycle_time  (TOPIC)
            └── boards_metrics    (TOPIC)

Type Folders (Core Concept)

A Type Folder is a PATH node with topicType set. It determines how all descendant TOPICs store data:

{
  "name": "State",
  "type": "PATH",
  "topicType": "STATE",
  "children": [...]
}

Data Type Inference Rules

TOPICs do not need an explicit dataType. The backend (node2vo) infers it automatically:

1. Parent topicType is STATE or ACTION → topic gets JSONB_TYPE; declared fields become JSON fields internally.
2. Parent topicType is METRIC → topic gets TIME_SEQUENCE_TYPE; fields are stored as time-series columns.
3. topicType propagates downward: nested PATH children inherit the parent's data type.

PATH Node

Regular PATH (pure folder)

{
  "name": "SMT-Area-1",
  "type": "PATH",
  "children": [...]
}

Type Folder PATH

{
  "name": "Metric",
  "type": "PATH",
  "topicType": "METRIC",
  "children": [...]
}

All PATH Fields

Constraints

• Names label and template are reserved and cannot be used as folder names.
• Folder name max length: 63 characters.

TOPIC Node

A TOPIC is a leaf node that defines a data point with typed fields.

Basic TOPIC (with fields)

{
  "name": "current_job",
  "type": "TOPIC",
  "fields": [
    { "name": "job_id", "type": "INTEGER" },
    { "name": "status", "type": "FLOAT" },
    { "name": "created_at", "type": "DATETIME" }
  ]
}

TOPIC with optional properties

{
  "name": "productA",
  "type": "TOPIC",
  "description": "desc",
  "enableHistory": "TRUE",
  "extendProperties": { "ext1": "value1" },
  "fields": [
    { "name": "product_id", "type": "INTEGER" },
    { "name": "status", "type": "STRING" }
  ]
}

TOPIC referencing a template

{
  "name": "board_cycle_time",
  "type": "TOPIC",
  "templateAlias": "basic_order",
  "enableHistory": "TRUE",
  "mockData": "FALSE"
}

All TOPIC Fields

Boolean-like fields (enableHistory, mockData, writeData) are strings, not JSON booleans.

Field Definitions

Each field has at minimum name and type:

{ "name": "temperature", "type": "DOUBLE" }

Supported Field Types

Field type lookup is case-insensitive. "int" is accepted as alias for INTEGER.

Optional Field Properties

Alias Generation

If alias is omitted (recommended), the backend auto-generates it from the full path: {parent_path}/{name}, processed by PathUtil.GenerateFileAlias(). This ensures global uniqueness.

Optional: Templates & Labels

Templates and labels are optional top-level sections. They are not required for namespace structure definition.

Templates

Reusable field schemas that TOPICs can reference via templateAlias:

{
  "templates": [
    {
      "alias": "basic_order",
      "name": "BasicTemplate",
      "fields": [
        { "name": "order_id", "type": "STRING" }
      ]
    }
  ]
}

Labels

Simple tags for categorizing nodes:

{
  "labels": [
    { "name": "alpha" },
    { "name": "beta" }
  ]
}

Import JSON Format

The full import file wraps everything in a single JSON object. Only namespace is required:

{
  "namespace": [
    {
      "name": "v1",
      "type": "PATH",
      "children": [
        {
          "name": "Plant_Name",
          "type": "PATH",
          "children": [
            {
              "name": "SMT-Area-1",
              "type": "PATH",
              "children": [
                {
                  "name": "State",
                  "type": "PATH",
                  "topicType": "STATE",
                  "children": [
                    {
                      "name": "current_job",
                      "type": "TOPIC",
                      "extendProperties": { "ext1": "value1" },
                      "fields": [
                        { "name": "job_id", "type": "INTEGER" },
                        { "name": "status", "type": "FLOAT" },
                        { "name": "created_at", "type": "DATETIME" }
                      ]
                    },
                    {
                      "name": "productA",
                      "type": "TOPIC",
                      "description": "desc",
                      "enableHistory": "TRUE",
                      "fields": [
                        { "name": "product_id", "type": "INTEGER" },
                        { "name": "status", "type": "STRING" }
                      ]
                    }
                  ]
                },
                {
                  "name": "Action",
                  "type": "PATH",
                  "topicType": "ACTION",
                  "children": [
                    {
                      "name": "start_job",
                      "type": "TOPIC",
                      "fields": [
                        { "name": "light_turn_on", "type": "BOOLEAN" },
                        { "name": "height_adjust", "type": "FLOAT" }
                      ]
                    },
                    {
                      "name": "stop_job",
                      "type": "TOPIC",
                      "fields": [
                        { "name": "water_pump_off", "type": "BOOLEAN" },
                        { "name": "window_close", "type": "BOOLEAN" }
                      ]
                    }
                  ]
                },
                {
                  "name": "Metric",
                  "type": "PATH",
                  "topicType": "METRIC",
                  "children": [
                    {
                      "name": "board_cycle_time",
                      "type": "TOPIC",
                      "enableHistory": "TRUE",
                      "mockData": "FALSE",
                      "templateAlias": "basic_order"
                    },
                    {
                      "name": "boards_metrics",
                      "type": "TOPIC",
                      "enableHistory": "TRUE",
                      "mockData": "FALSE",
                      "fields": [
                        { "name": "water", "type": "LONG" },
                        { "name": "temp", "type": "LONG" }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Validation Checklist

When reviewing or creating UNS structures, verify:

• Every node has type = PATH or TOPIC and a non-empty name
• Type folder PATH nodes set topicType to STATE, ACTION, or METRIC
• TOPIC nodes have fields array or templateAlias (one is required)
• METRIC topics use numeric/datetime field types only
• STATE/ACTION topics can use any field types (stored as JSONB internally)
• enableHistory, mockData, writeData are strings "TRUE" / "FALSE", not booleans
• extendProperties is a flat key-value map
• Folder names avoid reserved words (label, template) and are <= 63 chars
• If templateAlias is used, corresponding template must be defined

Backend Source Reference