Map External Data to WDM

External feeds describe units, aircraft, vessels, and weather in different formats. Mapping them into WDM gives [R]DP clients a common data model for displaying tracks, searching records, and linking related information. For example, a map client can read a vessel’s position without understanding the AIS message that supplied it.

A mapping translates source values into the fields defined by the WDM schema and can retain the original message alongside them.

Understand the source

Feeds may provide original messages or values already extracted from them. For example, a CoT feed may supply XML, while an ADS-B feed may combine several radio messages into one JSON snapshot. The mapping can retain that input even when the original messages are unavailable.

The source’s field definitions establish how to interpret those values. An altitude field might contain height above sea level or altitude calculated from air pressure; these belong in different WDM fields. Units and codes for unavailable measurements also matter because they change what a number means.

Choose an Object or Action

An Object represents something clients track over time, such as a unit, aircraft, facility, or weather condition. Each new aircraft position updates the same Object, giving clients the aircraft’s latest state. A CoT event describing a unit likewise maps to that unit’s Object.

An Action represents an activity, such as a task, order, or alert, whose state changes as it progresses. Links connect the activity to the Objects it concerns, so an order and the unit receiving it can be tracked together.

See Modeling with WDM and Action and Objects for examples.

Map known data into typed fields

Typed fields are fields defined by the WDM schema, which specifies their meaning and the kind of value they accept. For example, motion.speedMps holds speed over ground as a number in meters per second. Mapping vessel and aircraft speeds over ground to this field lets clients display and compare them consistently.

WDM is intentionally flexible, so a record uses only the fields whose values are known and meaningful. A track with only identity and position can still appear on a map, with richer fields added when the source supports them. Unknown values stay unset because zero and false can carry real meaning. See Modeling with WDM for this guidance.

Add data richness with details

Object.details and Action.details add data richness through custom structured attributes alongside WDM’s standard fields. They accommodate measurements or context that need application-specific definitions. For example, the weather mapping keeps precipitation categories in standard fields and adds rain rate and accumulation in details.

details is loosely typed: producers choose its field names, value types, and units, so clients must agree on those definitions to interpret the data. [R]DP supports field-based filtering within details, making these attributes useful for selecting records in streams and data feeds. See Modeling with WDM for the structure and a filtering example.

Preserve the original data

[R]DP can carry original messages alongside the mapped fields. A map client may need only a position, while another consumer needs a source-specific attribute or the message in its native format. Retaining the input leaves that information available for future mappings.

externalRefs can contain source data in any format or refer to larger data stored elsewhere. If a feed supplies extracted values instead of original messages, retaining that input preserves what the mapping received. See Preserve Source Data for payload packing and attachments.

Record source, time, and security

Provenance records where data came from and what produced it, so consumers can trace a mapped value back to its source.

provenance.updatedAt holds the source’s update time; externalRefs[].capturedAt records when the input was captured or copied. Keeping both separates the age of the observation from delays in receiving it. Each Object and Action also carries a required security marking for its classification and handling rules.

Updates, expiry, and replay

Objects

Successive observations update the same Object ID, so clients follow one entity over time. Its ttl is an expiry timestamp, based on the source’s validity time or a lifetime measured from the source update. Once it expires, the Object stops appearing in normal reads; the platform publishes a deleted event and later removes the stored record. Both the source’s update frequency and the observation’s useful life matter when choosing that time.

Keeping the original source and expiry times when reprocessing a message prevents old data from gaining a new lifetime. Omitting ttl uses the platform default; persist: true disables automatic expiry. See Object lifecycle for details.

For partial updates, the chosen API determines whether omitted values are retained or cleared; see Publish Object.

Actions

An Action keeps its original content while UpdateActionState changes its state, progress, and optional provenance, letting clients follow a task or alert through its lifecycle. Correcting the original content requires cancellation or replacement. Reusing its ID on retries refers to the same activity, though a repeated create request may return an existing-record error. See Create Action and Update Action State.

Examples

The examples pair source inputs with complete WDM records and explain the field mappings and update behavior.