Modeling with WDM
WDM uses two top-level records, Object and Action, to represent the operational picture.
This guide explains how to choose between them and how to select the fields that preserve the meaning of the source data.
The public WDM module in the Buf Schema Registry is the authoritative schema reference. Use this guide for modeling decisions, then use the protobuf comments for the exact field contracts and enum values.
See Map External Data to WDM for examples and guidance on IDs, unit conversion, source records, and replay.
Start with Object or Action
| Record | Represents | Examples |
|---|---|---|
|
Something with identity that consumers track or reason about. |
A platform, unit, facility, person, sensor, signal, event, route, or control measure. |
|
Directed activity, a notification, an order, or a structured report. |
An ISR collection task, fire mission, operations order, contact alert, SPOTREP, or MEDEVAC request. |
Use these rules of thumb:
-
Model something that exists or has a position as an Object.
-
Model something that is requested, authorized, assigned, executed, or reported as an Action.
-
When an activity concerns something in the operational picture, model the activity as an Action and link the relevant Objects through
objectLinks.
For example, model a planned strike as an Action and its target as an Object. Do not duplicate the target’s identity and current state inside the Action.
Populate only meaningful fields
WDM records intentionally contain many optional fields so one schema can represent different operational domains. A producer should populate the fields it knows and omit fields that are unknown or irrelevant.
Follow these rules:
-
Do not invent values to make a record look complete.
-
Preserve the difference between absent data and a known default value.
-
Prefer a strongly typed field whenever WDM defines one.
-
Include source attribution and the time the source information was updated.
-
Include the security marking required to handle the record correctly.
When publishing through the WDM services:
-
Set
securityon every Object and Action. -
Set
provenance.updatedAton every publish. -
Provide
idwhen the source has a stable identifier or the record must retain identity across updates. Omit it only when the service should create a new identifier. -
Set both
scopeandtypeon an Action so consumers know how to interpret it.
Model Objects
An Object combines identity, semantic classification, domain attributes, spatial state, tactical context, and lifecycle state. Different kinds of Objects use different subsets of those fields.
| Modeling need | WDM fields |
|---|---|
Stable identity and source identifiers. |
|
Broad semantic classification and ontology alignment. |
|
Domain-specific attributes. |
The applicable fields in |
Point position and movement. |
|
Boundaries, routes, coverage, and control measures. |
|
Tactical interpretation. |
|
Lifecycle and freshness. |
|
Source attribution and external lineage. |
|
Platform-managed mesh state and Object correlation. |
The platform populates |
typeInfo is a composite of domain-specific messages, not an exclusive oneof.
Most Objects populate one domain component.
Populate more than one only when the Object genuinely spans domains, such as a ground-based radar that also has signal characteristics.
Use location for a point position and shape for non-point geometry.
For a tactical control measure, set ontology.category to ONTOLOGY_CATEGORY_CONTROL_MEASURE, store its construction geometry in shape, and provide the MIL-STD-2525 SIDC and modifiers in symbology when clients should render it as a tactical graphic.
Common Object patterns include:
-
An ADS-B aircraft normally uses
identities,typeInfo.aviation,location,motion,assessment, andprovenance. -
An AIS vessel normally uses
identities,typeInfo.maritime,location,motion,dimensions,assessment, andprovenance. -
A fixed facility normally uses
location,dimensions,assessment, andprovenance, but does not needmotion. -
A route or control measure normally uses
shape,ontology,symbologywhen applicable, andprovenance.
See Object for a complete example and lifecycle guidance.
Model Actions
An Action uses scope for its broad role and type for its integration-specific meaning.
The scope comes from a fixed enum; the type is a lowercase snake-case value shared by the producers and consumers in an integration.
| Scope | Use |
|---|---|
|
High-level strategic guidance. |
|
An operational order, execution order, planning order, or amendment. |
|
A named campaign or operation plan. |
|
A temporal or functional phase within an order or plan. |
|
A directed activity and its subordinate steps, such as an ISR collection, fire mission, or patrol. |
|
A time-critical notification, such as a contact, CBRN, hostile-fire, or MEDEVAC alert. |
|
A structured observation or assessment, such as a SPOTREP, SALUTE report, or INTSUM. |
Use parentActionId and childActionIds to compose Actions into a planning hierarchy.
An order can contain phases, and each phase can contain tasks or subtasks.
Standalone alerts and reports normally omit the hierarchy fields.
Use typed links instead of embedding identifiers in descriptions:
-
linksrelates one Action to another for sequencing, causality, supersession, derivation, or coordination. -
objectLinksidentifies Objects that are targets, assigned assets, or related context.
Set every substantive field needed by consumers when creating an Action.
After creation, use UpdateActionState only for lifecycle state, progress, and optional provenance.
Dedicated server-side workflows manage BDA attachments and approval-chain changes.
To change other Action content, cancel the existing Action and create a new one.
See Action for a complete example and lifecycle guidance.
Choose an extension surface
How WDM stays extensible
Typed WDM fields give attributes shared meaning across integrations. Extensions add data richness and preserve source representations without changing the WDM schema; the record still carries its identity, security, provenance, and lifecycle.
Decide whether you need an extension
A matching typed field gives clients a common place to read a value, even when source systems use different names or units. Extensions cover information beyond those shared definitions:
-
Measurements or context that need application-specific definitions.
-
A copy of, or reference to, a record in another data model.
-
A file or payload stored separately from the WDM record.
A concept shared across integrations may belong in the typed model, where clients can rely on common field definitions.
Pick the narrowest mechanism
Use the narrowest extension mechanism that preserves the source meaning.
| Surface | Use |
|---|---|
Strongly typed WDM field. |
Values already represented by a WDM field. |
|
Small string metadata used to tag or organize a record. Use namespaced keys to avoid collisions. |
|
Custom structured attributes that enrich the record. Producers and consumers agree on their field definitions. |
|
A pointer to an external system record or an inline payload with a known external type. |
|
Large or binary content stored outside WDM. WDM carries the reference, not the file contents. |
|
Formal semantic classification. Ontology references classify a record; they do not carry additional attributes. |
Add data richness with details
Object.details and Action.details hold a google.protobuf.Struct, a container for JSON-like data with nested fields. This makes custom measurements or context available alongside standard WDM fields. For example, the weather Object includes this rain-rate fragment:
{
"details": {
"@type": "com.example.mapping.v1.ReportedPrecipitation",
"value": {
"rateMmPerHour": 5.0
}
}
}
The application-defined @type labels this structure; it does not select a protobuf decoder or validate its contents. Because details is loosely typed, producers and clients must agree on field names, value types, units, and meaning.
[R]DP supports field-based filtering within details. A stream filter can use details.value.rateMmPerHour to select observations above a chosen rain-rate threshold. Agreed field definitions let integrations build data feeds around these custom attributes.
details exposes selected attributes, while externalRefs retains the source representation. Keeping the original input remains useful even when its values also appear in typed fields or details: consumers can recover information beyond the mapping. See Preserve Source Data for payload formats and packing examples.
Modeling examples
These examples apply the preceding rules to common integration patterns. Each page explains the field choices and includes a complete WDM record.
Tracked platform
Represent identity, domain attributes, position, motion, assessment, and provenance.
View exampleTactical graphic
Represent MIL-STD-2525 construction geometry, SIDC, and rendering modifiers.
View exampleAction and Objects
Assign an asset, identify a target, and preserve each record's independent lifecycle.
View exampleContinue
Object
Populate identity, spatial state, domain attributes, tactical context, and lifecycle.
OverviewAction
Represent tasks, orders, alerts, reports, dependencies, and execution state.
OverviewAPI access
Choose an SDK, REST, or ConnectRPC integration path.
Integration options