Appendix B: Discovery Profile
The Discovery profile defines the lightweight announce messages and manifests that allow services, coverage areas, and spatial content or experiences to be discovered at runtime. It enables SpatialDDS deployments to remain decentralized while still providing structured service discovery.
See Appendix F.X (Discovery Query Expression) for the normative grammar used by CoverageQuery.expr filters.
// SPDX-License-Identifier: MIT
// SpatialDDS Discovery 1.4
// Lightweight announces for services, coverage, and content
#ifndef SPATIAL_CORE_INCLUDED
#define SPATIAL_CORE_INCLUDED
#include "core.idl"
#endif
module spatial {
module disco {
// -----------------------------
// Asset references (middle-ground model)
// -----------------------------
//
// Base contract: uniform access + integrity for all assets.
// Optional, namespaced metadata bags carry type-specific details
// without inflating the base schema.
//
// Example: media_type could be
// "application/vnd.sdds.features+json;algo=orb;v=1"
//
// Namespaced metadata uses JSON strings so producers can include
// structured details without schema churn.
//
@extensibility(APPENDABLE) struct AssetMetaKV {
string namespace; // e.g., "sensing.vision.features"
string json; // JSON object string; producer-defined for this namespace
};
@extensibility(APPENDABLE) struct AssetRef {
string uri; // required: how to fetch
string media_type; // required: IANA or registry-friendly type (with params)
string hash; // required: e.g., "sha256:<hex>"
uint64 bytes; // required: size in bytes
sequence<AssetMetaKV, 32> meta; // optional: zero or more namespaced bags
};
const string MODULE_ID = "spatial.discovery/1.4";
typedef spatial::core::Time Time;
typedef spatial::core::Aabb3 Aabb3;
typedef spatial::core::FrameRef FrameRef;
// Canonical manifest references use the spatialdds:// URI scheme.
typedef string SpatialUri;
// --- Profile version advertisement (additive) ---
// Semver per profile: name@MAJOR.MINOR
// Each row declares a contiguous range of MINORs within a single MAJOR.
@extensibility(APPENDABLE) struct ProfileSupport {
string name; // e.g., "core", "discovery", "sensing.common", "sensing.rad"
uint32 major; // compatible major (e.g., 1)
uint32 min_minor; // lowest supported minor within 'major' (e.g., 0)
uint32 max_minor; // highest supported minor within 'major' (e.g., 2) // supports 1.0..1.2
boolean preferred; // optional tie-breaker hint (usually false)
};
// --- Optional feature flags (namespaced strings, e.g., "blob.crc32", "rad.tensor.zstd") ---
@extensibility(APPENDABLE) struct FeatureFlag {
string name;
};
// --- Capabilities advertised in-band on the discovery bus ---
@extensibility(APPENDABLE) struct Capabilities {
sequence<ProfileSupport, 64> supported_profiles;
sequence<string, 32> preferred_profiles; // e.g., ["discovery@1.2","core@1.*"]
sequence<FeatureFlag, 64> features; // optional feature flags
};
// --- Topic metadata to enable selection without parsing payloads ---
@extensibility(APPENDABLE) struct TopicMeta {
string name; // e.g., "spatialdds/perception/cam_front/video_frame/v1"
string type; // registered type (see Topic Identity & QoS ยง2.2.1)
string version; // e.g., "v1"
string qos_profile; // e.g., "VIDEO_LIVE"
// optional advisory hints (topic-level, not per-message)
float target_rate_hz;
uint32 max_chunk_bytes;
};
enum ServiceKind {
@value(0) VPS,
@value(1) MAPPING,
@value(2) RELOCAL,
@value(3) SEMANTICS,
@value(4) STORAGE,
@value(5) CONTENT,
@value(6) ANCHOR_REGISTRY,
@value(255) OTHER
};
@extensibility(APPENDABLE) struct KV {
string key;
string value;
};
// CoverageElement geometry is always expressed in the parent coverage_frame_ref.
// If that frame is earth-fixed, bbox is [west,south,east,north] in degrees (EPSG:4326/4979);
// otherwise coordinates are in local meters.
@extensibility(APPENDABLE) struct CoverageElement {
string type; // "bbox" | "volume"
boolean has_crs;
string crs; // optional CRS identifier for earth-fixed frames (e.g., EPSG code)
// Presence flags indicate which geometry payloads are provided.
// When has_bbox == true, bbox is authoritative.
boolean has_bbox;
spatial::common::BBox2D bbox; // [west, south, east, north]
// When has_aabb == true, aabb is authoritative.
boolean has_aabb;
Aabb3 aabb; // axis-aligned bounds in the declared frame
// Explicit global coverage toggle: when true, bbox/aabb may be ignored by consumers.
boolean global;
};
// Validity window for time-bounded transforms.
@extensibility(APPENDABLE) struct ValidityWindow {
Time start; // inclusive start
uint32 duration_s; // seconds from start
};
// Quaternion follows GeoPose: unit [x,y,z,w]; pose maps FROM 'from' TO 'to'
@extensibility(APPENDABLE) struct Transform {
FrameRef from; // source frame (e.g., "map")
FrameRef to; // target frame (e.g., "earth-fixed")
string stamp; // ISO-8601 timestamp for this transform
// Explicit validity window (presence-flag style).
// When has_valid == true, the transform is valid in
// [valid.start, valid.start + valid.duration_s].
// When has_valid == false, consumers treat the transform as valid at 'stamp'
// (or until superseded, per system policy).
boolean has_valid;
ValidityWindow valid;
spatial::common::Vec3 t_m; // meters in 'from' frame
spatial::common::QuaternionXYZW q_xyzw; // GeoPose order [x,y,z,w]
};
@extensibility(APPENDABLE) struct ServiceAnnounce {
@key string service_id;
string name;
ServiceKind kind;
string version;
string org;
sequence<string,16> rx_topics;
sequence<string,16> tx_topics;
sequence<KV,32> hints;
// New: wire-level capability advertisement for version negotiation.
Capabilities caps; // in-band capabilities (profiles + features)
sequence<TopicMeta,128> topics; // topic list with typed-topic metadata
sequence<CoverageElement,16> coverage;
FrameRef coverage_frame_ref; // canonical frame consumers should use when evaluating coverage
boolean has_coverage_eval_time;
Time coverage_eval_time; // evaluate time-varying transforms at this instant when interpreting coverage_frame_ref
sequence<Transform,8> transforms;
SpatialUri manifest_uri; // MUST be a spatialdds:// URI for this service manifest
string auth_hint;
Time stamp;
uint32 ttl_sec;
};
@extensibility(APPENDABLE) struct CoverageHint {
@key string service_id;
sequence<CoverageElement,16> coverage;
FrameRef coverage_frame_ref;
boolean has_coverage_eval_time;
Time coverage_eval_time; // evaluate transforms at this instant when interpreting coverage_frame_ref
sequence<Transform,8> transforms;
Time stamp;
uint32 ttl_sec;
};
@extensibility(APPENDABLE) struct CoverageQuery {
// Correlates responses to a specific query instance.
@key uint64 query_id;
sequence<CoverageElement,4> coverage; // requested regions of interest
FrameRef coverage_frame_ref;
boolean has_coverage_eval_time;
Time coverage_eval_time; // evaluate transforms at this instant when interpreting coverage_frame_ref
// Optional search expression per Appendix F.X (Discovery Query Expression ABNF).
// Example: "type==\"radar_tensor\" && module_id==\"spatial.sensing.rad/1.4\""
string expr;
// Responders publish CoverageResponse samples to this topic.
string reply_topic;
Time stamp;
uint32 ttl_sec;
};
@extensibility(APPENDABLE) struct ContentAnnounce {
@key string content_id;
string provider_id;
string title;
string summary;
sequence<string,16> tags;
string class_id;
SpatialUri manifest_uri; // MUST be a spatialdds:// URI for this content manifest
sequence<CoverageElement,16> coverage;
FrameRef coverage_frame_ref;
boolean has_coverage_eval_time;
Time coverage_eval_time;
sequence<Transform,8> transforms;
Time available_from;
Time available_until;
Time stamp;
uint32 ttl_sec;
};
@extensibility(APPENDABLE) struct CoverageResponse {
// Mirrors CoverageQuery.query_id for correlation.
uint64 query_id;
// Result page.
sequence<ContentAnnounce,65535> results;
// Empty when no further pages remain.
string next_page_token;
};
}; // module disco
};