← OAK Relay evidence oakdefenseltd.comUnclassified · representational · generated 2026-09-24

OAK Relay 0.1.0 — Interface Control Document

Generated by docs/build_icd.py from the running code. Unclassified · representational.

1. Interfaces at a glance

Interface	Direction	Standard / shape	Module
MTF-XML	import / export	XML binding of the message→set→field model	`mtf_codec.py`
COIE	import / export	character-oriented set/field text form; lossless ↔ MTF-XML	`coie.py`
NIEM 6.0	import / export	nc:Document + usmtf: codes + mo:Unit / mo:Track + NDR-pattern oakr: extension; validated against the OASIS schemas; IEPD manifest	`niem_adapter.py`
NCDF	import / export	core entity/event/relationship object with bound confidentiality label — JSON and NIEM-NDR-style XML (NATO MTF→NCDF pattern)	`ncdf_adapter.py`
Packed (DDIL)	import / export	catalogue-aware binary + CRC-16; MTU fragmentation; precedence; store-and-forward	`ddil_transport.py`
JSON	import / export	format-neutral message	`relay_catalogue.py`
Cursor-on-Target	export	CoT 2.0 events validated against the MITRE public-release schema (bundled `cot/cot_event.xsd`); TAK Protocol protobuf via `takproto` (optional)	`relay.py`
STANAG 5066 SIS model	export	S_BIND / S_UNIDATA primitives, SAP table (Annex F), 2048-B MTU, ARQ / non-ARQ (EMCON) service types, TTL, HFCHAT / COSS byte streams for COIE text — client-side model of AComP-5066 Ed A	`s5066.py`
Picture update	export	normalised tracks (with MIL-STD-2525 SIDC) + alerts + taskings for a COP / wargame	`relay.py`
Fused picture	export	persistent correlated picture: identity → name → position-gate correlation, latest-wins with history, report counts, staleness	`relay_picture.py`
UDP link	both	relay-to-relay link: packed message as bearer-MTU frames over UDP, selective repeat (ACK bitmap), delivery receipt (RCPT), store-and-forward of undelivered payloads; MSGID TO / INFO addressing evaluated at the receiver	`relay_link.py`
DIS 7	export	Entity State PDUs for simulation federates (opendis, BSD, optional)	`relay.py`
STIX 2.1	import / export	cyber-incident bundle (incident, indicators with STIX patterns, TLP marking)	`stix_export.py`
STANAG 4774.1 label	export / import	confidentiality label in the ADatP-4774.1 XML shape (PolicyIdentifier / Classification / Category) inside the NCDF object	`ncdf_adapter.py`
Voice corpus	test / evidence	read-aloud script (EN/FR, every type, must-abstain lines), console microphone recorder → corpus with sidecar metadata, radio-like impairments (AWGN at SNR, 300–3400 Hz band, clipping), evaluation: WER, type accuracy, coverage, abstention per language / speaker / condition; synthetic Windows voices as the baseline, human recordings as the relevant-environment evidence	`voice_corpus.py`
Voice	import	WAV → Vosk offline STT (EN/FR, Apache) → spoken-form normaliser → assured draft	`speech_front.py`
MGRS	import	grids in operator text resolved to lat/lon (mgrs / GeoTrans, MIT, optional)	`message_extract.py`
HTTP service	both	JSON endpoints below; Prometheus metrics; HEC / ServiceNow-shaped sinks	`relay_service.py`
Splunk HEC push	export	HTTP Event Collector client: `POST /services/collector/event`, `Authorization: Splunk <token>`, newline-delimited event JSON; store-and-forward on refusal	`relay_integrations.py`
Live HEC collector	test / demo	runs the third-party Vector collector (splunk_hec source → file sink) so the HEC push is proven against software OAK did not write	`relay_collector.py`
ServiceNow push	export	Table API client: `POST /api/now/table/incident` (Bearer or Basic), CRITICAL alerts open tickets automatically; returned sys_id / number kept	`relay_integrations.py`
Prioritisation	export	explainable score = (precedence + content) × staleness with factor evidence; ranked lists; live-scored queue	`relay_priority.py`
Catalogue file	import	`oak-relay-catalogue` JSON — new message types / ratified baselines as data	`relay_catalogue.py`
Chat	import	line-oriented chat listener (TCP, `nick: text`, HFCHAT / IRC / MUC convention) and an HTTP gateway for XMPP / Teams bots → the same assured draft; optional slixmpp room adapter	`relay_chat.py`
STANAG 5066 SIS wire	both	S_ primitives as byte frames over TCP to a 5066 node (bind / unidata / confirm / reject / indication, Annex A-style framing and type codes); loopback node for the bench; conformance against a real node is the M2 target	`s5066_wire.py`
OpenAPI	export	`GET /openapi.json` — OpenAPI 3.0 generated from the same endpoint table as section 2; API-key / Bearer security scheme; TLS via --tls-cert	`relay_service.py`
TAK server (live)	both	TAK streaming protocol client (TCP 8087 / TLS 8089 with client certificate): identity event, CoT out per positioned element, CoT in from other TAK clients → fused picture; runs against the third-party taky server (MIT) or the stdlib CoT relay for tests and demos	`relay_tak.py`
Software modem	both	continuous-phase 2-FSK (1200 Hz / 2200 Hz, 1200 baud; or complex-baseband ±deviation) with preamble, sync, LEN, CRC-16, Hamming(8,4) + interleaver FEC; audio WAV for radio audio ports, int16 / float32 I/Q for SDR and the Proteus ARB; modem-in-the-loop channel for the DDIL bench	`relay_modem.py`
Persistence	—	SQLite write-through store (inbox, fused picture, incidents, chat drafts, tickets) — `--store relay.db`	`relay_store.py`

2. HTTP service endpoints

Method	Path	Body	Returns
GET	`/health`	`—`	{status, product, version, catalogue, formats, message_types, counters, audit_intact}
GET	`/metrics`	`—`	Prometheus text exposition (counters + gauges) — scrape target for Splunk / Dynatrace / Azure Monitor / System Center collectors
GET	`/openapi.json`	`—`	OpenAPI 3.0 description of every endpoint in this table (machine-readable ICD)
GET	`/catalogue`	`—`	live message catalogue JSON (the GFI seam: a ratified baseline is loaded here)
GET	`/formats`	`—`	{formats: [...]}
POST	`/ingest`	`{format, payload}`	{message, errors} — payload is text, or base64 for `packed`
POST	`/export`	`{format, message}`	{payload, bytes}
POST	`/bridge`	`{in_format, out_format, payload}`	{payload, bytes}
POST	`/extract`	`{text, originator?, serial?}`	assured extraction: {msg_type, message, confidence, abstain, missing, evidence, language, rationale, requires_confirmation}
POST	`/stix`	`{message}`	{bundle, bytes} — STIX 2.1 bundle (incident + indicators + TLP marking) for a CYBERINC message
POST	`/dis`	`{message}`	{pdus_b64} — DIS 7 Entity State PDUs (opendis, optional)
POST	`/voice`	`{wav_b64, lang, originator?}`	{transcript, normalized, asr, extraction} — offline speech-to-text (Vosk EN/FR, optional) → spoken-form normaliser → assured draft
POST	`/cot`	`{message}`	{events, schema_valid, tak_proto_b64} — CoT 2.0 events validated against the MITRE public-release schema; TAK Protocol protobuf when takproto is installed
POST	`/picture`	`{message}`	{tracks, alerts, taskings, fused} — the COP / wargame feed; also updates the fused picture; CRITICAL alerts open a ServiceNow-shaped incident
GET	`/picture`	`?now=DTG`	the fused picture: {tracks (pid, ids, reports, sources, first/last DTG, age_min, stale, matched_by), alerts (count), taskings, stats}
POST	`/picture/clear`	`—`	{ok}
POST	`/bearer/send`	`{message \| payload_b64, bearer, ber \| (ebn0_db, js_db), max_retries, seed, to_inbox?}`	{frames, attempts, retries, delivered, airtime_s, bytes, bearer, ber}
POST	`/link/send`	`{message, peer:"host:port", bearer, ber\|js_db+ebn0_db, max_retries, seed}`	transport stats + `receipt` from the receiving station (originator, serial, DTG, status, station) — real UDP link, MTU frames, selective repeat
GET	`/link/status`	`—`	{station, link: {addr, peers, pending, tx_frames, tx_dropped, rx_frames, rx_messages, receipts}}
GET	`/link/outbox`	`—`	{messages: [{seq, peer, bearer, delivered, acknowledged, receipt, ...}]}
POST	`/link/retry`	`{bearer, ber, max_retries}`	{results, pending} — next contact window for held payloads
POST	`/link/start`	`{host, port}`	start the UDP link listener explicitly (otherwise started on first /link/send)
GET	`/voice/script`	`—`	{lines: [{id, lang, type, text, spoken}], conditions} — the read-aloud script for volunteers
POST	`/voice/corpus`	`{wav_b64, line_id, speaker, lang?, condition?, verdict?}`	save a recording + sidecar metadata into the voice corpus (the console's Record button uses this)
GET	`/voice/corpus`	`—`	{recordings: [...], real, synthetic}
GET	`/voice/eval`	`?full=1&limit=N`	run the corpus evaluation (WER, type accuracy, coverage, abstention per language / speaker / condition; full=1 adds the noise + radio-band conditions)
POST	`/tak/connect`	`{host, port, callsign?, tls?, certfile?, keyfile?, cafile?}`	connect to a TAK server (TAK streaming protocol: TCP 8087, or TLS 8089 with a client certificate); sends the identity event; inbound CoT from other clients goes into the fused picture
POST	`/tak/send`	`{message, stale_s?}`	{events, sent} — the message's tracks as CoT events streamed to the connected TAK server
GET	`/tak/status`	`—`	{connected, client: {callsign, uid, sent, received, tracks, pongs}, received_tracks}
POST	`/tak/disconnect`	`—`	{ok}
POST	`/tak/server`	`{host?, port?, prefer_taky?}`	start a live TAK server for a demo or test: taky (MIT, PyPI) if installed, else the stdlib CoT relay; returns {server, addr}
POST	`/modem/encode`	`{message \| payload_b64, fs?, baud?, fec?, format: wav \| iq16 \| cf32, deviation?}`	the message as a 2-FSK waveform file (base64): WAV for a sound card / radio audio port, interleaved int16 or float32 I/Q for an SDR or the Proteus ARB; {samples, seconds, bytes_payload}
POST	`/modem/decode`	`{file_b64, format, fs?, baud?, fec?, deviation?, to_inbox?, ebn0_db? js_db? jammer?}`	demodulate a recording (WAV or I/Q): {frames, messages, decoded: [{bytes, start, snr_db, fec_fixed}]}; optional lab impairment before decoding
GET	`/link/routes`	`—`	{station, routes: {STATION: "host:port", "*": default next hop}, hops}
POST	`/link/routes`	`{routes: {STATION: "host:port"}, remove: [...], hops?}`	set relay next hops (multi-hop store-and-forward: a message addressed to another station is forwarded, duplicates suppressed, hop limit enforced, end-to-end receipt returned along the path)
GET	`/inbox`	`?sort=priority&now=DTG`	{messages: [{message, received_t, stats, picture, fused, priority}]} — messages delivered over a bearer or the link; `sort=priority` ranks by live score
POST	`/inbox/clear`	`—`	{ok}
POST	`/prioritize`	`{messages, now?, half_life_min?}`	{ranked: [{rank, score, precedence_w, content_w, staleness, age_min, time_critical, factors[]}]} — precedence × content × staleness, explained
POST	`/chat/start`	`{host?, port?, room?}`	start the line-oriented chat listener (TCP; one message per line, `nick: text`); returns its address
POST	`/chat/line`	`{nick?, text, source?}`	HTTP gateway for chat lines (XMPP / Teams bots) → assured draft: {msg_type, confidence, abstain, missing, draft, requires_confirmation}
GET	`/chat/drafts`	`—`	{drafts: [...]} — non-abstaining drafts awaiting operator confirmation
GET	`/chat/status`	`—`	{addr, room, connections, lines, drafts, abstained, xmpp}
POST	`/integrations/configure`	`{splunk_hec_url, splunk_hec_token, servicenow_url, servicenow_token \| servicenow_user+password, auto_push}`	outbound push targets (also via env OAK_RELAY_SPLUNK_HEC_URL / _TOKEN, OAK_RELAY_SERVICENOW_URL / _TOKEN); returns status
POST	`/integrations/push`	`—`	deliver pending events to Splunk HEC (`/services/collector/event`, `Authorization: Splunk <token>`, NDJSON) and incidents to the ServiceNow Table API (`/api/now/table/incident`); refused items stay pending
GET	`/integrations/status`	`—`	{configured, auto_push, targets, pushed, failed, pending_events, pending_incidents, tickets [{local, sys_id, remote}], last}
GET	`/integrations/splunk-hec`	`?since=N`	{events, next} — Splunk HTTP-Event-Collector-shaped batch (pull)
GET	`/integrations/servicenow/incidents`	`—`	{result: [incident records]} — ServiceNow-incident-shaped (pull)
POST	`/validate`	`{message}`	{errors, msg_type} — catalogue validation without export
POST	`/validate/niem`	`{message \| payload}`	{available, valid, errors} — validation against the OASIS NIEM 6.0 schemas (needs lxml + model checkout)
GET	`/samples`	`—`	{messages: [...]} — the nine representational sample messages
GET	`/audit`	`—`	{intact, count, head} — tamper-evident hash chain
GET	`/`	`—`	the bilingual (EN/FR) operator console (also /console), served by the same process

3. Registered formats

coie, json, mtf-xml, ncdf, niem, packed

A new format is added with MessageBridge.register(name, encoder, decoder); a new message type with a catalogue file — no core change either way.

4. Message catalogue (MTF-XML binding)

MTF-XML binding (namespace urn:oak:relay:mtf-xml:1) for catalogue 'OAK Relay representational catalogue' v1.1

Message type=SITREP  [C2; LAND/AIR/MARITIME/SPACE/CYBER/JOINT] — situation report
  Set id=MSGID (1)
    Field id=originator type=text  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=serial type=int  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=dtg type=dtg  → NIEM nc:DocumentCreationDate/nc:DateTime
    Field id=precedence type=enum enum=['FLASH', 'IMMEDIATE', 'PRIORITY', 'ROUTINE']  → NIEM usmtf:MessagePrecedenceCode
    Field id=classification type=enum enum=['UNCLAS', 'PROTECTED_A', 'PROTECTED_B', 'CONFIDENTIAL', 'SECRET', 'TOP_SECRET']  → NIEM usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText
    Field id=reference type=text optional
    Field id=to type=text optional
    Field id=info type=text optional
    Field id=exer_oper type=text optional
    Field id=ack_req type=bool optional
  Set id=PERIOD (1)
    Field id=from_dtg type=dtg  → NIEM nc:DateTime
    Field id=to_dtg type=dtg  → NIEM nc:DateTime
  Set id=OWNSIT (1)
    Field id=unit type=text  → NIEM mo:Unit/mo:UnitName
    Field id=location type=latlon  → NIEM mo:UnitPresentLocation/nc:Location2DGeospatialCoordinate
    Field id=strength type=enum enum=['FULL', 'REDUCED', 'MARGINAL', 'INEFFECTIVE']
    Field id=posture type=text optional
  Set id=ENSIT (0..n)
    Field id=unit type=text  → NIEM mo:Unit/mo:UnitName
    Field id=location type=latlon  → NIEM mo:UnitPresentLocation/nc:Location2DGeospatialCoordinate
    Field id=activity type=text
    Field id=assessment type=text optional
  Set id=TRACKS (0..1)
    Field id=hostile type=int
    Field id=suspect type=int
    Field id=friend type=int
    Field id=unknown type=int
  Set id=ALERT (0..n)
    Field id=level type=enum enum=['INFO', 'WARNING', 'CRITICAL']
    Field id=text type=text
  Set id=NARR (0..1)
    Field id=text type=text
Message type=CTC  [INTEL; AIR/MARITIME/SPACE] — contact / track report
  Set id=MSGID (1)
    Field id=originator type=text  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=serial type=int  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=dtg type=dtg  → NIEM nc:DocumentCreationDate/nc:DateTime
    Field id=precedence type=enum enum=['FLASH', 'IMMEDIATE', 'PRIORITY', 'ROUTINE']  → NIEM usmtf:MessagePrecedenceCode
    Field id=classification type=enum enum=['UNCLAS', 'PROTECTED_A', 'PROTECTED_B', 'CONFIDENTIAL', 'SECRET', 'TOP_SECRET']  → NIEM usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText
    Field id=reference type=text optional
    Field id=to type=text optional
    Field id=info type=text optional
    Field id=exer_oper type=text optional
    Field id=ack_req type=bool optional
  Set id=CONTACT (1..n)
    Field id=track_id type=text  → NIEM mo:Track/mo:TrackIdentification/nc:IdentificationID
    Field id=category type=enum enum=['AIR', 'SURF', 'SUB', 'LAND', 'SPACE', 'UAS']
    Field id=affiliation type=enum enum=['FRIEND', 'HOSTILE', 'NEUTRAL', 'SUSPECT', 'UNKNOWN']  → NIEM mo:ObservedObjectAllegianceCountry (seam)
    Field id=position type=latlon  → NIEM mo:TrackPoint/mo:TrackPointLocation/nc:Location2DGeospatialCoordinate
    Field id=course_deg type=float optional  → NIEM mo:CourseAngleDegreesMeasure (seam)
    Field id=speed_kt type=float optional
    Field id=altitude_m type=float optional
    Field id=sensor type=text optional
    Field id=confidence type=float optional
    Field id=dtg type=dtg  → NIEM nc:DateTime
Message type=FRAGO  [C2; LAND/JOINT] — fragmentary order
  Set id=MSGID (1)
    Field id=originator type=text  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=serial type=int  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=dtg type=dtg  → NIEM nc:DocumentCreationDate/nc:DateTime
    Field id=precedence type=enum enum=['FLASH', 'IMMEDIATE', 'PRIORITY', 'ROUTINE']  → NIEM usmtf:MessagePrecedenceCode
    Field id=classification type=enum enum=['UNCLAS', 'PROTECTED_A', 'PROTECTED_B', 'CONFIDENTIAL', 'SECRET', 'TOP_SECRET']  → NIEM usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText
    Field id=reference type=text optional
    Field id=to type=text optional
    Field id=info type=text optional
    Field id=exer_oper type=text optional
    Field id=ack_req type=bool optional
  Set id=SITUATION (1)
    Field id=text type=text
  Set id=MISSION (1)
    Field id=text type=text
  Set id=TASK (1..n)
    Field id=unit type=text
    Field id=task type=text
    Field id=effective_dtg type=dtg  → NIEM nc:DateTime
    Field id=location type=latlon optional  → NIEM nc:Location/nc:Location2DGeospatialCoordinate
  Set id=SVCSPT (0..1)
    Field id=text type=text
  Set id=CMDSIG (1)
    Field id=commander type=text
    Field id=net type=text
Message type=RFI  [INTEL; JOINT] — request for information
  Set id=MSGID (1)
    Field id=originator type=text  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=serial type=int  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=dtg type=dtg  → NIEM nc:DocumentCreationDate/nc:DateTime
    Field id=precedence type=enum enum=['FLASH', 'IMMEDIATE', 'PRIORITY', 'ROUTINE']  → NIEM usmtf:MessagePrecedenceCode
    Field id=classification type=enum enum=['UNCLAS', 'PROTECTED_A', 'PROTECTED_B', 'CONFIDENTIAL', 'SECRET', 'TOP_SECRET']  → NIEM usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText
    Field id=reference type=text optional
    Field id=to type=text optional
    Field id=info type=text optional
    Field id=exer_oper type=text optional
    Field id=ack_req type=bool optional
  Set id=REQUEST (1)
    Field id=rfi_id type=text
    Field id=question type=text
    Field id=ltiov type=dtg  → NIEM nc:DateTime
    Field id=priority type=enum enum=['HIGH', 'MEDIUM', 'LOW']
  Set id=AREA (0..1)
    Field id=center type=latlon  → NIEM nc:Location/nc:Location2DGeospatialCoordinate
    Field id=radius_km type=float
  Set id=RESPONSE (0..1)
    Field id=text type=text
    Field id=source type=text optional
Message type=MEDEVAC  [MEDICAL; LAND/JOINT] — medical evacuation request (9-line)
  Set id=MSGID (1)
    Field id=originator type=text  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=serial type=int  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=dtg type=dtg  → NIEM nc:DocumentCreationDate/nc:DateTime
    Field id=precedence type=enum enum=['FLASH', 'IMMEDIATE', 'PRIORITY', 'ROUTINE']  → NIEM usmtf:MessagePrecedenceCode
    Field id=classification type=enum enum=['UNCLAS', 'PROTECTED_A', 'PROTECTED_B', 'CONFIDENTIAL', 'SECRET', 'TOP_SECRET']  → NIEM usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText
    Field id=reference type=text optional
    Field id=to type=text optional
    Field id=info type=text optional
    Field id=exer_oper type=text optional
    Field id=ack_req type=bool optional
  Set id=LINE1 (1)
    Field id=pickup type=latlon  → NIEM nc:Location/nc:Location2DGeospatialCoordinate
  Set id=LINE2 (1)
    Field id=freq_mhz type=float
    Field id=callsign type=text
  Set id=LINE3 (1)
    Field id=urgent type=int
    Field id=priority type=int
    Field id=routine type=int
  Set id=LINE4 (1)
    Field id=equipment type=enum enum=['NONE', 'HOIST', 'EXTRACTION', 'VENTILATOR']
  Set id=LINE5 (1)
    Field id=litter type=int
    Field id=ambulatory type=int
  Set id=LINE6 (1)
    Field id=security type=enum enum=['NO_ENEMY', 'POSSIBLE_ENEMY', 'ENEMY_IN_AREA', 'ARMED_ESCORT_REQUIRED']
  Set id=LINE7 (1)
    Field id=marking type=enum enum=['PANELS', 'PYRO', 'SMOKE', 'NONE', 'OTHER']
  Set id=LINE8 (1)
    Field id=status type=enum enum=['US_MIL', 'COALITION_MIL', 'CIVILIAN', 'EPW']
  Set id=LINE9 (1)
    Field id=terrain type=text
Message type=CFF  [FIRES; LAND/MARITIME] — call for fire + message to observer
  Set id=MSGID (1)
    Field id=originator type=text  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=serial type=int  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=dtg type=dtg  → NIEM nc:DocumentCreationDate/nc:DateTime
    Field id=precedence type=enum enum=['FLASH', 'IMMEDIATE', 'PRIORITY', 'ROUTINE']  → NIEM usmtf:MessagePrecedenceCode
    Field id=classification type=enum enum=['UNCLAS', 'PROTECTED_A', 'PROTECTED_B', 'CONFIDENTIAL', 'SECRET', 'TOP_SECRET']  → NIEM usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText
    Field id=reference type=text optional
    Field id=to type=text optional
    Field id=info type=text optional
    Field id=exer_oper type=text optional
    Field id=ack_req type=bool optional
  Set id=OBSERVER (1)
    Field id=id type=text
    Field id=location type=latlon  → NIEM nc:Location/nc:Location2DGeospatialCoordinate
  Set id=TARGET (1)
    Field id=description type=text
    Field id=location type=latlon  → NIEM nc:Location/nc:Location2DGeospatialCoordinate
  Set id=ENGAGE (1)
    Field id=munition type=text
    Field id=rounds type=int
    Field id=sheaf type=text optional
    Field id=method type=text optional
  Set id=MTO (0..1)
    Field id=in_range type=bool
    Field id=tof_s type=float optional
    Field id=charge type=text optional
Message type=SPACEEVT  [INTEL; SPACE] — space domain event
  Set id=MSGID (1)
    Field id=originator type=text  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=serial type=int  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=dtg type=dtg  → NIEM nc:DocumentCreationDate/nc:DateTime
    Field id=precedence type=enum enum=['FLASH', 'IMMEDIATE', 'PRIORITY', 'ROUTINE']  → NIEM usmtf:MessagePrecedenceCode
    Field id=classification type=enum enum=['UNCLAS', 'PROTECTED_A', 'PROTECTED_B', 'CONFIDENTIAL', 'SECRET', 'TOP_SECRET']  → NIEM usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText
    Field id=reference type=text optional
    Field id=to type=text optional
    Field id=info type=text optional
    Field id=exer_oper type=text optional
    Field id=ack_req type=bool optional
  Set id=EVENT (1)
    Field id=object_id type=text
    Field id=event_type type=enum enum=['CONJUNCTION', 'MANEUVER', 'DECAY', 'RPO', 'LAUNCH', 'BREAKUP']
    Field id=dtg type=dtg  → NIEM nc:DateTime
    Field id=description type=text
  Set id=ORBIT (0..1)
    Field id=apogee_km type=float
    Field id=perigee_km type=float
    Field id=inclination_deg type=float
Message type=CYBERINC  [INTEL; CYBER] — cyber incident report
  Set id=MSGID (1)
    Field id=originator type=text  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=serial type=int  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=dtg type=dtg  → NIEM nc:DocumentCreationDate/nc:DateTime
    Field id=precedence type=enum enum=['FLASH', 'IMMEDIATE', 'PRIORITY', 'ROUTINE']  → NIEM usmtf:MessagePrecedenceCode
    Field id=classification type=enum enum=['UNCLAS', 'PROTECTED_A', 'PROTECTED_B', 'CONFIDENTIAL', 'SECRET', 'TOP_SECRET']  → NIEM usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText
    Field id=reference type=text optional
    Field id=to type=text optional
    Field id=info type=text optional
    Field id=exer_oper type=text optional
    Field id=ack_req type=bool optional
  Set id=INCIDENT (1)
    Field id=incident_id type=text
    Field id=category type=enum enum=['MALWARE', 'INTRUSION', 'DOS', 'PHISHING', 'EXFIL', 'OTHER']
    Field id=severity type=enum enum=['LOW', 'MEDIUM', 'HIGH', 'CRITICAL']
    Field id=affected type=text
    Field id=dtg type=dtg  → NIEM nc:DateTime
  Set id=IOC (0..n)
    Field id=ioc_type type=enum enum=['IP', 'DOMAIN', 'HASH', 'URL', 'EMAIL']
    Field id=value type=text
Message type=LOGSTAT  [LOGISTICS; LAND/MARITIME/AIR/JOINT] — logistics status report
  Set id=MSGID (1)
    Field id=originator type=text  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=serial type=int  → NIEM nc:DocumentIdentification/nc:IdentificationID
    Field id=dtg type=dtg  → NIEM nc:DocumentCreationDate/nc:DateTime
    Field id=precedence type=enum enum=['FLASH', 'IMMEDIATE', 'PRIORITY', 'ROUTINE']  → NIEM usmtf:MessagePrecedenceCode
    Field id=classification type=enum enum=['UNCLAS', 'PROTECTED_A', 'PROTECTED_B', 'CONFIDENTIAL', 'SECRET', 'TOP_SECRET']  → NIEM usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText
    Field id=reference type=text optional
    Field id=to type=text optional
    Field id=info type=text optional
    Field id=exer_oper type=text optional
    Field id=ack_req type=bool optional
  Set id=SUPPLY (1..n)
    Field id=supply_class type=enum enum=['I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX']
    Field id=on_hand_pct type=float
    Field id=days_of_supply type=float
  Set id=REQUEST (0..1)
    Field id=text type=text

5. Wire examples (SITREP sample)

5.1 MTF-XML

<mtf:Message xmlns:mtf="urn:oak:relay:mtf-xml:1" type="SITREP" catalogue="OAK Relay representational catalogue" version="1.1">
  <mtf:Set id="MSGID">
    <mtf:Field id="originator">OAK-BMS</mtf:Field>
    <mtf:Field id="serial">1</mtf:Field>
    <mtf:Field id="dtg">121200ZSEP26</mtf:Field>
    <mtf:Field id="precedence">PRIORITY</mtf:Field>
    <mtf:Field id="classification">UNCLAS</mtf:Field>
  </mtf:Set>
  <mtf:Set id="PERIOD">
    <mtf:Field id="from_dtg">120600ZSEP26</mtf:Field>
    <mtf:Field id="to_dtg">121200ZSEP26</mtf:Field>
  </mtf:Set>
  <mtf:Set id="OWNSIT">
    <mtf:Field id="unit">EW-1</mtf:Field>
    <mtf:Field id="location">44.65000,-76.50000</mtf:Field>
    <mtf:Field id="strength">FULL</mtf:Field>
    <mtf:Field id="posture">Static, jammer on</mtf:Field>
  </mtf:Set>
  <mtf:Set id="ENSIT">
    <mtf:Field id="unit">SAM BN</mtf:Field>
    <mtf:Field id="location">44.90000,-76.10000</mtf:Field>
    <mtf:Field id="activity">Fire-control radar active</mtf:Field>
    <mtf:Field id="assessment">Threat to route BLUE</mtf:Field>
  </mtf:Set>
  <mtf:Set id="ENSIT">
    <mtf:Field id="unit">UAS SWARM</mtf:Field>
    <mtf:Field id="location">44.70000,-76.30000</mtf:Field>
    <mtf:Field id="activity">6 x group-2 UAS orbiting</mtf:Field>
  </mtf:Set>
  <mtf:Set id="TRACKS">
    <mtf:Field id="hostile">3</mtf:Field>
    <mtf:Field id="suspect">2</mtf:Field>
    <mtf:Field id="friend">12</mtf:Field>
    <mtf:Field id="unknown">1</mtf:Field>
  </mtf:Set>
  <mtf:Set id="ALERT">
    <mtf:Field id="level">WARNING</mtf:Field>
    <mtf:Field id="text">SAM radar illuminating ROUTE BLUE</mtf:Field>
  </mtf:Set>
  <mtf:Set id="NARR">
    <mtf:Field id="text">Jamming effective; request EO-IR cue on swarm.</mtf:Field>
  </mtf:Set>
</mtf:Message>

5.2 COIE

UNCLAS
MSGID/SITREP/OAK-BMS/1/121200ZSEP26/PRIORITY/UNCLAS/-/-/-/-/-//
PERIOD/120600ZSEP26/121200ZSEP26//
OWNSIT/EW-1/44.65000,-76.50000/FULL/STATIC, JAMMER ON//
ENSIT/SAM BN/44.90000,-76.10000/FIRE-CONTROL RADAR ACTIVE/THREAT TO ROUTE BLUE//
ENSIT/UAS SWARM/44.70000,-76.30000/6 X GROUP-2 UAS ORBITING/-//
TRACKS/3/2/12/1//
ALERT/WARNING/SAM RADAR ILLUMINATING ROUTE BLUE//
NARR/JAMMING EFFECTIVE; REQUEST EO-IR CUE ON SWARM.//
UNCLAS

5.3 NIEM (excerpt)

<nc:Document xmlns:mo="https://docs.oasis-open.org/niemopen/ns/model/domains/militaryOperations/6.0/" xmlns:nc="https://docs.oasis-open.org/niemopen/ns/model/niem-core/6.0/" xmlns:oakr="urn:oak:relay:niem-ext:2" xmlns:usmtf="https://docs.oasis-open.org/niemopen/ns/model/domains/usmtf/6.0/">
  <nc:DocumentCategoryText>SITREP</nc:DocumentCategoryText>
  <nc:DocumentCreationDate>
    <nc:DateTime>2026-09-12T12:00:00Z</nc:DateTime>
  </nc:DocumentCreationDate>
  <nc:DocumentDescriptionText>situation report</nc:DocumentDescriptionText>
  <nc:DocumentIdentification>
    <nc:IdentificationID>OAK-BMS-1</nc:IdentificationID>
    <nc:IdentificationCategoryText>originator-serial</nc:IdentificationCategoryText>
  </nc:DocumentIdentification>
  <nc:DocumentSupplementalMarkingText>UNCLAS</nc:DocumentSupplementalMarkingText>
  <oakr:C2MessageAugmentation>
    <usmtf:MessagePrecedenceCode>PP</usmtf:MessagePrecedenceCode>
    <usmtf:MessageSecurityClassificationCode>U</usmtf:MessageSecurityClassificationCode>
    <oakr:CatalogueNameText>OAK Relay representational catalogue</oakr:CatalogueNameText>
    <oakr:CatalogueVersionText>1.1</oakr:CatalogueVersionText>
    <mo:Unit>
      <mo:UnitName>EW-1</mo:UnitName>
      <mo:UnitPresentLocation>
        <nc:Location2DGeospatialCoordinate>
          <nc:GeographicCoordinateLatitude>
            <nc:LatitudeDegreeValue>44.65000</nc:LatitudeDegreeValue>
  ...

5.4 NCDF (excerpt)

{
  "format": "oak-relay-ncdf",
  "version": "1.0",
  "id": "OAK-BMS-1",
  "label": {
    "policyIdentifier": "CAN",
    "classification": "UNCLASSIFIED",
    "categories": []
  },
  "provenance": {
    "originator": "OAK-BMS",
    "serial": 1,
    "time": "121200ZSEP26",
    "catalogue": "OAK Relay representational catalogue",
    "catalogue_version": "1.1"
  },
  "binding": "802bbba1fcb02a8b448b4ae5e392c80bd7a52a97b27fadf9e6b52059a2aa1828"
,
  "entities": [...], "events": [...], "relationships": [...], "source_message": {...}
}

5.5 Packed (DDIL)

4f52010008001f0000074f414b2d424d5302b088d90602000103c885d906b088d906020f000445572d31682144003045… (280 bytes, CRC-16 trailer)

6. NIEM IEPD manifest

{
  "iepd": "OAK Relay C2 Message Exchange",
  "version": "1.1",
  "niem_version": "6.0 (OASIS NIEMOpen Project Specification 02, CC-BY 4.0)",
  "namespaces": {
    "nc": "https://docs.oasis-open.org/niemopen/ns/model/niem-core/6.0/",
    "mo": "https://docs.oasis-open.org/niemopen/ns/model/domains/militaryOperations/6.0/",
    "usmtf": "https://docs.oasis-open.org/niemopen/ns/model/domains/usmtf/6.0/",
    "structures": "https://docs.oasis-open.org/niemopen/ns/model/structures/6.0/",
    "oakr": "urn:oak:relay:niem-ext:2"
  },
  "core_components_used": [
    "nc:Document",
    "nc:DocumentCategoryText",
    "nc:DocumentCreationDate",
    "nc:DateTime",
    "nc:DocumentDescriptionText",
    "nc:DocumentIdentification",
    "nc:IdentificationID",
    "nc:IdentificationCategoryText",
    "nc:DocumentSupplementalMarkingText",
    "nc:DocumentAugmentationPoint",
    "nc:Location",
    "nc:Location2DGeospatialCoordinate",
    "nc:GeographicCoordinateLatitude",
    "nc:LatitudeDegreeValue",
    "nc:GeographicCoordinateLongitude",
    "nc:LongitudeDegreeValue",
    "nc:TextType"
  ],
  "domain_components_used": [
    "usmtf:MessagePrecedenceCode",
    "usmtf:MessageSecurityClassificationCode",
    "mo:Unit",
    "mo:UnitName",
    "mo:UnitPresentLocation",
    "mo:Track",
    "mo:TrackIdentification",
    "mo:TrackPoint",
    "mo:TrackPointLocation"
  ],
  "extension_schema": "niem/oakr-extension.xsd.tmpl",
  "extension_components": [
    "oakr:C2MessageAugmentation",
    "oakr:MessageSet",
    "oakr:SetID",
    "oakr:Field",
    "oakr:FieldID",
    "oakr:FieldTypeText",
    "oakr:FieldValueText",
    "oakr:CatalogueNameText",
    "oakr:CatalogueVersionText"
  ],
  "code_mappings": {
    "precedence": {
      "FLASH": "ZZ",
      "IMMEDIATE": "OO",
      "PRIORITY": "PP",
      "ROUTINE": "RR"
    },
    "classification": {
      "UNCLAS": "U",
      "PROTECTED_A": "U",
      "PROTECTED_B": "U",
      "CONFIDENTIAL": "C",
      "SECRET": "S",
      "TOP_SECRET": "T"
    }
  },
  "exchanges": [
    {
      "message_type": "SITREP",
      "service": "C2",
      "domains": [
        "LAND",
        "AIR",
        "MARITIME",
        "SPACE",
        "CYBER",
        "JOINT"
      ],
      "sets": [
        "MSGID",
        "PERIOD",
        "OWNSIT",
        "ENSIT",
        "TRACKS",
        "ALERT",
        "NARR"
      ],
      "niem_property_map": {
        "MSGID.originator": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.serial": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.dtg": "nc:DocumentCreationDate/nc:DateTime",
        "MSGID.precedence": "usmtf:MessagePrecedenceCode",
        "MSGID.classification": "usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText",
        "PERIOD.from_dtg": "nc:DateTime",
        "PERIOD.to_dtg": "nc:DateTime",
        "OWNSIT.unit": "mo:Unit/mo:UnitName",
        "OWNSIT.location": "mo:UnitPresentLocation/nc:Location2DGeospatialCoordinate",
        "ENSIT.unit": "mo:Unit/mo:UnitName",
        "ENSIT.location": "mo:UnitPresentLocation/nc:Location2DGeospatialCoordinate"
      }
    },
    {
      "message_type": "CTC",
      "service": "INTEL",
      "domains": [
        "AIR",
        "MARITIME",
        "SPACE"
      ],
      "sets": [
        "MSGID",
        "CONTACT"
      ],
      "niem_property_map": {
        "MSGID.originator": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.serial": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.dtg": "nc:DocumentCreationDate/nc:DateTime",
        "MSGID.precedence": "usmtf:MessagePrecedenceCode",
        "MSGID.classification": "usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText",
        "CONTACT.track_id": "mo:Track/mo:TrackIdentification/nc:IdentificationID",
        "CONTACT.affiliation": "mo:ObservedObjectAllegianceCountry (seam)",
        "CONTACT.position": "mo:TrackPoint/mo:TrackPointLocation/nc:Location2DGeospatialCoordinate",
        "CONTACT.course_deg": "mo:CourseAngleDegreesMeasure (seam)",
        "CONTACT.dtg": "nc:DateTime"
      }
    },
    {
      "message_type": "FRAGO",
      "service": "C2",
      "domains": [
        "LAND",
        "JOINT"
      ],
      "sets": [
        "MSGID",
        "SITUATION",
        "MISSION",
        "TASK",
        "SVCSPT",
        "CMDSIG"
      ],
      "niem_property_map": {
        "MSGID.originator": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.serial": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.dtg": "nc:DocumentCreationDate/nc:DateTime",
        "MSGID.precedence": "usmtf:MessagePrecedenceCode",
        "MSGID.classification": "usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText",
        "TASK.effective_dtg": "nc:DateTime",
        "TASK.location": "nc:Location/nc:Location2DGeospatialCoordinate"
      }
    },
    {
      "message_type": "RFI",
      "service": "INTEL",
      "domains": [
        "JOINT"
      ],
      "sets": [
        "MSGID",
        "REQUEST",
        "AREA",
        "RESPONSE"
      ],
      "niem_property_map": {
        "MSGID.originator": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.serial": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.dtg": "nc:DocumentCreationDate/nc:DateTime",
        "MSGID.precedence": "usmtf:MessagePrecedenceCode",
        "MSGID.classification": "usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText",
        "REQUEST.ltiov": "nc:DateTime",
        "AREA.center": "nc:Location/nc:Location2DGeospatialCoordinate"
      }
    },
    {
      "message_type": "MEDEVAC",
      "service": "MEDICAL",
      "domains": [
        "LAND",
        "JOINT"
      ],
      "sets": [
        "MSGID",
        "LINE1",
        "LINE2",
        "LINE3",
        "LINE4",
        "LINE5",
        "LINE6",
        "LINE7",
        "LINE8",
        "LINE9"
      ],
      "niem_property_map": {
        "MSGID.originator": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.serial": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.dtg": "nc:DocumentCreationDate/nc:DateTime",
        "MSGID.precedence": "usmtf:MessagePrecedenceCode",
        "MSGID.classification": "usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText",
        "LINE1.pickup": "nc:Location/nc:Location2DGeospatialCoordinate"
      }
    },
    {
      "message_type": "CFF",
      "service": "FIRES",
      "domains": [
        "LAND",
        "MARITIME"
      ],
      "sets": [
        "MSGID",
        "OBSERVER",
        "TARGET",
        "ENGAGE",
        "MTO"
      ],
      "niem_property_map": {
        "MSGID.originator": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.serial": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.dtg": "nc:DocumentCreationDate/nc:DateTime",
        "MSGID.precedence": "usmtf:MessagePrecedenceCode",
        "MSGID.classification": "usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText",
        "OBSERVER.location": "nc:Location/nc:Location2DGeospatialCoordinate",
        "TARGET.location": "nc:Location/nc:Location2DGeospatialCoordinate"
      }
    },
    {
      "message_type": "SPACEEVT",
      "service": "INTEL",
      "domains": [
        "SPACE"
      ],
      "sets": [
        "MSGID",
        "EVENT",
        "ORBIT"
      ],
      "niem_property_map": {
        "MSGID.originator": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.serial": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.dtg": "nc:DocumentCreationDate/nc:DateTime",
        "MSGID.precedence": "usmtf:MessagePrecedenceCode",
        "MSGID.classification": "usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText",
        "EVENT.dtg": "nc:DateTime"
      }
    },
    {
      "message_type": "CYBERINC",
      "service": "INTEL",
      "domains": [
        "CYBER"
      ],
      "sets": [
        "MSGID",
        "INCIDENT",
        "IOC"
      ],
      "niem_property_map": {
        "MSGID.originator": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.serial": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.dtg": "nc:DocumentCreationDate/nc:DateTime",
        "MSGID.precedence": "usmtf:MessagePrecedenceCode",
        "MSGID.classification": "usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText",
        "INCIDENT.dtg": "nc:DateTime"
      }
    },
    {
      "message_type": "LOGSTAT",
      "service": "LOGISTICS",
      "domains": [
        "LAND",
        "MARITIME",
        "AIR",
        "JOINT"
      ],
      "sets": [
        "MSGID",
        "SUPPLY",
        "REQUEST"
      ],
      "niem_property_map": {
        "MSGID.originator": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.serial": "nc:DocumentIdentification/nc:IdentificationID",
        "MSGID.dtg": "nc:DocumentCreationDate/nc:DateTime",
        "MSGID.precedence": "usmtf:MessagePrecedenceCode",
        "MSGID.classification": "usmtf:MessageSecurityClassificationCode + nc:DocumentSupplementalMarkingText"
      }
    }
  ],
  "validation": "instances validate against the OASIS NIEM 6.0 schemas (niem-core, structures, mo, usmtf) plus the OAK extension with validate_niem() (lxml)"
}

7. Bearer profiles (representational)

Bearer	bit/s	MTU (B)	latency (s)	note
VLF	200	48	0.1	one-way broadcast class; hundreds of bit/s
LF	300	64	0.1	low-rate long-haul
HF	2400	192	0.5	narrowband HF data modem class (kbit/s); ARQ
HF-WB	9600	512	0.5	wideband HF class
UHF-LOS	16000	512	0.05	tactical VHF/UHF net data class
UHF-SATCOM	9600	512	0.3	narrowband SATCOM channel class
SATCOM-WB	64000	1024	0.3	wideband SATCOM class

8. Integration into experimentation / simulation / wargaming (EO-5)

relay.picture_update(msg) → {tracks, alerts, taskings} — the shape the OAK BMS live-feed ingest, the Tactical Operations Console and the Joint Wargame consume.
relay_picture.Picture — the fused picture (GET /picture): every received message is correlated into one persistent set of tracks (report counts, sources, age, stale flag), de-duplicated alerts and latest taskings — consumers read one picture, not N message extracts.
relay_link.LinkNode — two relay stations exchange packed messages over a real UDP link with selective repeat and delivery receipts; the receiver evaluates MSGID TO / INFO against its station name (addressed_to_me, relay_needed).
relay.message_to_cot(msg) → CoT events — TAK-class tools and the EW SUITE tactical_interop bridge (which also re-emits Link 16 / DIS / VMF / NFFI / OTH-GOLD).
ddil_transport.bench*() — messages are pushed through a physics-modelled bearer (BER vs Eb/N0 and jammer J/S) so a wargame can degrade the comms picture deterministically (seeded).
Every ingest / bridge / extraction / bearer send is written to the tamper-evident audit chain (relay_audit.py) for after-action review.

9. Honesty notes

MTF-XML / COIE implement the structural message model and bindings; ratified APP-11 / ADatP-3 / MIL-STD-6040 baselines are not reproduced and load as GFI through the catalogue seam.
NIEM 6.0 (OASIS NIEMOpen PS02, CC-BY 4.0): instances validate against the published niem-core, structures, Military Operations and USMTF schemas; the oakr: extension schema follows the NIEM NDR augmentation pattern.
The NCDF object is a representational core-data model rendered in JSON and in NIEM-NDR-style XML following the documented NATO MTF→NCDF design pattern (NIEM methodology); the ratified NATO framework re-points its vocabularies.
Bearer profiles are order-of-magnitude, unclassified planning values.
s5066.py is a client-side model of the STANAG 5066 subnetwork interface (AComP-5066 Ed A, NATO UNCLASSIFIED, releasable to the Interoperability Platform) used for sizing, prioritising and benching; it is not an implementation of the HF sublayers. The standard itself is not redistributed.
CoT schemas are the MITRE public-release CoT 2.0 schemas (Approved for Public Release; Distribution Unlimited), bundled with attribution.
The NIEM extension schema and sample instances are additionally checked with the NIEMOpen Common Model Format tool (cmftool 1.0, Apache-2.0): see docs/CMF_REPORT.md.