Skip to content

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 buildProfileStart with
Firmware or an agent on a deviceOBSP-NODEprotobuf obsp.v1, field topics, node-manifest, sensor-passport, time-quality, observation-record
A site controllerOBSP-SITEnode contracts plus provider-manifest, plan, correction-notice, proof-receipt
A grid or cluster control planeOBSP-GRIDsite contracts plus fleet-projection, product-manifest, the gateway API
A supplied product or serviceOBSP-PROVIDERprovider-manifest, supply-chain-receipt, decommission-record
An applicationOBSP-CONSUMERproduct-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)

PlaneBinding (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
EventsEventEnvelope ↔ CloudEvents 1.0; channels described in AsyncAPI 3
ExchangeOpenAPI 3.1; OGC API family; SensorThings; STAC; WIS 2.0
EvidenceDSSE-signed in-toto statements; SLSA provenance; SCITT transparency receipts
TelemetryOpenTelemetry 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
TierRole (§3)Profile (§7)
Node: sensor host, logger, gateway, radio, edge computerNODEOBSP-NODE
Site cell: local authority, buffer and plan for a siteSITE_CELLOBSP-SITE
Cluster and grid: fleet, policy, release, federation, exchangeCLUSTER, FED_PEER, GRID_OPERATOROBSP-GRID
Provider: devices, software, models, data, connectivity, servicesPROVIDEROBSP-PROVIDER
Consumer: applications reading productsCONSUMEROBSP-CONSUMER
Verifier: appraises evidence and challengesVERIFIERpart of OBSP-SITE

Planes

The planes are separate (P7). The exchange plane never opens an inbound management path into a site.

PlaneCarriesBinding (§6)
ControlIdentity, plans, reconciliationTLS 1.3 mutual auth; protobuf obsp.v1 over gRPC or HTTP/2
DataObservations, replay batchesMQTT 5 and Sparkplug B in the field; at-least-once with idempotency upstream
EvidenceAttestation, supply-chain and proof receiptsDSSE-signed in-toto; SLSA; SCITT
ExchangeProducts and events to consumersOpenAPI 3.1, OGC API, SensorThings, STAC, CloudEvents
GatewayParticipant registration and conformance claimsOpenAPI 3.1 (schemas/openapi/)

How a value travels

  1. A node that has joined (§5.1) and been described (§5.3) measures a value. The value carries time-quality.
  2. The node publishes an observation-record on a field topic. If the link is down it buffers and replays the record later (§5.5).
  3. The site cell qualifies the value with quality flags, calibration and provenance (§5.6).
  4. The grid exchanges the qualified value as a product (§5.10). A consumer such as GRIx reads it.
  5. 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).
  6. 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 holdRequirement
KeysSite cell and grid keys, in your HSM or TPM where available
IdentityYour identity provider; no external identity is required
UpdatesYour own update mirror; signed plans only
TelemetryYour own collector; nothing phones home
DataIn your jurisdiction; sharing is a federation choice
NamesYour name pack; the protocol imposes no organisation name

Procure

Ask suppliers for conformance claims (see policies/conformance-claims.md):

  1. Profile and level, for the exact version you buy.
  2. The conformance report and the digests of the tested artifacts.
  3. A run of the suite on that evidence, by you, giving the same result (CNF-3).
  4. 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)

EnvironmentConnectivityKey custodyIdentity
ENV-AIRGAPAir-gapped on-premises or classified enclave
none
operator HSM (PKCS#11) or TPM-sealed keysoperator PKI and OIDC inside the enclave
ENV-ONPREMConnected on-premises data centre
operator-controlled egress
operator HSM or Vault-class KMSoperator OIDC, SAML through an operator broker, X.509 or PIV smart cards
ENV-SOVEREIGN-CLOUDNational or sovereign cloud
in-jurisdiction
customer-held keys in the cloud's KMS or an external HSMoperator OIDC
ENV-HYPERSCALERPublic hyperscaler cloud, including its sovereign or government regions
cloud region chosen by the operator
customer-managed or external keysoperator OIDC or the cloud identity service through an adapter
ENV-HYBRIDHybrid and multi-cloud, including federation across operators
mixed
per trust domainper trust domain, federated by FederationBinding
ENV-TELCO-EDGETelecom edge and MEC
operator network
operator HSM or TPMoperator PKI
ENV-FIELDField site or single node, often disconnected
intermittent or none
TPM, DICE or secure element on the devicesite cell PKI
ENV-DEPLOYABLEMobile or deployable kit (incident, humanitarian, mission)
satellite or none
TPM or secure elementkit-local PKI with later federation

References

Sources cited on this page, in order of first citation. Addresses were last checked on the date shown.

  1. Observatory Protocol, Implementers guide: docs/guides/implementers.md Observatory Protocol 0.1 (draft), CC BY 4.0.
  2. OBSP 0.1 §6: Wire bindings Observatory Protocol 0.1 (draft), CC BY 4.0.
  3. Observatory Protocol, Architecture: docs/architecture.md Observatory Protocol 0.1 (draft), CC BY 4.0.
  4. Observatory Protocol, Operators guide: docs/guides/operators.md Observatory Protocol 0.1 (draft), CC BY 4.0.
  5. OBSP 0.1 §13: Sovereign deployment for every operator and environment Observatory Protocol 0.1 (draft), CC BY 4.0.