schemas: DeviceService contract v0.1 — the southbound device plane (W8.7)

[mdheller]

The gap

The estate has no southbound device abstraction anywhere. The health twin ingests batch corpora; the smart home has nothing; a Δt<50ms twin sync is aspirational for the simple reason that no sensor stream exists to be late.

EdgeX Foundry's lesson is the fix, and it is a lesson about shape, not about adopting EdgeX: ONE southbound interface, N protocol drivers. A driver speaks a protocol; it does not invent a vocabulary. The moment each driver defines its own event shape, every consumer downstream grows a per-driver special case and the "device plane" is a directory of adapters rather than a plane.

Two types

Schema	What it is	URN
DeviceProfile	What a device is: protocol, typed protocol binding, and the exact metric set it produces with units, value types, operating ranges and protocol-native source addresses.	urn:srcos:device-profile:
DeviceReading	One observation: metric, value, unit, quality, observedAt — on the MPCC ConversationEvent envelope, byte-identical, parity machine-enforced.	urn:srcos:device-reading:

The normative invariant: a reading is attributable or it is nothing

An unattributable reading is the silent-wrong we keep paying for.

deviceRef, deviceProfileRef, profileDigest, metric, sourceAddress and unit are all required — there is no optional path to an anonymous value. tools/validate_device_service_examples.py resolves every one across the example set: the profile exists, the digest matches the recomputed declaration, the metric is declared, the unit and source address agree with it, the value is of the declared type and inside the declared range, and provenanceLinks independently name both the device and the profile — so the attribution survives being read by something that is not this validator.

Digest-pinning: a range cannot be widened after the fact

A reading fails the declared range, so somebody widens the range. DeviceProfile.definitionDigest (sha256 over the {deviceClass, protocol, metrics} projection as written) closes that: widening produces a new digest and orphans the readings it was meant to legalise instead of silently admitting them. Same construct as UpdateHealthProbe (W9.2), applied to metrology — and recomputed, never read back. A digest that is merely stored is an assertion about pinning; a digest that is recomputed is pinning.

Quality is closed, absence is typed, simulation is visible

• Five values: ok / degraded / stale / substituted / unavailable. Normatively stale and substituted are not ok, and substituted is not measured — conflating them is how a smart-home twin comes to believe a default is a measurement, and then how a health twin does.
• unavailable is schema-bound (if/then/else) to a null value plus a NullAbsenceRecord ref. The device plane reuses the existing 12-kind MPCC absence taxonomy rather than inventing a device-local one.
• protocol: "virtual" is a first-class labelled member of the taxonomy; the validator enforces synthetic:simulated-device in both directions. This is the KnowledgeNuggetmodel-generated rule applied to sensors: generated data that is indistinguishable downstream is worse than no data, because it is believed.

Read-only at v0.1

access is closed to "read". Commanding a device is a world-changing effect and must travel EffectRequest → EffectDecision. Admitting actuation through a widened enum would hand every protocol driver unreviewed physical authority over a citizen's home.

Overlap decided, not ignored

Existing	Decision
DeviceIdentity	Governs admission/attestation/trust for a SourceOS operator workstation; says nothing about metrology. DeviceProfile.identityRef binds to it. A negative vector forbids attributing a reading to a urn:srcos:device-identity: URN.
TelemetryEvent	An AgentSession diagnostic log event — no unit, range, quality or device. Untouched.
NullAbsenceRecord	Reused verbatim. No device-local absence vocabulary exists.
ConversationEvent	The envelope authority.
Fog plane (Topic/Offer/WorkOrder/…)	No overlap despite the shared word — that is the FogCompute marketplace; this is sensor fog.

Verification

make validate exit 0 (whole repo, incl. the new target)
make validate-device-service-examples exit 0 ok: true
scripts/check_duplicate_schema_ids.py exit 0 316 unique $id
ajv compile (CI step) both schemas ok
CI example loop 215 passed, 82 skipped, 0 failed

• 21 negative vectors in fixtures/device-service/conformance.json — every one derived from a complete canonical example and broken in exactly one way, so a failure is attributable to the named defect. Verified all 21 fail, none passes.
• The validator was mutation-tested: 8 deliberate defects (widen a range without re-digesting; unit drift; source-channel drift; a simulated reading losing its labels; a value out of range; an edited envelope description; provenance that no longer names the device; receivedAt before observedAt) each turn it red. A checker that cannot go red is theatre.

Deliberate gaps (§11 of the spec note)

• No Device instance registry. The profile describes a device model; deviceRef names an instance by a urn:srcos:device: URN with no schema of its own yet. Same house convention as ConversationEvent's free-form actorRef/workspaceRef/branchRef. First follow-on.
• No command/actuation path (by design), no discovery/provisioning contract, no aggregate/derived-reading type (emitting one as a DeviceReading would launder a computation into a measurement).
• No OpenAPI/AsyncAPI/semantic-context wiring yet — matching how schemas: MPCC event contract v0.1 — conversation + trading event family #204, schemas: KnowledgeNugget + SemanticAction v0.1 — L2 content grain + typed-action registry #210 and schemas: A/B fallback update contract v0.1 — never ship an update you cannot brick with (W9.2) #212 landed.

Reference implementation: device-service in SocioProphet/prophet-platform (separate PR).