glTF EXT_structural_metadata: Node Metadata Guide

The EXT_structural_metadata extension provides a standardized way to embed rich, strongly typed, and schema-driven metadata into glTF assets. When applied to nodes, it allows developers to associate non-visual properties—such as BIM parameters, GIS attributes, identifiers, and physical characteristics—directly with individual elements or instances in a 3D scene hierarchy. This article outlines the schemas, data types, and property structures that can be assigned to nodes using this extension.

Metadata Schema and Class Definitions

Metadata in EXT_structural_metadata is defined through a formal schema containing one or more classes. When structuring node metadata, the schema establishes the data blueprint:

  • Classes: Represent the conceptual category of the node (e.g., BuildingElement, SensorNode, or MechanicalPart).
  • Properties: Named fields within a class that define what metadata values can be stored (e.g., height, serialNumber, isOperational).
  • Semantic Annotations: Standardized tags that clarify the meaning of a property across different platforms and engines.

Supported Data Types for Node Properties

Properties attached to nodes can store a wide range of structured data types:

  • Scalars and Numeric Data: Integer (signed/unsigned 8-bit, 16-bit, 32-bit, 64-bit) and floating-point types (single- and double-precision) for measurements, coordinates, and quantities.
  • Booleans: Binary flags indicating states (e.g., visibility, load-bearing status).
  • Strings: UTF-8 encoded text for names, descriptions, or unique identifiers.
  • Enumerations (Enums): Predefined sets of named values for fixed classifications (e.g., material types or operational statuses).
  • Arrays: Fixed-length or variable-length sequences of any supported primitive, enum, or string, allowing lists of values like transformation vectors or tag sets.

How Node Metadata is Structured

Node-level metadata is primarily organized using Property Tables:

  1. Tabular Storage: Metadata is stored in columnar binary buffers (property tables) rather than loose JSON objects. This format optimizes memory layout and allows efficient access by runtime engines.
  2. Node-to-Row Association: A glTF node references the extension by declaring an index pointing to a specific property table and specifying the row index (or feature ID) corresponding to that node.
  3. Instance Metadata: When used in conjunction with GPU instancing (EXT_mesh_gpu_instancing), metadata can be mapped to individual mesh instances, assigning unique properties to each instance spawned from a single node.

Common Metadata Categories Structured on Nodes

  • Identification & Tracking: Global unique identifiers (GUIDs), serial numbers, and asset codes.
  • Physical & Environmental Metrics: Mass, volume, thermal coefficients, and structural load ratings.
  • Lifecycle & Maintenance Information: Installation dates, manufacturer names, maintenance schedules, and warranty details.
  • Functional States: Operational status codes, simulation variables, and interaction triggers.