This document defines the OCI Package Resolution System for Internet of Things (IoT-PRS), an extension of the OCI artifact model that transforms registries into a stateful message bus for IoT operations and management. By employing a canonical encoding approach to represent artifacts in a consistent, immutable format, IoT-PRS enables reliable content resolution, schema discovery, and decentralized state mutation. This specification outlines how IoT devices download system images, subscribe to state changes, and perform logic operations based on declarative state mutations—all through existing OCI distribution mechanisms.
The IoT-PRS specification provides detailed guidance for implementors who wish to build an end-to-end, cloud native IoT management solution using OCI registries as stateful message buses. In this model, every artifact—whether it is a system image, device configuration, or sensor data record—is encoded in a canonical format that maps namespaces to device or application state, tags to keys, and the manifest’s single layer to the current value. This approach supports:
- Stateful Content Resolution: IoT devices use built-in resolver functions to download system images and query for state changes.
- Declarative Device Management: Users declare desired state changes which are communicated through registries to IoT devices.
- Decentralized Messaging and Mutation: Registries act as federated, stateful message buses, allowing devices and users to exchange multi-modal information reliably.
- Namespace: A dedicated OCI domain representing a publisher’s ledger of IoT artifacts (e.g., system images, state records). Each namespace acts as a logical container for device or application state.
- Artifact: An IoT package or asset stored in OCI, encoded in a canonical format. Artifacts include system images, configuration files, and state update records.
- Tag: A label used to denote specific versions or attributes of an artifact. In IoT-PRS, tags serve as keys in a key–value mapping.
- Manifest Layer: The content layer of an OCI artifact that holds the actual package payload, such as a JSON document with device state or configuration data.
- Resolver Function: A client-side function that interprets the encoded artifact format, mapping namespaces and tags to retrieve the manifest layer and assemble a complete state record.
- Schema Discovery: The mechanism by which a client retrieves the authoritative schema for a given namespace, enabling proper interpretation and validation of IoT artifacts.
- Nameserver: A special namespace that functions as an index and state registry; it maps content names to artifacts and provides the associated schema for that domain.
- State Mutation: A declared change in the state of a device or application, recorded and propagated through OCI registries.
IoT-PRS builds on existing OCI registry infrastructure by applying a standardized encoding format that transforms registries into a stateful message bus for IoT operations. The key architectural components are:
- Artifact Encoding: IoT system images, configuration updates, and state changes are published in a canonical, immutable format as single-layer manifests.
- Namespace Ledger: Each OCI namespace serves as a ledger for a specific domain (e.g., a fleet of smart lights). Publishers register their namespace with one or more centralized indexes (similar to app stores) for discovery.
- Key–Value Mapping: Tags are used as keys and the manifest layer as the value, resulting in structured records akin to JSON objects.
- Resolver Functions: IoT devices and management systems use resolver functions to query registries for state changes, download system images, and validate state updates.
- Schema Discovery: Nameservers provide authoritative schemas that describe the structure and semantics of the IoT artifacts in a namespace, ensuring that devices can correctly parse and act on the data.
IoT-PRS defines a meta-component model that standardizes how IoT device state, application assets, and user commands are packaged. The core elements include:
- Object (Namespace): Represents a domain or ledger for IoT artifacts.
- Key (Tag): Denotes metadata fields such as firmware version, configuration parameters, or sensor type.
- Value (Manifest Layer): Contains the actual content—whether it is a system image, a state record, or a configuration update.
- Schema: An extensible metadata model (e.g., based on Schema.org) that describes the expected structure and semantics of the artifacts, allowing for automated validation and processing.
IoT-PRS employs a canonical encoding scheme to represent IoT artifacts in a deterministic and verifiable manner. The encoding consists of two main components:
-
Canonical Header:
- Collect all OCI tags associated with the IoT artifact.
- Normalize the order and format of these tags to ensure a consistent header.
- Assemble a JSON object that includes key metadata fields such as
deviceID,firmwareVersion,configuration, andcontentType. - Generate a digital fingerprint of the header to support integrity checks.
-
Key–Value Mapping:
- In the header, tags act as keys and their associated values (e.g., version numbers, configuration parameters) are organized in a consistent JSON-based structure.
- Manifest Layer as Payload:
- The artifact’s payload is contained within a single manifest layer. This layer stores the IoT data (e.g., system image, sensor reading, configuration update) in a structured format, typically JSON.
- Content Hashing:
- Process the payload with a content-addressable hash function to ensure any change results in a new artifact.
- Normalization:
- Normalize the payload (e.g., standardizing formatting and ordering) so that the same logical content always produces the same hash.
This encoding guarantees that every IoT artifact is immutable and verifiable, simplifying state resolution and integrity checking.
The Resolver API is a client-side interface that adapts the OCI distribution API for IoT operations. It allows devices and management systems to resolve, retrieve, and act on state changes. The API operates locally or remotely and includes the following methods:
-
QueryNamespace(namespace: string) → ArtifactList
- Description: Retrieves a list of IoT artifacts within the specified OCI namespace.
- Details: Calls the OCI distribution API to list all artifacts and returns their identifiers along with metadata.
-
LookupTag(namespace: string, tag: string) → ArtifactID
- Description: Searches within the namespace for an artifact that contains the specified tag (key).
- Details: Performs a key-based lookup in the canonical header to find the matching artifact.
-
RetrieveManifest(artifactID: string) → Manifest
- Description: Downloads the manifest for the given artifact ID.
- Details: Expects the manifest to contain a single layer with the IoT data payload. Validates the payload against the header’s content hash.
-
DownloadSchema(nameserver: string) → SchemaDefinition
- Description: Retrieves the authoritative schema for the domain managed by the nameserver.
- Details: Returns a machine-readable schema (e.g., JSON Schema) describing the structure of the IoT records in that namespace.
The resolver function for IoT devices follows these steps:
-
Namespace Query:
- The device calls
QueryNamespace(namespace)to obtain a list of relevant artifacts (e.g., state updates).
- The device calls
-
Key-Based Lookup:
- For a specific state variable (tag), the device invokes
LookupTag(namespace, tag)to identify the corresponding artifact.
- For a specific state variable (tag), the device invokes
-
Manifest Retrieval and Validation:
- The device uses
RetrieveManifest(artifactID)to download the manifest. It then validates the payload by comparing the computed content hash with that in the header.
- The device uses
-
Schema Discovery and Record Assembly:
- The device calls
DownloadSchema(nameserver)to fetch the authoritative schema. Using this schema, it parses the canonical header and payload to assemble a complete record.
- The device calls
-
State Mutation and Action:
- The resolved record is processed locally to update device state or trigger actions (e.g., change brightness on smart lights, update sensor readings).
-
Local Caching and Optimization:
- The API supports local caching of frequently accessed artifacts and schemas to improve performance and reduce redundant remote calls.
-
Client-Side Integration:
- The Resolver API is entirely implemented on the client side, integrated into IoT device firmware or management applications.
-
OCI Distribution API Compatibility:
- The Resolver API works as an adapter to the existing OCI distribution API without altering current OCI specifications.
-
Modularity and Extensibility:
- The API design is modular, allowing future enhancements such as support for multi-layer manifests or advanced query capabilities.
-
Performance:
- Optimized for asynchronous queries, local caching, and batch processing to handle real-time IoT state updates across federated registries.
In an IoT-PRS-based system, registries function as a stateful message bus that delivers multi-modal information to devices. The workflow includes:
-
System Image Deployment:
- An IoT device downloads its system image (which includes its workload and configuration) from an OCI registry.
-
State Subscription:
- The device subscribes to one or more OCI namespaces for state changes. Resolver functions continuously monitor for new artifacts indicating state mutations.
-
Declarative State Management:
- Users declare state changes (e.g., adjusting light brightness or color) through an interface. These changes are encoded as artifacts and pushed to the registry.
-
State Mutation and Resolution:
- IoT devices retrieve the updated state via the Resolver API, validate the changes using the canonical encoding and schema, and update their local state accordingly.
-
Local Action Execution:
- Devices execute logic operations based on state changes, performing sensory measurements or imperative actions such as controlling smart lights or digital assistants.
The IoT management solution is fully declarative:
-
User-Driven State Changes:
- Users indicate desired state changes (e.g., setting a preferred brightness level) via an application interface.
-
Registry as a Message Bus:
- OCI registries store both static assets (system images) and dynamic state records, serving as a federated message bus.
-
Mutability through Resolution:
- Devices and users communicate state mutations through standard mutation and resolution operations, ensuring that updates propagate through the system in a controlled, verifiable manner.
The "brightidea" example illustrates a user’s interaction with smart light bulbs and sensors:
-
Scenario Overview:
A user installs smart light bulbs equipped with IoT-PRS-based state resolution. Initially, the user manually adjusts brightness and color settings via a mobile application. -
State Encoding:
Each light bulb publishes its current state (e.g., brightness, color temperature, power status) as an artifact in its dedicated namespace. Tags such asbrightnessandcoloract as keys, while the manifest layer contains the actual state values. -
Schema Discovery:
The nameserver for the smart lighting domain provides a JSON Schema that defines the structure of these state records. -
Automated Adaptation:
Over time, the Resolver API on each bulb retrieves updated state artifacts from the registry. As the device accumulates historical state data, it begins to automatically adjust its behavior to match the user's preferences. -
Diminishing Manual Intervention:
Gradually, the manual controls become less necessary. The smart light’s state recognition system learns from the user’s historical interactions, adjusting brightness and color in anticipation of the user’s needs—embodying the "brightidea" where intelligence is built into the system. -
Declarative Updates:
Users continue to interact with the system declaratively, declaring new desired states when needed. These updates are encoded and pushed to the registry, with the Resolver API ensuring that the latest state is always resolved on the device.
The security of the IoT-PRS system is ensured by:
-
Immutable and Verifiable Encoding:
Every artifact is encoded in a canonical, immutable format. Any change produces a new artifact with a distinct content address. -
Content Addressability:
Artifacts are retrieved by their content-based addresses, ensuring integrity and tamper-evidence. -
Access Control:
Namespaces and indexes enforce robust access controls to protect sensitive IoT data and maintain ledger integrity. -
Schema Validation:
Automated schema discovery and validation ensure that only well-formed, authorized state records are processed.
Implementors of IoT-PRS must ensure:
-
Canonical Encoding Compliance:
All IoT artifacts must be encoded as specified, with namespaces as objects, tags as keys, and the manifest layer as the value. -
Resolver API Integration:
Devices and management systems must implement the Resolver API endpoints precisely, ensuring seamless interaction with the OCI distribution API. -
Schema Publication:
Publishers must register a machine-readable schema for their namespace using established metadata vocabularies. -
Interoperability Testing:
Rigorous testing for compatibility with existing OCI registries and cloud native tooling is required. -
Security Best Practices:
Follow recommended guidelines for content signing, integrity verification, and access control.
IoT-PRS transforms OCI registries into a stateful message bus for comprehensive IoT management. By encoding IoT artifacts in a canonical, self-describing format and incorporating built-in schema discovery, IoT-PRS provides a robust framework for managing system images, device state, and user-declared mutations. This declarative, federated approach enables smart, adaptive operations—exemplified by the "brightidea" scenario—while maintaining compatibility with existing OCI standards. This specification serves as a comprehensive guide for implementors and maintainers in the cloud native and IoT communities.
For further details and implementation examples, please refer to the accompanying implementation guide and reference repositories provided by the OCI working group.