Skip to content

Observatory ProtocolOpen developmentSpecification text

Observatory Protocol 0.1, the text

The normative text of OBSP 0.1, clause by clause, as published in the protocol repository. Every clause has a permanent address on this page.

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

Draft. OBSP-SPEC-0.1, protocol version obsp/0.1, read from the protocol repository at commit 7cc9c697342c. The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT and MAY are used as in RFC 2119 and RFC 8174 when they appear in capitals. (IETF RFC 2119; IETF RFC 8174)

Purpose and scope

The Observatory Protocol lets an instrument or computer that has never met the grid join it, prove what it is, keep time, publish what it measures with its metadata and quality, and be orchestrated, corrected, federated and finally retired, without trusting any single vendor, cloud or central service.

In scope: the participant roles, objects, identifiers, state machines, messages and wire bindings for the twelve functions in §5, the conformance profiles in §7 and the security model in §8.

Out of scope (non-goals):

  • It is not a public authority. Warnings, emergency dispatch, regulation, spectrum assignment, insurance, certification and law enforcement stay with competent external bodies. A protocol receipt creates no legal, regulatory or financial authority.
  • It defines no token, coin or tradable unit. Participation credits, where a product offers them, are product terms outside this specification.
  • It does not define products, prices or sellers. Those belong to implementations.

Principles (normative)

#PrincipleRequirement
P1Zero implicit trustA participant starts untrusted. Trust is earned by attestation, admission and evidence, and lapses on expiry or revocation
P2One owner per factEach fact family has exactly one authoritative owner. A site MAY cache and continue bounded state; it MUST NOT become a silent second source of truth
P3Local first, offline is not policy-freeApproved local operation MUST continue through loss of upstream links for the autonomy window in the plan. Expired authority, revoked identity, compromised time or missing mandatory evidence MUST force quarantine even offline
P4Typed, receipted commandsEvery consequential command carries identity, purpose, policy, authority, idempotency key and a receipt
P5Products keep their contextEvery value carries provenance, time, uncertainty, quality, epistemic state and correction state
P6Replaceable providersHardware, software, cloud, radio, satellite, model, data and service providers are replaceable behind typed contracts, with a tested exit path
P7Separated planesControl, data, evidence and exchange planes are separate. The exchange plane MUST NOT create an inbound management path into a site
P8Each step is its own evidenceInstallation is not qualification; qualification is not observation; observation is not assessment. No state is reached by wording
P9Correction without erasureRecords are correction-addressable. Supersession never deletes history
P10Scoped proofA proof proves only the claim and scope in its evidence
P11No dependency on another partyA conforming deployment MUST be operable by its owner without any service, data or approval from another organisation, unless the owner chooses to federate

P11 means that every party implements and operates the protocol on its own; joining another party's grid is a choice (§5.7), never a dependency.

Participant roles

Roles are protocol roles, never organisation names.

RoleIdDescription
NodeNODEA device running a conforming node agent: sensor host, edge computer, gateway, radio unit, tower
Site Cell ControllerSITE_CELLLocal authority for a site: identity, policy, plan and buffer for its nodes; runs offline
ClusterCLUSTEROptional group of site cells under one operator, sharing fleet, policy and release
Federation PeerFED_PEERA cluster or site cell that exchanges with another trust domain under a federation binding
Grid OperatorGRID_OPERATORThe organisation that runs a site cell, cluster or grid and holds its keys
ProviderPROVIDERHardware, software, model, data, connectivity or service supplier entering by manifest
VerifierVERIFIERAppraises attestation evidence and proof challenges; issues receipts
ConsumerCONSUMERAn application or person reading products through the exchange plane
StewardSTEWARDMaintains this specification and its registries (§10)

Objects, identifiers and envelopes

4.1 Identifiers

KindRuleSource
UNI (durable identifier)^[A-Za-z0-9][A-Za-z0-9:._/@-]{7,255}$, scheme uni:<kind>:<local> (for example uni:site:site001)request-context.schema.json $defs.Uni
Digest<alg>:<hex>, pattern ^[a-z0-9][a-z0-9._-]{1,31}:[A-Fa-f0-9]{32,128}$; sha256 REQUIRED, sha384/sha512 MAYrequest-context.schema.json $defs.Digest; plan.schema.json
Event type^observatory\.[a-z0-9]+(\.[a-z0-9]+){1,6}$event-envelope.schema.json
Error code^OBS-[A-Z0-9]+-[0-9]{4}$; errors as RFC 9457 problem detailserror-problem.schema.json
Device class^ndc\.[a-z0-9-]+\.[a-z0-9-]+$sensor-passport.schema.json deviceClass
Secret referencesecret://...; secrets never appear inlinethis specification

4.2 Core objects

ObjectSchema (schemas/json/)Function
NodeManifestnode-manifestJoin, Describe
NodeBootstrapBundlenode-bootstrap-bundleJoin
AttestationEvidence, AttestationResultattestation-evidence, attestation-resultJoin
ProviderManifestprovider-manifestAdmit, Exit
SupplyChainReceipt (SBOM, SLSA provenance, SCITT receipt)supply-chain-receiptAdmit
QualificationRecordqualification-recordAdmit, Qualify
SourceManifest, SourceReleasesource-manifest, source-releaseDescribe, Admit
SensorPassport, CalibrationRecordsensor-passport, calibration-recordDescribe
TimeQualitytime-quality (also time fields on observed-state-receipt, event-envelope)Time
ObservationRecordobservation-recordObserve, Qualify
QualityFlag, Provenancequality-flag, provenanceQualify
NativeEnvelope, EventEnvelopenative-envelope, event-envelopeObserve, Exchange
ReplayBatch, ReplayBatchResultreplay-batch, replay-batch-resultObserve
SystemPack, Plansystem-pack, planOrchestrate
ReconciliationAssignment, ReconciliationReceipt, ObservedStateReceiptsame namesOrchestrate
FleetProjectionfleet-projectionFederate
FederationBinding, AuthorityLeasegap G-FED-1Federate
CorrectionNoticecorrection-noticeCorrect
ProductManifestproduct-manifestExchange
ProofReceiptproof-receiptProve
DecommissionRecorddecommission-recordExit
RequestContextrequest-contextAll

4.3 Request context

Every request, command and event MUST carry a RequestContext (request-context.schema.json): actor, purpose, tenant scope, policy reference, idempotency key, correlation id, and the authority under which it acts. A receiver MUST reject a consequential command without it (OBS-CTX-0001).

The twelve functions

Each function states its requirements, the objects and state machine it uses and the evidence it produces. Open gaps are listed in §9.

5.1 Join

A node proves what it is, receives an identity and a policy, then a signed plan.

  • States: UNENROLLED → DISCOVERED → ATTESTING → IDENTITY_ISSUED → POLICY_BOUND → PLAN_STAGED → LOCAL_READY, with DEGRADED, QUARANTINED and terminal REVOKED. Transitions not in the table MUST be refused and recorded.
  • A node MUST present attestation evidence (RATS, RFC 9334, passport model) rooted in a hardware root of trust where the device class has one (TPM 2.0, DICE or a secure element), or a software root explicitly marked SOFTWARE_ROOT otherwise. A verifier MUST bind the result to a nonce and an expiry.
  • Identity MUST be short-lived and renewable (X.509 SVID, SPIFFE-style URI spiffe://<trust-domain>/node/<uni>). Long-lived shared secrets MUST NOT be used.
  • The bootstrap bundle MUST be signed by the site cell's enrolment key and carry the trust anchors, policy reference and the first plan digest.
  • Evidence: enrolment receipt, attestation result, identity issuance record.

5.2 Admit

Providers enter by manifest, rights, security and technical review, for a stated scope.

  • States: DISCOVERED → MANIFEST_VALID → RIGHTS_REVIEWED → SECURITY_REVIEWED → TECHNICALLY_QUALIFIED → JURISDICTION_QUALIFIED → ADMITTED_FOR_SCOPE, with SUSPENDED, REVOKED, RETIRED. No state is a sovereignty, certification or endorsement claim.
  • Admission is scoped to the tuple (provider, artifact digest or version, capability or profile, jurisdiction, purpose, qualification revision). Presence, connectivity or a commercial relationship MUST NOT imply admission.
  • Every admitted software artifact MUST carry an SBOM (SPDX or CycloneDX) and SLSA provenance. A transparency receipt (SCITT) SHOULD be recorded.

5.3 Describe

Every instrument and observation carries what, where, how and by whom.

  • A sensor MUST have a SensorPassport: device class, make and model (provider name gated), serial, firmware digest, mounting and exposure, sampling plan, units (UCUM), and calibration history.
  • Metadata MUST map to OGC SensorML 3.0 and the SOSA/SSN ontology; weather and climate instruments SHOULD also map to WMO WIGOS metadata.
  • Every observation MUST reference its sensor passport version, so a later recalibration is traceable.

5.4 Time

One time base across the grid, with time quality as explicit state.

  • A node MUST report a TimeQuality with every observation: source class (AUTHENTICATED_PNT, PTP, NTS, GNSS_ONLY, SYSTEM_CLOCK, UNKNOWN), estimated offset bound, holdover age and integrity flags.
  • Network time MUST be authenticated (NTS, RFC 8915) or come from a site grandmaster (IEEE 1588 PTP, telecom profile ITU-T G.8275.1 where radios need it). GNSS alone MUST NOT be treated as trusted time; spoofing and jamming indicators MUST lower the quality.
  • A node whose time integrity is compromised MUST stop signing receipts that depend on time and enter DEGRADED.

5.5 Observe

Streams and files move over whatever link the site has, with store and forward.

  • Field-side transport: MQTT 5 with Sparkplug B for device telemetry; a node MAY also speak LoRaWAN, OPC UA or vendor buses through a connector.
  • Site to upstream: observations are written to a local durable outbox first and published at-least-once with an idempotency key. Duplicates MUST be absorbed by the receiver.
  • Replay outcomes: ACCEPTED, IDEMPOTENT_REPLAY, STALE_HISTORICAL, GAP_RECORDED, CONFLICT, REJECTED, FAILED_RETRYABLE, FAILED_TERMINAL. A gap MUST be recorded, never filled silently.
  • Events use the EventEnvelope and MUST map one-to-one to CloudEvents 1.0 attributes.

5.6 Qualify

Quality flags, calibration and provenance travel with each value.

  • Quality flags MUST come from a controlled vocabulary (WMO-style: GOOD, SUSPECT, BAD, MISSING, ESTIMATED, NOT_CHECKED, plus test codes) with the test that set them.
  • Provenance MUST be expressible as W3C PROV-O (entity, activity, agent) and travel with derived products.
  • Uncertainty MUST be stated where the instrument class defines one. A missing value is a typed state, never zero.

5.7 Federate

Nodes form cells, cells form clusters, and clusters federate across trust domains.

  • Federation is asynchronous exchange under an explicit FederationBinding: the two trust domains, the scopes and data classes shared, the direction, retention, the authority lease (who may command what, until when) and the exit terms. No binding, no exchange.
  • A federation peer MUST NOT gain command authority over another domain's nodes unless an unexpired authority lease grants it for a named scope.
  • Federation MUST survive partition: each domain stays authoritative for its own facts (P2).

5.8 Orchestrate

Software, configuration and upgrades roll out by signed plan, with evidence for every change.

  • A SystemPack (released, signed) is compiled deterministically into a per-site Plan; the same inputs MUST give the same plan digest.
  • A plan MUST be signed before a node applies it. Update metadata MUST follow TUF roles (root, targets, snapshot, timestamp) so a compromised mirror cannot roll back or freeze a node; device firmware SHOULD use IETF SUIT manifests.
  • The node agent applies the smallest reversible step, records an ObservedStateReceipt, and rolls back on failure.

5.9 Correct

An upstream correction marks dependants stale, triggers recompute and publishes a new version.

  • Correction states: CURRENT → DISPUTED → SUPERSEDED | WITHDRAWN | RECALLED; DISPUTED → CURRENT on resolution. SUPERSEDED, WITHDRAWN and RECALLED are terminal for that version.
  • A CorrectionNotice MUST name the corrected record and version, the reason, the issuer and the dependants it invalidates. Consumers subscribed to a product MUST receive the notice.

5.10 Exchange

Governed products reach people and applications through versioned APIs, events, maps and exports.

  • Read APIs follow OpenAPI 3.1. Geospatial products SHOULD be served through OGC API (Features, Tiles, EDR), SensorThings API for observations, OGC API Connected Systems for systems, and STAC for archives. WMO WIS 2.0 publication is a product option.
  • Every product has a ProductManifest with licence, the most restrictive upstream term, quality and correction state.
  • The exchange plane is read-only toward sites (P7).

5.11 Prove

Peers answer unpredictable challenges and emit signed proof receipts for an independent verifier.

  • Proofs cover coverage, uptime, data delivery, location and time. A challenge MUST be unpredictable to the prover; a receipt MUST be signed and bound to the challenge, the evidence digests and the scope.
  • Location proofs SHOULD combine at least two independent sources (GNSS with RTK, radio ranging, witness nodes).

5.12 Exit and decommission

Every material provider has an open export and replacement path, and decommissioning closes the record.

  • Every ProviderManifest MUST declare an exit path (export format, replacement procedure), exercised as a test before admission for scope.
  • Decommissioning MUST revoke identities, wipe or return keys, export the owner's data in open formats, and issue a DecommissionRecord with final evidence.

Wire bindings

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

Conformance

7.1 Profiles

ProfileFunctionsFor
OBSP-NODEJoin, Describe, Time, Observe, Qualify, Orchestrate (apply), ExitNode agents and devices
OBSP-SITEOBSP-NODE plus Admit (local), Orchestrate (plan), Correct, Prove (verifier)Site cell controllers
OBSP-GRIDOBSP-SITE plus Federate and ExchangeCluster and grid control planes
OBSP-PROVIDERAdmit, Describe, ExitHardware, software, model and data providers
OBSP-CONSUMERExchange, Correct (subscribe)Applications reading products

The machine-readable form is registers/conformance-profiles.yaml.

7.2 Conformance levels

DECLARED → SELF_TESTED → LAB_TESTED → QUALIFIED, with SUSPENDED and WITHDRAWN. A level is reached only with the evidence named in the profile, produced by the open conformance suite (conformance/, run with obsp conformance run) or a qualified lab. "Conformant" describes a tested scope only; it is never written as certification.

Security model

AreaRequirement
ArchitectureZero trust (NIST SP 800-207): every request is authenticated, authorised and logged; network position grants nothing
Device identityAttested; hardware root where the class has one; short-lived certificates; revocation within the site cell's offline window
Workload identitySPIFFE-style SVIDs, rotated; no shared secrets
KeysSite cell keys held by the grid operator; customer-held keys for upstream services; HSM or TPM-sealed where available
Supply chainSBOM, SLSA provenance, signed artifacts, TUF update metadata, SUIT for firmware
TimeAuthenticated time (P3, §5.4); time integrity gates receipts
OT environmentsIEC 62443 zones and conduits for industrial deployments
PrivacyObservation data that can identify a person is a declared data class with its own policy; default is not to collect it
Break glassLogged, time-bound, receipted

Threats the conformance suite MUST test: rogue node, cloned identity, replayed plan, rolled-back update, spoofed GNSS time, location fraud, poisoned observation, compromised provider control plane, partitioned federation.

Gaps register

Open gaps in the specification and its contracts:

GapWhat is missing
G-FED-1FederationBinding, AuthorityLease, peer protocol
G-ORCH-1Plan signing, TUF
G-EXCH-1Read APIs, OGC endpoints
G-PROVE-1Proof verifier

The machine-readable function and gap list is registers/functions.yaml. A gap is closed by an OIP that adds the contract and its fixtures.

Versioning and change

  • Protocol versions are obsp/<major>.<minor>. Until 1.0, a minor version MAY break; from 1.0, only a major version breaks. Wire contracts carry schemaVersion 3.1.0 for OBSP 0.1; a breaking contract change needs an OIP and a new schemaVersion.
  • Changes are proposed as Observatory Improvement Proposals (OIPs): DRAFT → REVIEW → ACCEPTED → IMPLEMENTED, or WITHDRAWN. An OIP that changes a function MUST update this file, registers/functions.yaml, the affected schemas and the conformance tests in the same change.
  • Stewardship, licences and the contribution terms are recorded in GOVERNANCE.md.

Implementations

Implementations are listed in IMPLEMENTATIONS.md with the profile, version and conformance level each one claims and the evidence for it. Listing is not endorsement; a claim above DECLARED needs the evidence of §7.2.

Operator sovereignty profile (`OBSP-SOV`)

A deployment operated by any organisation other than the publisher of the software runs with no involvement of the publisher, direct or indirect. The operator holds the data, the keys and the stewardship. OBSP-SOV is an overlay: it applies on top of whichever profile of §7 a deployment conforms to, whenever the operator is not the publisher.

IdRequirement
SOV-1No outbound connection to any endpoint the operator has not configured. The default configuration has none: no update check, licence check, crash report or usage report to the publisher
SOV-2No publisher account, credential, key, certificate or trust anchor ships in a build. The operator generates every root (site cell enrolment, plan signing, TUF root, identity issuer) at install
SOV-3Installation and upgrade work from signed releases verifiable offline (TUF metadata and signature bundles), from a mirror the operator controls, including air-gapped
SOV-4Telemetry, logs and traces go only to collectors the operator configures; off by default
SOV-5Open components contain no licence enforcement, entitlement check, metering to a third party or billing hook. Commercial features live in separate components that no open component requires, so nothing in an open build can charge the operator
SOV-6Brand-neutral: product names, logos, domains, legal text and help links come from a name pack the operator loads. no company name, trademark or domain is compiled into an open component
SOV-7Cloud-neutral: identity, key management, storage and messaging are reached through adapters with an open-source default; no hyperscaler endpoint is hard-coded
SOV-8Every function is operable by the operator's own staff from public documentation; the operator can export all data in open formats at any time
SOV-9The publisher has no remote access path. Support happens through public channels (releases, documentation, issue trackers); an operator MAY grant access under its own contract and controls, never by default
SOV-10Builds are reproducible, so an operator can rebuild every open component from source and compare digests

An implementation SHOULD enforce SOV-5, SOV-6 and SOV-7 in its own continuous integration by scanning its open components for publisher names and domains, licence, metering or billing code, and hard-coded provider endpoints outside adapters, with baselines that may only go down.

Name packs (SOV-6). The contract is name-pack.schema.json: product and surface names (console, studio, developer portal, node agent, site cell, protocol display name), a system code map, the operator's organisation, logos (local paths with digests; a remote location only when the operator opts in), help, docs, legal, privacy and support links (https or relative, each may be empty), a legal notice and a locale set (BCP 47 tags with a right-to-left flag). kind is the operator class: NEUTRAL (the default), NON_PROFIT_STANDARDISED, GOVERNMENT, INTERGOVERNMENTAL, ENTERPRISE, OEM_WHITE_LABEL or COMPANY. a NEUTRAL pack carries nothing organisation-specific. A publisher screens its own names and trademarks out of non-company packs with its release tooling. Implementations load the pack the operator names and MUST refuse an invalid one.

One sentence of this clause, on the names used by one programme's operators, is held back from this site until a decision on how the site presents it. It remains in the source.

Sovereign deployment for every operator and environment

OBSP-SOV (§12) applies to every operator that is not the publisher: national and subnational governments, intergovernmental bodies and UN agencies, national parties, non-profits, enterprises, OEMs embedding the node agent, research networks and communities. Each of them MUST be able to run every function in the environments it chooses, with its own keys, identity, update mirror, telemetry and data residency, and with no service of the publisher.

EnvironmentKey custodyIdentityUpdates
Air-gapped on-premises or enclaveOperator HSM (PKCS#11) or TPMOperator PKI and OIDC inside the enclaveSigned releases imported by media into an operator TUF mirror
Connected on-premisesOperator HSM or KMSOperator OIDC, SAML through a broker, X.509, PIVOperator TUF mirror
National or sovereign cloudCustomer-held keysOperator OIDCMirror inside the jurisdiction
Hyperscaler, including government regionsCustomer-managed or external keysOperator OIDC or the cloud identity service through an adapterOperator mirror
Hybrid and multi-cloudPer trust domainPer trust domain, federated by FederationBindingPer trust domain
Telecom edge and MECOperator HSM or TPMOperator PKIOperator mirror
Field site or single nodeTPM, DICE or secure elementSite cell PKISigned plans staged locally
Deployable kitTPM or secure elementKit PKI, federated laterSigned plans staged before deployment

Requirements:

  • Every cloud-specific capability is an adapter selected by explicit configuration. The default profile none uses open components only and makes no outbound call; it is the air-gapped and on-premises path. An adapter that is not implemented MUST fail closed when selected.
  • Cryptography MUST be agile: algorithms are configuration, an operator MAY select a validated-module mode, and a hybrid post-quantum mode is on the roadmap.
  • Packages MUST run on Kubernetes, lightweight edge Kubernetes and plain Linux services, on x86_64 and arm64.
  • Data and events MUST be exchangeable through open standards (OGC API, SensorThings, STAC, WMO WIS 2.0, CloudEvents, MQTT 5, Sparkplug B), so any operator's existing systems can join.
  • Assurance frameworks (ISO/IEC 27001, IEC 62443, NIST SP 800-53 and 800-207, national public-sector baselines) are design references, never compliance claims.

The machine form of the operator classes, environments and compatibility targets is registers/deployment-environments.yaml. Each implementation records its own status per environment and target.

References

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

  1. IETF RFC 2119 Key words for use in RFCs to Indicate Requirement Levels www.rfc-editor.org/rfc/rfc2119.html Checked
  2. IETF RFC 8174 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words www.rfc-editor.org/rfc/rfc8174.html Checked