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.

Start with Object or Action

Record Represents Examples

Record	Represents	Examples
`Object`	Something with identity that consumers track or reason about.	A platform, unit, facility, person, sensor, signal, event, route, or control measure.
`Action`	Directed activity, a notification, an order, or a structured report.	An ISR collection task, fire mission, operations order, contact alert, SPOTREP, or MEDEVAC request.

Object

Something with identity that consumers track or reason about.

A platform, unit, facility, person, sensor, signal, event, route, or control measure.

Action

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 security on every Object and Action.
Set provenance.updatedAt on every publish.
Provide id when 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 scope and type on 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

Modeling need	WDM fields
Stable identity and source identifiers.	`id`, `identities`, `name`, and `description`.
Broad semantic classification and ontology alignment.	`ontology.category`, `ontology.type`, and `ontology.refs`.
Domain-specific attributes.	The applicable fields in `typeInfo`, such as `maritime`, `aviation`, `ground`, `signal`, or `organization`.
Point position and movement.	`location` and `motion`.
Boundaries, routes, coverage, and control measures.	`shape` and, when applicable, `symbology`.
Tactical interpretation.	`assessment`, `targeting`, `symbology`, and `transponderCodes`.
Lifecycle and freshness.	`status`, `ttl`, and `persist`.
Source attribution and external lineage.	`provenance` and `externalRefs`.
Platform-managed mesh state and Object correlation.	The platform populates `replication`. The correlation service manages `correlation` and `disassociations`; clients read but do not set these fields when publishing.

Stable identity and source identifiers.

id, identities, name, and description.

Broad semantic classification and ontology alignment.

ontology.category, ontology.type, and ontology.refs.

Domain-specific attributes.

The applicable fields in typeInfo, such as maritime, aviation, ground, signal, or organization.

Point position and movement.

location and motion.

Boundaries, routes, coverage, and control measures.

shape and, when applicable, symbology.

Tactical interpretation.

assessment, targeting, symbology, and transponderCodes.

Lifecycle and freshness.

status, ttl, and persist.

Source attribution and external lineage.

provenance and externalRefs.

Platform-managed mesh state and Object correlation.

The platform populates replication. The correlation service manages correlation and disassociations; clients read but do not set these fields when publishing.

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, and provenance.
An AIS vessel normally uses identities, typeInfo.maritime, location, motion, dimensions, assessment, and provenance.
A fixed facility normally uses location, dimensions, assessment, and provenance, but does not need motion.
A route or control measure normally uses shape, ontology, symbology when applicable, and provenance.

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

Scope	Use
`ACTION_SCOPE_DIRECTIVE`	High-level strategic guidance.
`ACTION_SCOPE_ORDER`	An operational order, execution order, planning order, or amendment.
`ACTION_SCOPE_PLAN`	A named campaign or operation plan.
`ACTION_SCOPE_PHASE`	A temporal or functional phase within an order or plan.
`ACTION_SCOPE_TASK` or `ACTION_SCOPE_SUB_TASK`	A directed activity and its subordinate steps, such as an ISR collection, fire mission, or patrol.
`ACTION_SCOPE_ALERT`	A time-critical notification, such as a contact, CBRN, hostile-fire, or MEDEVAC alert.
`ACTION_SCOPE_REPORT`	A structured observation or assessment, such as a SPOTREP, SALUTE report, or INTSUM.

ACTION_SCOPE_DIRECTIVE

High-level strategic guidance.

ACTION_SCOPE_ORDER

An operational order, execution order, planning order, or amendment.

ACTION_SCOPE_PLAN

A named campaign or operation plan.

ACTION_SCOPE_PHASE

A temporal or functional phase within an order or plan.

ACTION_SCOPE_TASK or ACTION_SCOPE_SUB_TASK

A directed activity and its subordinate steps, such as an ISR collection, fire mission, or patrol.

ACTION_SCOPE_ALERT

A time-critical notification, such as a contact, CBRN, hostile-fire, or MEDEVAC alert.

ACTION_SCOPE_REPORT

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:

links relates one Action to another for sequencing, causality, supersession, derivation, or coordination.
objectLinks identifies 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

WDM is designed to cover a broad operational picture without adding a first-class field for every attribute produced by every source system. Object and Action provide the stable, typed fields that consumers can understand without knowing the source integration. Optional fields and a small set of extension mechanisms let producers preserve additional source data while keeping the standard WDM identity, security, provenance, and lifecycle around it.

Decide whether you need an extension

Most records do not need one. Start with the public WDM module and look for a typed field that represents the meaning of the source data. Use that field even when the source system uses a different name or structure.

An extension is appropriate when:

Integration-specific data must survive a round trip, but it has no canonical WDM field.
A new or uncommon concept is still local to a small number of producers and consumers.
Consumers need a pointer to, or an inline copy of, a record in another data model.
The record needs to reference a file or another payload that is too large to replicate inline.

If a concept is useful across integrations, changes how consumers interpret the operational picture, or must support consistent search and filtering, it probably belongs in the typed WDM model instead. Propose a model change rather than creating a private convention that every consumer must learn.

An extension preserves data, but it does not automatically give that data shared meaning. Producers and consumers must agree on any label names, details structure, or external payload type they exchange.

Pick the narrowest mechanism

Use the narrowest extension mechanism that preserves the source meaning.

Surface Use

Surface	Use
Strongly typed WDM field.	Data already represented by the canonical model. This is always the preferred option.
`labels`.	Small string metadata used to tag or organize a record. Use namespaced keys to avoid collisions.
`details`.	Small structured data that has no first-class WDM field. Include `@type` when consumers share a defined payload shape.
`externalRefs`.	A pointer to an external system record or an inline payload with a known external type.
`attachments`.	Large or binary content stored outside WDM. WDM carries the reference, not the file contents.
`ontology.refs`.	Formal semantic classification. Ontology references classify a record; they do not carry additional attributes.

Strongly typed WDM field.

Data already represented by the canonical model. This is always the preferred option.

labels.

Small string metadata used to tag or organize a record. Use namespaced keys to avoid collisions.

details.

Small structured data that has no first-class WDM field. Include @type when consumers share a defined payload shape.

externalRefs.

A pointer to an external system record or an inline payload with a known external type.

attachments.

Large or binary content stored outside WDM. WDM carries the reference, not the file contents.

ontology.refs.

Formal semantic classification. Ontology references classify a record; they do not carry additional attributes.

Do not add the same information to multiple extension surfaces. Consumers should have one canonical place to read each value.

Modeling examples

These examples apply the preceding rules to common integration patterns. Each page explains the field choices and includes a complete JSON record that matches the public WDM protobuf contract.

Object