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

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

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

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

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.

labels.

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

details.

Custom structured attributes that enrich the record. Producers and consumers agree on their field definitions.

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.

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.