---
title: "Implementer and operator guides | Observatory Protocol"
description: "What to build for each profile, the reference tooling, the interoperability bindings and the environments a deployment can run in."
url: https://nexusobservatory.com/development/implementers/
publisher: GCRI Canada
updated: 2026-11-18
---

[Observatory Protocol](https://nexusobservatory.com/)[Open development](https://nexusobservatory.com/development/)Implementer 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

[Propose a change](https://nexusobservatory.com/development/proposals/)

[Read the text](https://nexusobservatory.com/development/text/)

## 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

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 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):

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)

| Environment | Connectivity | Key custody | Identity |
| --- | --- | --- | --- |
| ENV-AIRGAP | Air-gapped on-premises or classified enclave `none` | operator HSM (PKCS#11) or TPM-sealed keys | operator PKI and OIDC inside the enclave |
| ENV-ONPREM | Connected on-premises data centre `operator-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 cloud `in-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 regions `cloud 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 operators `mixed` | per trust domain | per trust domain, federated by FederationBinding |
| ENV-TELCO-EDGE | Telecom edge and MEC `operator network` | operator HSM or TPM | operator PKI |
| ENV-FIELD | Field site or single node, often disconnected `intermittent 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.

1. [Observatory Protocol, Implementers guide:](https://nexusobservatory.com/development/implementers/#doc-docs-guides-implementers) Observatory Protocol 0.1 (draft), CC BY 4.0.
2. [OBSP 0.1 §6: Wire bindings](https://nexusobservatory.com/development/text/#c-6) Observatory Protocol 0.1 (draft), CC BY 4.0.
3. [Observatory Protocol, Architecture:](https://nexusobservatory.com/development/implementers/#doc-docs-architecture) Observatory Protocol 0.1 (draft), CC BY 4.0.
4. [Observatory Protocol, Operators guide:](https://nexusobservatory.com/development/implementers/#doc-docs-guides-operators) Observatory Protocol 0.1 (draft), CC BY 4.0.
5. [OBSP 0.1 §13: Sovereign deployment for every operator and environment](https://nexusobservatory.com/development/text/#c-13) Observatory Protocol 0.1 (draft), CC BY 4.0.

On this page

1. What to build
2. Interoperability bindings
3. Architecture
4. Operators guide
5. Deployment environments
6. References

- [View the source](https://nexusobservatory.com/development/text/)
- [Report a defect](https://nexusobservatory.com/development/take-part/)
- [Propose a change](https://nexusobservatory.com/development/proposals/)
- [Changes](https://nexusobservatory.com/governance/changes/)
