Author DTDL (Digital Twins Definition Language) model files in JSON-LD defining interfaces with properties, telemetry, relationships, and components; use DTDL v2 or v3 and validate the files with the DTDL parser SDK before uploading
Upload models to Azure Digital Twins via the CLI (az dt model create --dt-name <name> --models <file.json>) or REST API PUT https://<host>/models; models are immutable once created — decommission old versions and create new ones for changes
Create twin instances corresponding to real physical entities: az dt twin create --dt-name <name> --dtmi dtmi:example:Room;1 --twin-id room1; set initial property values with --properties '{"temperature":21.0}'
Create relationships between twins to model spatial or logical topology: az dt twin relationship create --dt-name <name> --twin-id room1 --relationship-id rel1 --relationship contains --target sensor1; relationships mirror the DTDL relationship definitions
Query the twin graph using the Azure Digital Twins Query Language (SQL-like syntax): SELECT * FROM digitaltwins WHERE IS_OF_MODEL('dtmi:example:Room;1') returns all room twins; JOIN traversal up to 5 hops for relationship path queries
Integrate live telemetry by routing IoT Hub messages to a function that calls the Update Twin API to patch telemetry-backed properties; use Event Routes in Azure Digital Twins to forward twin change notifications to Event Hub or downstream services
Known gotchas
DTDL v3 models are supported for most operations but do not appear in the Model Graph panel in Azure Digital Twins Explorer and cannot be imported via that tool's UI — use the CLI or REST API for DTDL v3 model management
Deleting a twin that has incoming relationships fails with a BadRequest error; all relationships pointing to the twin must be deleted first before the twin itself can be removed
The Azure Digital Twins Query Language supports a maximum of 5 JOINs in a single query; deeply nested relationship traversals must be broken into multiple queries and joined at the application layer
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp