SOF Data Model (SDM)

This page provides developer resources for the SOF Data Model (SDM). For the conceptual overview, entity model, history API summary, and transformer list, see SOF Data Model.

Download Proto and OpenAPI Specs

Download the SDM protobuf and OpenAPI source bundle:

Download SDM proto and OpenAPI specs

The archive includes the SDM protobuf definitions, Buf dependency manifests, and the generated OpenAPI schema. It does not bundle third-party protobuf dependencies. Consumers should resolve those dependencies through Buf or their language-specific protobuf toolchain.

Source Files Included

Path Contents

proto/raft/sdm/v1beta/

SDM public entity, query, security, shape, provenance, and service protobuf definitions.

buf.yaml

Buf module configuration listing protobuf dependencies.

buf.lock

Locked Buf dependency versions.

spec/sdm-swagger.yaml

OpenAPI schema generated from the SDM service definitions.

API Implementation Notes

The public service is raft.sdm.v1beta.EntityService. It supports ConnectRPC and native gRPC on the same service path, with REST transcoding for unary methods.

Current public methods include:

  • PublishEntity

  • PublishEntities

  • SearchEntities

  • GetEntity

  • StreamEntities

  • ReplayEntityHistory

  • GetEntityHistory

  • GetEntityAtTime

  • SearchEntitiesAtTime

History APIs use recorded_at for replay and audit order, and source_updated_at from entity.provenance.updated_at for source-timeline reconstruction.

See the SDM API Reference for the rendered OpenAPI spec.

Example Queries and Searches

The examples below use REST-transcoded endpoints from spec/sdm-swagger.yaml. Set BASE to the external API base URL for the deployment.

BASE="https://node-a.example.com"
AUTH_HEADER="Authorization: Bearer ${TOKEN}"

Search Current Entities by Domain and Affiliation

curl -sS -X POST "${BASE}/api/v1beta/sdm/entities/search" \
  -H "${AUTH_HEADER}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "domains": ["ENTITY_DOMAIN_GROUND"],
      "affiliations": ["AFFILIATION_FRIEND"],
      "labels": {
        "mission": "training"
      }
    },
    "pageSize": 50
  }' | jq .

Search Current Entities in a Bounding Box

curl -sS -X POST "${BASE}/api/v1beta/sdm/entities/search" \
  -H "${AUTH_HEADER}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "boundingBox": {
        "minLatitudeDegrees": 38.80,
        "minLongitudeDegrees": -77.20,
        "maxLatitudeDegrees": 39.00,
        "maxLongitudeDegrees": -76.90
      }
    },
    "pageSize": 100
  }' | jq .

Replay Accepted History Records

curl -sS -X POST "${BASE}/api/v1beta/sdm/entities/history/replay" \
  -H "${AUTH_HEADER}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "domains": ["ENTITY_DOMAIN_AIR"]
    },
    "startTime": "2026-08-10T00:00:00Z",
    "endTime": "2026-08-10T01:00:00Z",
    "pageSize": 100
  }' | jq .

Get One Entity History

ENTITY_ID="track-001"

curl -sS "${BASE}/api/v1beta/sdm/entities/${ENTITY_ID}/history?pageSize=25&ascending=true" \
  -H "${AUTH_HEADER}" | jq .

Reconstruct Entity State at Source Time

ENTITY_ID="track-001"
AT_TIME="2026-08-10T00:30:00Z"

curl -sS "${BASE}/api/v1beta/sdm/entities/${ENTITY_ID}/at?atTime=${AT_TIME}" \
  -H "${AUTH_HEADER}" | jq .

Search Entity Snapshots at Source Time

curl -sS -X POST "${BASE}/api/v1beta/sdm/entities/history/search-at" \
  -H "${AUTH_HEADER}" \
  -H "Content-Type: application/json" \
  -d '{
    "atTime": "2026-08-10T00:30:00Z",
    "query": {
      "statuses": ["ENTITY_STATUS_ACTIVE"],
      "domains": ["ENTITY_DOMAIN_AIR", "ENTITY_DOMAIN_GROUND"]
    },
    "pageSize": 100
  }' | jq .

Related Documentation