Observatory ProtocolOpen developmentImplementer guides
Implementer and operator guides
What to build for each profile, the reference tooling, the interoperability bindings and the environments a deployment can run in.
- Version
- 0.1.0-draft
- Status
- Draft specification
- Specification
- CC BY 4.0
- Code
- Apache-2.0
- Steward
- GCRI Canada
- Source
- obsp-0.1-foundation
What to build
The profile, the contracts to start with and the reference tooling for each kind of implementation. (Observatory Protocol, Implementers guide)
Pick what you build
| You build | Profile | Start with |
|---|---|---|
| Firmware or an agent on a device | OBSP-NODE | protobuf obsp.v1, field topics, node-manifest, sensor-passport, time-quality, observation-record |
| A site controller | OBSP-SITE | node contracts plus provider-manifest, plan, correction-notice, proof-receipt |
| A grid or cluster control plane | OBSP-GRID | site contracts plus fleet-projection, product-manifest, the gateway API |
| A supplied product or service | OBSP-PROVIDER | provider-manifest, supply-chain-receipt, decommission-record |
| An application | OBSP-CONSUMER | product-manifest, correction-notice, the exchange bindings |
Tooling
python3 -m pip install -e sdk/python # the obsp package and CLI
obsp validate my-document.json --schema observation-record
obsp digest my-document.json # RFC 8785 canonical digest
obsp conformance run --profile OBSP-NODE --evidence ./evidence --out report.json- Contracts: schemas/json/, schemas/asyncapi/, schemas/proto/, schemas/openapi/.
- Test documents: fixtures/positive/ must validate in your implementation, and fixtures/negative/ must be rejected.
- Conformance suite: conformance/.
Rules of thumb
- Treat a missing value as a typed state, never as zero.
- Reject a consequential command that has no request context (
OBS-CTX-0001). - Never put a secret inline. Use
secret://references. - Never depend on a vendor endpoint to join, update or export (P6, P11).
- Read the open gaps (specification §9) before you build federate, orchestrate, exchange or prove.
Interoperability bindings
One binding per plane, normative for OBSP 0.1. (OBSP 0.1 §6)
| Plane | Binding (normative for OBSP 0.1) |
|---|---|
| Control (site cell ↔ node, cluster ↔ site cell) | TLS 1.3 with mutual authentication; protobuf messages in package obsp.v1 over gRPC or HTTP/2; the current node-agent message framing is binding obsp-control/0 and stays supported until 0.2 |
| Data (field) | MQTT 5 with Sparkplug B; connectors for LoRaWAN, OPC UA and vendor buses |
| Data (site → upstream) | At-least-once publication with idempotency keys over the control channel or NATS JetStream; QUIC MAY be used on lossy links |
| Events | EventEnvelope ↔ CloudEvents 1.0; channels described in AsyncAPI 3 |
| Exchange | OpenAPI 3.1; OGC API family; SensorThings; STAC; WIS 2.0 |
| Evidence | DSSE-signed in-toto statements; SLSA provenance; SCITT transparency receipts |
| Telemetry | OpenTelemetry OTLP |
Architecture
Tiers, planes and how a value travels from an instrument to a product. (Observatory Protocol, Architecture)
Tiers
┌──────────── trust domain A ────────────┐ ┌──── trust domain B ────┐
node ─┐ │ │ │ │
node ─┼──► site cell ──► cluster ──► grid control ──┼─ federation binding ─► grid ──► … │
node ─┘ │ (offline-capable) plane │ │ │
└──────────────────┬─────────────────────┘ └────────────────────────┘
│ exchange plane (read-only to the outside)
▼
consumers: applications, GRIx, Nexus Reports, dashboards, exports| Tier | Role (§3) | Profile (§7) |
|---|---|---|
| Node: sensor host, logger, gateway, radio, edge computer | NODE | OBSP-NODE |
| Site cell: local authority, buffer and plan for a site | SITE_CELL | OBSP-SITE |
| Cluster and grid: fleet, policy, release, federation, exchange | CLUSTER, FED_PEER, GRID_OPERATOR | OBSP-GRID |
| Provider: devices, software, models, data, connectivity, services | PROVIDER | OBSP-PROVIDER |
| Consumer: applications reading products | CONSUMER | OBSP-CONSUMER |
| Verifier: appraises evidence and challenges | VERIFIER | part of OBSP-SITE |
Planes
The planes are separate (P7). The exchange plane never opens an inbound management path into a site.
| Plane | Carries | Binding (§6) |
|---|---|---|
| Control | Identity, plans, reconciliation | TLS 1.3 mutual auth; protobuf obsp.v1 over gRPC or HTTP/2 |
| Data | Observations, replay batches | MQTT 5 and Sparkplug B in the field; at-least-once with idempotency upstream |
| Evidence | Attestation, supply-chain and proof receipts | DSSE-signed in-toto; SLSA; SCITT |
| Exchange | Products and events to consumers | OpenAPI 3.1, OGC API, SensorThings, STAC, CloudEvents |
| Gateway | Participant registration and conformance claims | OpenAPI 3.1 (schemas/openapi/) |
How a value travels
- A node that has joined (§5.1) and been described (§5.3) measures a value. The value carries time-quality.
- The node publishes an observation-record on a field topic. If the link is down it buffers and replays the record later (§5.5).
- The site cell qualifies the value with quality flags, calibration and provenance (§5.6).
- The grid exchanges the qualified value as a product (§5.10). A consumer such as GRIx reads it.
- If a calibration turns out to be wrong, a correction-notice marks every dependant stale. The dependants are recomputed and published as new versions (§5.9).
- Anyone with the evidence can check any claim made along the way with a proof-receipt (§5.11).
Sovereign deployment
Every tier runs in any environment of registers/deployment-environments.yaml, from air-gapped to public cloud. In every environment the operator holds:
- its own keys and identity;
- its own update mirror;
- its own telemetry and data.
See specification §12 and §13.
Operators guide
Choosing an environment, keeping sovereignty, procuring and running a deployment. (Observatory Protocol, Operators guide)
Choose an environment
Every function runs in every environment of the deployment matrix (specification §13, registers/deployment-environments.yaml). For each environment the register states the connectivity, key custody, identity, updates and telemetry. Choose by your law and risk, not by a provider's offer.
Keep sovereignty (OBSP-SOV)
| You hold | Requirement |
|---|---|
| Keys | Site cell and grid keys, in your HSM or TPM where available |
| Identity | Your identity provider; no external identity is required |
| Updates | Your own update mirror; signed plans only |
| Telemetry | Your own collector; nothing phones home |
| Data | In your jurisdiction; sharing is a federation choice |
| Names | Your name pack; the protocol imposes no organisation name |
Procure
Ask suppliers for conformance claims (see policies/conformance-claims.md):
- Profile and level, for the exact version you buy.
- The conformance report and the digests of the tested artifacts.
- A run of the suite on that evidence, by you, giving the same result (
CNF-3). - A tested exit path (§5.12): open export, replacement and decommission.
Run
- Admit every provider with a manifest, for a stated scope (§5.2), and revoke when the scope ends.
- Keep the autonomy window of each site's plan realistic. Expired authority forces quarantine even offline (P3).
- Publish corrections as notices. Never edit history (P9).
- Offer evidence to GRIx or Nexus Reports only by your choice.
Deployment environments
Every operator class can run every function in the environments it chooses, with its own keys, identity and updates. (OBSP 0.1 §13)
| Environment | Connectivity | Key custody | Identity |
|---|---|---|---|
| ENV-AIRGAP | Air-gapped on-premises or classified enclavenone | operator HSM (PKCS#11) or TPM-sealed keys | operator PKI and OIDC inside the enclave |
| ENV-ONPREM | Connected on-premises data centreoperator-controlled egress | operator HSM or Vault-class KMS | operator OIDC, SAML through an operator broker, X.509 or PIV smart cards |
| ENV-SOVEREIGN-CLOUD | National or sovereign cloudin-jurisdiction | customer-held keys in the cloud's KMS or an external HSM | operator OIDC |
| ENV-HYPERSCALER | Public hyperscaler cloud, including its sovereign or government regionscloud region chosen by the operator | customer-managed or external keys | operator OIDC or the cloud identity service through an adapter |
| ENV-HYBRID | Hybrid and multi-cloud, including federation across operatorsmixed | per trust domain | per trust domain, federated by FederationBinding |
| ENV-TELCO-EDGE | Telecom edge and MECoperator network | operator HSM or TPM | operator PKI |
| ENV-FIELD | Field site or single node, often disconnectedintermittent or none | TPM, DICE or secure element on the device | site cell PKI |
| ENV-DEPLOYABLE | Mobile or deployable kit (incident, humanitarian, mission)satellite or none | TPM or secure element | kit-local PKI with later federation |
References
Sources cited on this page, in order of first citation. Addresses were last checked on the date shown.
- Observatory Protocol, Implementers guide: docs/guides/implementers.md Observatory Protocol 0.1 (draft), CC BY 4.0.
- OBSP 0.1 §6: Wire bindings Observatory Protocol 0.1 (draft), CC BY 4.0.
- Observatory Protocol, Architecture: docs/architecture.md Observatory Protocol 0.1 (draft), CC BY 4.0.
- Observatory Protocol, Operators guide: docs/guides/operators.md Observatory Protocol 0.1 (draft), CC BY 4.0.
- OBSP 0.1 §13: Sovereign deployment for every operator and environment Observatory Protocol 0.1 (draft), CC BY 4.0.