]> An Application Layer Interface for Non-Internet-connected Physical Components (NIPC) Cisco Systems
Brussels Belgium bbrinckm@cisco.com
Cisco Systems
170 West Tasman Drive San Jose 95134 USA rohitmo@cisco.com
Philips
Cambridge USA braeden.sanford@philips.com
Internet-Draft This document describes an API that allows applications to perform operations against a gateway serving one or more devices described by an SDF model. The API consists of a RESTful application layer interface that performs operations on those devices, as well as a CBOR-based publish-subscribe interface for streaming data. Status information for this document may be found at . Discussion of this document takes place on the A Semantic Definition Format for Data and Interactions of Things Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .
Introduction
Motivation Low‑power sensors, actuators, and other connected devices deployed for building management, healthcare, workplace, manufacturing, logistics, and hospitality use cases are often resource and battery constrained. Many lack native IP connectivity and instead attach via heterogeneous non‑IP operational networks. Common non‑IP protocols include BLE and Zigbee . When IP is available, constrained application protocols such as CoAP may be used. These devices still need to exchange data with IP‑based applications. Accordingly, applications on the IP network obtain telemetry from and issue operations to such devices through an application‑layer gateway. This gateway bridges the application network and one or more separate operational networks where devices are connected, allowing applications on the IP network to perform operations on devices connected to these other operational networks.
Application Gateway Device Application Device network network | Gateway |<------------>| Device | | | Application | | Device | | +-------------+ network +---------+ network +--------+ ]]>
There have been efforts to define Gateway functions for devices that support a particular protocol, such as a BLE GATT REST API for BLE Gateways (), however they have been limited to a single protocol or a particular use case. In absence of an open standard describing how applications on an IP network communicate with devices on other operational networks, bespoke and vendor-specific implementations have proliferated. Each deployment then requires: (1) defining or adapting yet another API, and (2) deploying additional gateway functions, increasing operational and integration cost. This specification defines a single, extensible application layer interface for cross-network and cross-protocol device interaction through a network gateway. The intent is to support multiple network and network protocols (and versions) concurrently, allow incremental addition of new protocols via mapping, and reduce redundant infrastructure by enabling multiple applications to share one standardized gateway function. Furthermore, by leveraging interaction models, the application and gateway are able to maintain a protocol-neutral interface, while the gateway handles the protocol-specific interactions with devices. A standardized Application Layer Gateway interface has the following benefits: Eliminates repeated bespoke integration effort across deployments. Avoids deploying multiple overlapping gateway functions for different networks, protocols or use cases. Reduces time and operational cost to integrate new networks and devices. Allows applications to interact with devices in a protocol-neutral way, leveraging interaction models.
NIPC Gateway A Non-Internet-connected Physical Components (NIPC) gateway is an application layer gateway (ALG) that implements APIs for applications to communicate with devices on different networks connected to the Gateway. These devices may leverage different protocols, IP based or non-IP based. Even when the device network uses IP, the ALG may still need to act as an intermediary, since the device network may not be directly reachable from the application network, may use a different overlay protocol than the one expected by applications, or may be subject to a different authorization model. NIPC APIs allow reading or writing properties of devices, invoking actions on devices, as well as enabling or disabling events on devices, by means of a supporting gateway, in a protocol-neutral way. In order to perform NIPC operations on a device, 2 prerequisites must be fulfilled: The gateway has access to a device object, that contains its identity, in the form of a unique UUID and any credentials & trust material required to communicate with the device. Provisioning this device object is out of scope of this document. It may be performed via SCIM with . An interaction model for the class of devices must be available to the gateway. This allows the gateway to understand how to interact with the device in a protocol-neutral way. The interaction model is provided to the gateway by means of an SDF model, as described in . Once these prerequisites are met, the gateway can resolve an SDF affordance referenced in the SDF model into the protocol-specific operations required for that device. A NIPC gateway provides the following functions: Authentication and authorization of application clients that will leverage the NIPC APIs. Maintain or have access to a repository of device objects, including device identity and trust material. Accept and validate SDF interaction model registrations. Expose APIs for property, action, and event operations. Perform implicit connection management to devices where required; optionally support explicit connection management. Stream events (publish/subscribe) to authorized data applications. Proxy payloads between networks without interpreting or modifying application data. Operate one or more channels to supported wired or wireless networks. Optionally provide a bridge between devices on one or more device networks connected to the NIPC-Gateway. This may include translating between different protocols, if multiple protocols are supported on the device network(s). The gateway’s role is to provide gateway functions between application and device networks; it is not intended to be middleware that inspects, decodes, or transforms device payloads.
Request onboarding SCIM app Server Ctrl Endpt Control REST NIPC AP Device & | Gateway Telemetry pub/sub Apps Network Deployment | SCIM | | | app |<--------------+ Server | | +-----------+ Ctrl Endpt| +---------+ | | | +-----------+ | +------------+ +-------+ +--------+ | | Control +----REST------>| NIPC +-->| AP +-->| Device | | | & | | | Gateway | +-------+ +--------+ | | Telemetry |<--pub/sub-----+ | | | Apps | | +------------+ | +-----------+ | | | Network Deployment | +------------------------------------------+ ]]>
illustrates the basic components: applications, the NIPC application‑layer gateway (ALG), an access point (AP), and a device (D). The applications, ALG, and AP reside on an IP network; the AP provides a wireless or wired interface to the device. Applications often operate in a different administrative domain than the ALG and AP, so the ALG will have to support authorization. The ALG bridges the IP application domain and the device network, be it an IP-based or non-IP device network. This enables applications to perform operations on devices attached to those device networks. Applications use a JSON-based RESTful NIPC APIs for property, action, and event operations, and a CBOR‑based publish/subscribe interface for event streaming.
Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.
Glossary NIPC: Non-Internet-connected Physical Components, the application layer interface defined in this document. NIPC Gateway: An application layer gateway that implements the NIPC interface. SDF: Semantic Device Format, a standardized format to describe devices and their interaction models, as defined in . SDF Affordance: An interaction point on a device as defined in an SDF model. Examples of affordances are properties, actions, and events. SDF Global Name: Absolute URI (with fragment) identifying an SDF affordance. SCIM: System for Cross-domain Identity Management, a standardized protocol to manage identity information, as defined in . ALG: Application Layer Gateway. IoT: Internet of Things. Protocol Mapping / sdfProtocolMap: Mapping from protocol-neutral SDF affordances to protocol-specific operations. BLE: Bluetooth Low Energy protocol. Zigbee: Low-power mesh networking protocol. GATT: Generic Attribute Profile used in BLE for services/characteristics/descriptors. Service (BLE): Top-level GATT grouping of characteristics. Characteristic (BLE): GATT data element supporting read/write/notify. Descriptor (BLE): Metadata element attached to a characteristic. Bonding (BLE): Procedure to establish trusted, reusable security keys. Service Discovery (BLE): Procedure to enumerate GATT services/characteristics/descriptors. Endpoint (Zigbee): Addressable application entity on a Zigbee device, grouping clusters. Cluster (Zigbee): Group of related attributes and commands defined by the Zigbee Cluster Library. Attribute (Zigbee): Zigbee Cluster Library data element, supporting read/write/report access. Device ID / Group ID: UUID identifying a device or a group of devices. UUID: Universally unique identifier (128-bit). Data Application / Data App: Registered application receiving streamed event data. MQTT: Publish/subscribe messaging protocol used for streaming. Webhook: HTTP callback endpoint for push delivery. Websocket: Bidirectional TCP-based message channel over HTTP. Publish/Subscribe Interface: Streaming channel for events (CBOR-encoded payloads). CBOR: Concise Binary Object Representation; compact binary data format. CDDL: Concise Data Definition Language; schema language for CBOR data. JSON: JavaScript Object Notation; text encoding used for API payloads. Access Point (AP): Network element with a radio interface communicating with devices.
Architecture
Overview A Non‑Internet‑Connected Physical Components (NIPC) gateway is an application‑layer gateway (ALG) that exposes APIs enabling applications to perform operations on devices attached to networks connected to the gateway. NIPC defines two API categories: Registrations: register SDF models for classes of devices and register data applications that receive streaming event data. Operations: perform protocol‑neutral device interactions (read/write properties, invoke actions, enable/disable events) across heterogeneous networks and protocols. To execute NIPC operations on a device, both prerequisites MUST be met: The NIPC gateway has access to device instance information: The device object contains its identity, in the form of a unique UUID and any credentials/trust material required to communicate with the device (e.g., via SCIM with ). This device object is identified by the device ID referenced in NIPC API paths. The NIPC gateway has access to an interaction model (device class information): An SDF model is registered, providing protocol‑neutral affordances and mappings to protocol‑specific operations.
SCIM object {ID} NIPC Operation - Property - Action - Event SDF model | | +------------+ | NIPC Operation | | - Property | | - Action | +------------+ | - Event | | SDF +---------->| | | model | +----------------+ +------------+ ]]>
Once both prerequisites are met, authorized applications can perform NIPC operations on devices identified by their IDs. See for authorization details. NIPC operations act on SDF affordances—properties, actions, and events defined in the registered SDF model. Certain NIPC operations may also be performed on groups of devices identified by a group ID.
Device instance information In order for the NIPC gateway to perform operations on a device, it must have access to the device's instance information. This includes the device’s identity and any credentials or trust material required to communicate with the device. The device object MUST include a unique identity (UUID) and sufficient information to bootstrap trust and establish connectivity, as NIPC operations assume connectivity can be established without separate API calls. While provisioning devices instance information can be performed in various ways, it is RECOMMENDED to use SCIM with the device schema , which defines the necessary attributes and extensions to support NIPC. As per , group objects may also be declared, and leveraged in NIPC operations.
Device class information Device class information is declared through SDF models, as defined in . These SDF models define the protocol-neutral affordances of a class of devices, as well as protocol mappings that relate these affordances to protocol-specific operations. The SDF model for a class of devices can be registered through NIPC registration APIs, as described in . The SDF model reference and/or data‑app registration MAY also be included in a device's SCIM object. See and for details.
NIPC Registrations NIPC registration APIs allow applications to register objects that are not tied to specific device instances. NIPC supports two registration types: SDF model registration: Registers an SDF interaction model for a class of devices. Data application authorization: Authorizes an application to receive streaming event data.
SDF model registrations The SDF model for a class of devices determines how a gateway can interact with these devices in a protocol-neutral way. To enable this, the SDF model must contain protocol mappings, mapping protocol-neutral SDF affordances to protocol-specific operations as defined in . The SDF affordances supported by the device, as well as its protocol-mappings, are provided to the gateway by means of an SDF model. SDF models are described in .
Data application registrations NIPC operations can enable or disable event reporting on a device. Events are reported through a publish-subscribe interface. Applications that are authorized to perform NIPC operations on devices can define which applications are permitted to receive streaming event data for that device. The data-app registrations API maps an event to an application that is authorized to receive that data. The registration also defines what protocol will be used to deliver the data (e.g., MQTT, webhook, websocket). This registration basically allows applications to instruct the gateway to direct event data-streams to specific data-applications.
NIPC Operations
Overview NIPC APIs are exposed over HTTP . Requests and responses use JSON unless another media type is negotiated via Content-Type and Accept. A media type for an SDF affordance can also be stipulated in the SDF ContentFormat data quality, as described in . The default media type is “application/nipc+json” (see ). SDF model registrations use “application/sdf+json”. Property APIs MAY use other media types appropriate to the property payload. Failures use Problem Details with media type application/problem+json. NIPC operations are protocol-neutral operations on SDF affordances, more specifically properties, actions & events. NIPC operations can happen against affordances registered in an SDF model. Operations reference affordances by their SDF global name. If the underlying protocol requires a connection, the gateway establishes and tears down the connection implicitly unless an explicit connection is already in place. NIPC exposes four operation groups: Properties APIs: These APIs allow applications to perform operations on properties, such as to read or write values to them. Actions APIs: These APIs perform actions on devices, such as enabling or disabling a feature on a device. Events APIs: These APIs allow apps to enable or disable event reporting on devices. Events are reported over the events publish/subscribe interface. Trigger APIs: These APIs allow an event on one device or group to trigger an action on another device or group. Trigger APIs are not a fundamental operation, but rather tie 2 fundamental operations together; an event triggers an action.
Properties Property operations allow clients to read and write values for SDF properties. An example of using a property API is reading the property temperature from a temperature sensor. Requests and responses use application/nipc+json unless another media type is negotiated via Content‑Type and Accept. When using JSON, binary property values are base64‑encoded with padding per . Regardless of media type, the byte order of any multi-byte values within a binary payload is not specified by NIPC and is determined by the underlying protocol. Multiple properties MAY be read or written in a single request. When a single property is addressed via a query parameter, non‑JSON media types MAY be used for the payload. On success, the response returns either 200 with per‑property status (JSON) or 204 No Content for single, non‑JSON writes.
Actions Action operations invoke SDF actions on devices. An example of using an action API is to turn on a lightbulb. A successful action request returns 202 Accepted with a Location header referencing the action instance. Clients poll the instance URI to obtain status (e.g., IN_PROGRESS, COMPLETED). Request bodies are optional and MAY carry action input in a media type appropriate to the underlying protocol (e.g., octet‑stream).
Events Event operations enable and disable device event reporting. An example of using an event API receiving an event that a button has been pressed. Enabling an event returns 201 Created with a Location header referencing the event instance. Disabling an event uses the instance identifier and returns 204 No Content on success (for a single device) or 200 Success with a per‑device status list (for a group). Event payloads are delivered via the publish/subscribe interface encoded in CBOR .
Triggers Triggers allow an event on one device or group to trigger an action on another device or group. Triggers are not protocol-specific. As an example, an event on a BLE device can trigger an action on a Zigbee device. An example of a Trigger is when a button is pressed (event), a lightbulb should turn on (action). Multiple buttons (group) can also turn on a lightbulb (device). A single button (device) could also turn on multiple lights (group). Creating a trigger returns 201 Created with a Location header referencing the trigger instance. Deleting a trigger uses the instance identifier and returns 204 No Content on success (for a single device) or 200 Success with a per‑device trigger list (for a group).
Groups Where supported by the underlying protocol, operations MAY target a group of devices identified by a group ID. Responses for group operations return per‑device results; failures for individual devices are reported using Problem Details entries within the array.
Connection management for NIPC Operations For protocols that require connection setup, the gateway performs implicit connection management during an operation (establish on demand; tear down on completion). Gateways MAY support explicit connection management; when an explicit connection is active, operations reuse it and do not tear it down. Explicit connection management is described in .
Extensions NIPC supports API extensions for compound or specialized operations. Extensions can execute a set of NIPC operations in a single request or provide more efficient mechanisms for specific use cases (e.g., a bulk operation). Extensions MUST use the “/extensions” path element. To ensure interoperability, extensions MUST be registered with IANA as defined in .
Events publish subscribe interface Events are delivered via a publish/subscribe interface. NIPC events are encoded in CBOR () and can be transported over MQTT, Webhook or Websocket. CBOR is used for the publish/subscribe interface as Non-IP payloads are typically binary. CBOR encodes binary payloads efficiently, and is more compact than JSON, therefore reducing the amount of data that needs to be transmitted to the application. Event types include: Streaming data from devices: Streaming data is activated/deactivated with the NIPC events API Broadcasts from devices (e.g., advertisements in BLE) Connection events: Devices connecting & disconnecting
Paths
General The NIPC HTTP protocol is described in terms of a path relative to a Base URI. The Base URI MUST NOT contain a query string, as clients MAY append additional path information and query parameters as part of forming the request. The base URI is a URL that most often consists of the "https" protocol scheme, a domain name, and an initial path . That initial path for NIPC is recommended to be /nipc. For example:
Additionally a version number may be added, for example:
After the base or version number, the path must contain a collection identifier. The collection identifier can be one of the following: /registrations: for NIPC registration APIs /devices: for NIPC operations on devices /groups: for NIPC operations on groups of devices /extensions: for NIPC extension APIs The well-known URI /.well-known/nipc defined in can be used to discover the base path of the NIPC APIs and the supported versions and extensions. The response to a GET request on this URI MUST be a JSON document that contains the base path, and optionally the supported versions and extension APIs. The paths MUST be a URI template as defined in . The following is an example of a template defining the NIPC base path as well as supported extensions on a server.
A formal CBOR definition of the well-known response is as follows:
NIPC Registrations Registrations leverage the base path + /registrations. NIPC supports SDF model registrations and data-app registrations. paths: /registrations/models /registrations/data-apps
NIPC Operations Every NIPC Operations API pertains to either a device or group of devices, identified by an ID, hence the ID must be reflected as the first parameter in the path. For example:
The second parameter in the path refers to the NIPC operation that the API will perform on the device. This can be: properties events actions triggers extensions These are described in .
Schema The NIPC schema leans heavily on the SDF schema, as defined in . NIPC operations map directly to SDF affordances.
SDF model registrations To execute NIPC operations, an SDF interaction model for the device class MUST be registered. The model MUST include protocol mappings that relate protocol‑neutral SDF affordances to protocol‑specific operations. Registration is performed via POST /registrations/models with the SDF model in the request body. A registered model can be retrieved via GET /registrations/models using the model identifier (sdfName).
NIPC Operations NIPC operations require two parameters: Device ID: the UUID identifying the target device (or group). sdfName: the SDF global name (absolute URI with fragment) of the affordance (property, action, or event) on which the operation acts.
Device ID All NIPC operations are executed against a device or a group of devices. Devices or groups of devices are identified by a unique UUID, adhering to . Attribute Type Example id uuid 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 ID is a UUID assigned to uniquely identify a device to the NIPC Gateway (e.g., by a SCIM server) and the application calling the APIs. The NIPC Gateway must have access to a device object identified by this device ID and the application must store this UUID in order to use it to identify the device on which it wants to perform NIPC operations.
SDF Name Operations act on SDF affordances and reference them by SDF global name—an absolute URI with fragment that includes the namespace. The affordance referenced MAY be a property, action, or event; the reference is carried as a string. For example: NIPC Operation Example SDF Name used in the API Property https://example.com/heartrate#/
sdfObject/thermostat/sdfProperty/temperature Event https://example.com/heartrate#
/sdfObject/healthsensor/sdfEvent/fallDetected Action https://example.com/heartrate#/
sdfObject/thermostat/sdfAction/resetThermostat
Parameters To minimize deployment risk arising from inconsistent URI path normalization and handling of percent‑encoded reserved characters in path elements (notably “/” encoded as “%2F”) across common HTTP servers and intermediaries (e.g., Jetty, Tomcat, Apache httpd, NGINX), NIPC uses query parameters (except the primary {id} path segment) rather than additional path segments for values that can legitimately contain reserved characters (such as SDF global names). Although and require that reserved characters not be normalized or decoded in ways that alter semantics, misinterpretation of these rules has led to security vulnerabilities (path confusion, cache poisoning, authorization bypass) and to conservative default configurations that reject encoded slashes. In proxy deployments, relaxing these defaults often triggers security review friction. Representing such values in the query component avoids reliance on tolerant path normalization behavior, reduces ambiguity for intermediaries, and aligns with prevailing “safe” operational profiles; a malformed or unsupported parameter can be rejected with a 4xx status without exposing downstream services to traversal or normalization discrepancies.
Responses A NIPC Gateway must respond to a NIPC operation request synchronously, and provide the result of the completed operation in the HTTP response. Exceptions to this are the following: Extensions: Extension APIs (see ) execute compound operations and thus require the gateway to execute multiple NIPC operations. On acceptance, the gateway returns 202 Accepted. Clients poll the extension URI (GET) for execution status. If a callback URI was supplied in the request, the gateway MAY send the final result upon completion. Actions: Action requests return 202 Accepted with a Location header pointing to the action instance used for status tracking, and a Retry-After header indicating the number of seconds the client should wait before polling for status. A failure response must contain an HTTP status code of 4xx or 5xx, and use Problem Details with application/problem+json media type. All NIPC failure responses must include the following attributes: type: a URI identifying the error (see ) status: the 4xx or 5xx HTTP status code title: a brief, human‑readable summary detail: a human‑readable explanation specific to this occurrence Additional attributes MAY be included as permitted by .
Example of a failure response:
NIPC Registration APIs
SDF model registrations APIs SDF model registration APIs allow applications to register an SDF model for a class of devices. These APIs use the application/sdf+json media type, as described in .
Register an SDF model Method: POST /registrations/models Description: Registers one or more SDF models for a class of devices. If the SDF model is already registered, the gateway will return an error with the sdf-model-already-registered problem type. Request Body: The SDF document in JSON format containing one or more sdfThings or sdfObjects, similar to the example in . The SDF document MUST contain protocol mappings, as described in . Response: A list containing objects where each object has an "sdfName" which is the global name of the top-level sdfThing or sdfObject in the SDF model. The response uses the 201 Created status code.
Example of a response:
Get all SDF models Method: GET /registrations/models Description: Gets all SDF models registered with the gateway. Response: A list containing objects where each object has an "sdfName" which is the global name of the top-level sdfThing or sdfObject in the SDF model.
Example of a response:
Get an SDF model Method: GET /registrations/models{?sdfName} Description: Gets an SDF model registered with the gateway. Query Parameters: sdfName: the name of the top-level sdfThing or sdfObject in the SDF model. Response: The SDF model is returned in JSON format, similar to the example in .
Delete an SDF model Method: DELETE /registrations/models{?sdfName} Description: Deletes an SDF model registered with the gateway. Query Parameters: sdfName: the name of the top-level sdfThing or sdfObject in the SDF model. Response: An object with an "sdfName" which is the global name of the top-level sdfThing or sdfObject in the SDF model
Example of a response:
Update an SDF model Method: PUT /registrations/models{?sdfName} Description: Updates an SDF model registered with the gateway. Query Parameters: sdfName: the name of the top-level sdfThing or sdfObject in the SDF model. Request Body: An SDF model in JSON format, similar to the example in . Response: An object with an "sdfName" which is the global name of the top-level sdfThing or sdfObject in the SDF model
Example of a response:
Data application registrations APIs Data-app registration APIs allow applications to register a data application that will receive streaming data from the gateway. These APIs operate on a data app ID. This ID corresponds to the endpoint app ID of the telemetry endpoint app that is registered with the SCIM server as an authorized endpoint that can receive data for a device. The endpoint app is defined in . Apart from the endpoint app ID, the API also configures the protocol the data-app supports. These should be one of the following: mqttClient: The data-app is an MQTT client, which means that the NIPC gateway must act as an MQTT broker. mqttBroker: The data-app is an MQTT broker, which means that the NIPC gateway must act as an MQTT client. The MQTT broker configuration data, such as the URI, credentials and MQTT topic must also be provided in the registration API. webhook: The data-app supports a webhook the gateway can publish to. The registration API has to include the webhook URI & credentials. websocket: The data-app supports a websocket interface. The registration API has to include the websocket URI & credentials.
Register a data application Method: POST /registrations/data-apps{?dataAppId} Description: Registers a data application with the gateway. Query Parameters: dataAppId: the ID of the data application Request Body: events: a list of events that the data application is authorized for. mqttClient: a boolean that denotes that the data application is an MQTT client. mqttBroker: The data app is an MQTT broker. This object contains the MQTT broker information: URI: the URI of the MQTT broker. username: the username to authenticate with the MQTT broker. password: the password to authenticate with the MQTT broker. brokerCACert: the base64-encoded CA certificate of the MQTT broker (optional). customTopic: By default, the topic will be composed of data-app/<dataAppId>/<namespace>/<json_pointer_to_sdf_event>, as described in . In this attribute, a custom topic can be configured (optional). webhook: The data app supports a webhook. This object contains a webhook URL along with any credentials that are required to authenticate the webhook. URI: the webhook URI. The URI MUST include the scheme used by the webhook server (e.g., "https://"). It is up to the implementation to support different schemes. If a scheme is not supported, the NIPC gateway MUST return an error response with type "https://www.iana.org/assignments/nipc-problem-types#unsupported-uri-scheme". headers: An object that contains the headers to be sent with the webhook request. The headers can contain any authentication information required by the webhook server. Each header is represented as a key-value pair in the object. serverCACert: the CA certificate of the webhook server, encoded as per and newlines encoded as '\n' (optional) websocket: The data app supports a websocket. This object contains a websocket URL along with any credentials that are required to authenticate the websocket. The websocket URL is the endpoint where the streaming data will be sent. URI: the websocket URI. The URI MUST include the scheme used by the websocket server (e.g., "wss://"). It is up to the implementation to support different schemes. If a scheme is not supported, the NIPC gateway MUST return an error response with type "https://www.iana.org/assignments/nipc-problem-types#unsupported-uri-scheme". headers: An object that contains the headers to be sent with the websocket request. The headers can contain any authentication information required by the websocket server. Each header is represented as a key-value pair in the object. serverCACert: the CA certificate of the websocket server, encoded as per and newlines encoded as '\n' (optional)
text }, ; key/value headers ? serverCACert: text } } DataAppWebsocket = { websocket: { URI: text, ? headers: { * text => text }, ; key/value headers ? serverCACert: text } } ]]>
Example of a request body:
Example of a request body for a data application that is an MQTT broker:
Response: If successful, the response will be identical to the request body.
Update a data application Method: PUT /registrations/data-apps{?dataAppId} Description: Updates a data application registration. Query Parameters: dataAppId: the ID of the data application Request Body: The request body is identical to the request body for the register data application API . Response: If successful, the response will be identical to the request body.
Get a data application Method: GET /registrations/data-apps{?dataAppId} Description: Gets a data application object registered with the gateway. Query Parameters: dataAppId: the ID of the data application Response: The response will be identical to the request body for the register data application API .
Delete a data application Method: DELETE /registrations/data-apps{?dataAppId} Description: Deletes a data application registered with the gateway. Query Parameters: dataAppId: the ID of the data application Response: If successful, the response will be 204 No Content.
NIPC Operation APIs The NIPC operation APIs perform protocol‑neutral interactions on SDF affordances, properties, events, and actions. This allows applications to read and update device properties, invoke actions, and consume events. NIPC defines three API collections aligned with the SDF Affordances defined in : Properties: read and write device properties. Events: enable and disable device event reporting. Actions: invoke device actions. Additionally, NIPC defines one more API collection that allows applications to install triggers on events. Triggers will trigger an action if the event is executed. Trigger collection: Triggers: Install a trigger on an event (invokes an action) To invoke NIPC operations APIs on a device, one or more SDF models MUST be registered for that device. The SDF model MAY have a top‑level sdfThing (with multiple sdfObjects) or a top‑level sdfObject. Operations depend on affordances (sdfProperty, sdfEvent, sdfAction) defined in the registered SDF model and on a device ID (see ). Affordances are referenced by their SDF global name (absolute URI with fragment) as described in . The NIPC Gateway must match the SDF global name against the registered SDF model to resolve the protocol mapping (protocolmap) the gateway will execute. When carried in a URI, the SDF global name MUST be percent‑encoded per .
NIPC Property APIs These APIs allow applications to read and update device properties. If the underlying protocol requires a connection, the gateway establishes it implicitly for the operation; when an explicit connection is already active, operations reuse it without modification. Requests and responses support content negotiation via Content-Type and Accept. When using "application/nipc+json", payloads must follow the examples above. Binary property values must be base64‑encoded with padding per in the "value" field. For other media types, payload semantics must follow the selected media type.
Update one or multiple values Method: PUT /devices/{id}/properties{?propertyName} Description: Write values to one or more properties on a device Parameters: id: the ID of the device Query Parameters: propertyName: Identifies a single property to update. If present, the request body MAY use any media type appropriate to the property payload. -or- If absent, the request body MUST be application/nipc+json and contain an array of update items, each with a property and a value. Request Body: If the query parameter propertyName is provided, the request body MAY use any media type appropriate to the property payload. The value is encoded as per the content type of the payload. -or- If the query parameter propertyName is NOT provided, the request body must be an array of properties to update, each containing a property and a value. The value attribute contains the raw binary data, which must be encoded in base64 with padding as per .
Example body for updating multiple properties:
Response: If the Accept header is set to application/nipc+json, the response must be an array with a status field set to 200 for each property that was updated, or a problem type object for each property that failed to update. The "properties" array must be an array of properties that were updated, each containing a property and a value. -or- If the Accept header is set to any other media type and the propertyName query parameter is provided, the response must be 204 No Content with no body.
Example of a response:
Read one or multiple values Method: GET /devices/{id}/properties{?propertyName*} Description: Read values from one or more properties on a device Parameters: id: the ID of the device Query Parameters: propertyName: The property to read. This can be a single property or multiple properties. If multiple properties are provided, the request body MUST contain an application/nipc+json payload with an array of properties to read. Response: If the Accept header is set to application/nipc+json, the response must be an array of properties, each containing a property and a value. The value must be the raw binary data read from the property, encoded in base64 with padding as per . The array must contain objects with 2 attributes: - property: The property that was read. - value: The bytes that were read in base64 encoding -or- If the Accept header is set to any other media type and a single propertyName query parameter is provided, the request body MAY use any media type appropriate to the property payload. The value is encoded as per the content type of the payload.
Example of a response:
NIPC Event APIs Event APIs enable or disable reporting of device events. For certain protocols, a connection may be required. If the underlying protocol requires a connection, the gateway establishes it implicitly for the operation. If an explicitly created connection is already active, it is reused without modification. Events are referenced by the SDF global name of an sdfEvent. The {id} path segment identifies a device or a group of devices. A group event MAY be enabled only if the underlying protocol supports group activation (e.g., BLE advertisement or connection status events). Events are delivered to registered data-apps over a publish/subscribe interface, as defined in . If the data application registered for this event is an MQTT broker or client, the event SDF global name may be used to construct the MQTT topic for the event. The topic is constructed using the data application ID, the default namespace for the event, and the event itself. For example, if the data application ID is "0927ce7c-b258-4bfa-a345-bcc9f74385b4" and the event is "https://example.com/thermometer#/sdfThing/thermometer/sdfEvent/isPresent", the topic will be:
// data-app/0927ce7c-b258-4bfa-a345-bcc9f74385b4/thermometer/sdfThing/\ thermometer/sdfEvent/isPresent ]]>
A data application may subscribe to this topic using the topic or it may use MQTT wildcards to subscribe to data-app/+/temperature/# to receive all events for the temperature namespace. If a customTopic was supplied in the data‑app registration (mqttBroker case), that topic MUST be used instead of the constructed default.
Enable event reporting Method: POST /devices/{id}/events{?eventName} Description: Enables an event on a device Parameters: id: the ID of the device Query Parameters: eventName: the event to enable. The eventName must be a URL encoded string that is the absolute URI that is the global name of an sdfEvent. Response: Returns HTTP status code 201 Created with a Location header pointing to the created event instance. Example of a successful response:
The Location header must contain the URI for the created event instance, which may be used to check status or disable the event.
Disable event reporting Method: DELETE /devices/{id}/events{?instanceId} Description: Disables an event on a device Parameters: id: the ID of the device or group of devices Query Parameters: instanceId: the instance ID of the event to disable (obtained from the Location header when the event was enabled) Response: Returns HTTP status code 204 No Content on successful disable.
Get status of one or more events Method: GET /devices/{id}/events{?instanceId*} Description: Get the status of one or more events on a specific device Parameters: id: the ID of the device or group of devices Query Parameters: instanceId: a comma separated list of event instance IDs to filter by (optional) Response: The response must be an array of events, each containing an instanceID and an event. - instanceId: must be the unique instance ID for each enabled event. - event: must be the event URI for each enabled event.
Example of a response:
Enable event reporting on a group of devices Method: POST /groups/{id}/events Description: Enables an event on a group of devices Parameters: id: the ID of the group of devices Query Parameters: eventName: the event to enable. The eventName is a URL encoded string that is the absolute URI that is the global name of an sdfEvent. Response: The response must return HTTP status code 201 Created with a Location header pointing to the created event instance. The Location header must contain the URI for the created event instance, which can be used to check status or disable the event. Example of a successful response:
Disable event reporting on a group of devices Method: DELETE /groups/{id}/events{?instanceId} Description: Disables an event on a group of devices Parameters: id: the ID of the group of devices Query Parameters: instanceId: the instance ID of the event to disable (obtained from the Location header when the event was enabled) Response: MUST return 200 OK with an array of per‑device event status entries. For each device where the event was successfully disabled, the entry MUST include deviceId and event (SDF global name). For each device where disabling failed, the entry MUST be a Problem Details error object for that device.
Example of a response:
Get event status on a group of devices Method: GET /groups/{id}/events{?instanceId} Description: Get the status of one or more events for a group of devices Parameters: id: the ID of the group of devices Query Parameters: instanceId: the instance ID of the event (obtained from the Location header when the event was enabled). Response: MUST return 200 OK with an array of per‑device event status entries. For each device where the event was successfully enabled, the entry MUST include deviceId and event (SDF global name). For each device where enabling failed, the entry MUST be a Problem Details error object for that device.
Example of a response:
NIPC Action APIs NIPC Action APIs invoke device actions. If the underlying protocol requires a connection, the gateway establishes it implicitly for the operation. If an explicitly established connection is already active, the operation MUST reuse it without modification.
Perform an action Method: POST /devices/{id}/actions{?actionName} Description: Perform an action on a specific device Parameters: id: the ID of the device Query Parameters: actionName: the action to perform Request Body: The request body is optional and may contain a value. The media type of the value can be defined by the underlying protocol, for example it could be octet-stream for binary data. Response: Actions are performed asynchronously. A successful request returns HTTP status code 202 Accepted with a Location header pointing to the action instance for status checking, and a Retry-After header indicating the number of seconds the client should wait before polling. The Location header contains the URI for the action instance, which can be used to check the action status. Example of a successful response:
Check action status Method: GET /devices/{id}/actions{?instanceId} Description: Check the status of an action on a specific device Parameters: id: the ID of the device Query Parameters: instanceId: the instance ID of the action (obtained from the Location header) Response: MUST return 200 OK with an action status, which may be "IN_PROGRESS" or "COMPLETED".
Example of a response:
Perform an action on a group of devices Method: POST /groups/{id}/actions{?actionName} Description: Perform an action on a group of devices Parameters: id: the ID of the group Query Parameters: actionName: the action to perform Request Body: The request body is optional and may contain a value. The media type of the value can be defined by the underlying protocol, for example it could be octet-stream for binary data. Response: Actions are performed asynchronously. A successful request returns HTTP status code 202 Accepted with a Location header pointing to the action instance for status checking, and a Retry-After header indicating the number of seconds the client should wait before polling. Example of a successful response:
Check group action status Method: GET /groups/{id}/actions{?instanceId} Description: Check the status of an action on a group of devices. Returns a per-device status array. Parameters: id: the ID of the group Query Parameters: instanceId: the instance ID of the action (obtained from the Location header) Response: MUST return 200 OK with an array of per-device action statuses. Each entry contains the action status and a deviceId. Entries for failed devices contain a problem detail with the deviceId.
Example of a response:
NIPC Trigger APIs Triggers APIs do not actually execute an operation on a device or group of devices, but install a trigger that registers an operation. When triggered the registered operation gets executed. Triggers can be installed for devices or groups of devices, represented by their id as a path parameter. The trigger must always be triggered by an event. the global name of the event must be passed as a path parameter. The triggered operation must always be an action. Since an action can be executed against both a device and a group, the trigger API also supports actions on both devices and groups of devices. The action is defined by its full NIPC URI to be executed, for example:
If a NIPC Gateway supports multiple protocols, then a trigger can be defined on a devices that supports one protocol and triggers an action on a device that supports a different protocol. As an example, an event on a BLE device can trigger an action on a Zigbee device.
Create a trigger on a device Method: POST /devices/{id}/triggers{?eventName} Description: Creates a trigger on an affordance of a device. A trigger will trigger an action on another device or a group of devices. If a trigger for the same eventName is already enabled on the device, the gateway MUST return an error with the trigger-already-enabled problem type. Parameters: id: the ID of the device Query Parameters: eventName: the eventName of the event that is associated with the trigger. This must be a URL encoded string that is the absolute URI that is the global name of an sdfEvent. Request Body: The request body must be of type 'application/nipc+json', and contain an action object. The action object contains a NIPC URI to be executed, including the device or group id and actionname percent-encoded query parameter.
Example body for trigger creation:
Response: Returns HTTP status code 201 Created with a Location header pointing to the created trigger instance. Example of a successful response:
The Location header must contain the URI for the created trigger instance, which may be used to check status or disable the trigger.
Delete a trigger on a device Method: DELETE /devices/{id}/triggers{?instanceId} Description: Deletes an installed trigger Parameters: id: the ID of the device Query Parameters: instanceId: the instance ID of the trigger to disable (obtained from the Location header when the trigger was installed) Response: Returns HTTP status code 204 No Content on successful delete.
Get installed triggers for a device Method: GET /devices/{id}/triggers{?instanceId} Description: Get the installed triggers for a devices, or a specific trigger when specifying an instanceId. Parameters: id: the ID of the device Query Parameters: instanceId: an InstanceID, or comma separated list of event instance IDs to filter by (optional) If no query parameter is supplied, then all triggers for the device must be retrieved Response: The response must be an array of triggers, each containing an instanceId, the sdfName of an event and an action. instanceId: must be the instance ID for each installed trigger, as returned by the NIPC GW when the trigger was created. eventName: must be the sdfName of the event that is associated with the trigger. action: must be the NIPC URI of the action to be executed when the trigger is activated.
Example of a response:
Create a trigger on a group of devices Method: POST /groups/{id}/triggers{?eventName} Description: Creates a trigger on an affordance of a group of devices. A trigger will trigger an action on another device or a group of devices. If a trigger for the same eventName is already enabled on the group, the gateway MUST return an error with the trigger-already-enabled problem type. Parameters: id: the ID of the group of devices Query Parameters: eventName: the eventName of the affordance that is associated with the trigger. This must be an event. The eventName must be a URL encoded string that is the absolute URI that is the global name of an sdfEvent. Request Body: The request body must be of type 'application/nipc+json', and contain an action object. The action object contains a NIPC URI to be executed, including the device or group id and actionname percent-encoded query parameter.
Example body for trigger creation:
Response: Returns HTTP status code 201 Created with a Location header pointing to the created trigger instance. Example of a successful response:
The Location header must contain the URI for the created trigger instance, which may be used to check status or disable the trigger.
Delete a trigger on a group of devices Method: DELETE /groups/{id}/triggers{?instanceId} Description: Deletes an installed trigger Parameters: id: the ID of the group of devices Query Parameters: instanceId: the instance ID of the trigger to disable (obtained from the Location header when the trigger was installed) Response: Returns HTTP status code 204 No Content on successful delete.
Get installed triggers for a group of devices Method: GET /groups/{id}/triggers{?instanceId} Description: Get the installed triggers for a group of devices, or a specific trigger when specifying an instanceId. Parameters: id: the ID of the group of devices Query Parameters: instanceId: an InstanceID, or comma separated list of event instance IDs to filter by (optional) If no query parameter is supplied, then all triggers for the group of devices must be retrieved Response: The response must be an array of triggers, each containing an instanceId, the sdfName of an affordance and an action. - deviceId: must be the device ID for each installed trigger. - eventName: must be the sdfName of the affordance (event or action) that is associated with the trigger. - action: must be the NIPC URI of the action to be executed when the trigger is activated.
Example of a response:
NIPC explicit connection management APIs Some protocols do not require explicit connection setup; for those protocols, the APIs in this section do not apply. For protocols that do require a connection (e.g., BLE), an NIPC gateway performs implicit connection management for individual operations (establish on demand; release on completion), so clients ordinarily need not manage connections. Clients MAY choose to explicitly establish and retain a connection to perform a sequence of operations that depends on intermediate results. This section specifies APIs for explicit connection lifecycle control. Examples use BLE.
Protocol Information Object The protocol information object is used to define protocol specific parameters for connections. The protocol information object is protocol specific and defined in the protocol extensions. An example of where a protocol info object would be used is to return protocol specific connection parameters when making connections, for example a BLE service map. An example of a BLE protocol information object is shown below. This specification defines both the BLE and the Zigbee protocol information objects for connections and broadcast messages.
Connect to a device Method: POST /devices/{id}/connections Description: Connect to a device Parameters: id: the ID of the device Request Body: Connection retry parameters A protocol info object representing the BLE service map to be discovered. In the case of BLE, if no protocol info object is included, service discovery is performed to discover all supported properties when connecting to a device. Optionally, service discovery may be limited to properties defined in the "ble" protocol extension. The services to be discovered can be added in an array. Property discovery can be buffered across connections, so the API also supports caching parameters.
Example body of a connection without specific discovery of properties:
where- "retries" defines the number of retries in case the operation does not succeed In case the application would like to discover specific properties of a device, an additional protocol information object can be provided that defines what properties should be discovered. Example body of a BLE connection with specific discovery of properties:
where in the BLE protocol object: "services" is an array of services defined by their serviceIDs. "cached" refers to whether the services need to be discovered for this connection. If cached is true, the services will be discovered for this connection only if it is not present in the cache. If cached is false, the services will be discovered for this connection. The services will be cached once it is discovered. "cacheExpiryDuration" defines how long (in seconds) the cache should be maintained before purging. some devices support notifications on changes in services, "autoUpdate" allows the network to update services based on notification (on by default) "bonding" allows you to override the bonding method configured in the device object. Possible values are default, none, justworks, passkey, oob. Default behavior is to use the bonding method defined in the device object. Response: Success responses includes an optional protocol information object with an array of discovered properties, as defined in the BLE protocol info object in section . This is an array of supported services, which in turn contains an array of characteristics, which in turn contains an array of descriptors, as shown in .
characteristics - characteristicID - flags | |> Descriptors - descriptorID ]]>
Example of a response:
where- "id" is the ID of the device "protocolInformation" contains an Array of BLE services as shown in A failure will generate a standard failed response. Please refer to definition of failed response.
Update a connection Method: PUT /devices/{id}/connections Description: Update a connection, for BLE this will update the cached ServiceMap for a device. Full service discovery will be performed, unless specific services are described in the API body. Parameters: id: the ID of the device Request Body: A protocol information object. In the case of BLE, if no protocol information is included, service discovery is performed to discover all supported properties when connecting to a device. Optionally, service discovery may be limited to properties defined in the "ble" protocol extension. The services to be discovered can be added in an array. Property discovery can be buffered across connections, so the API also supports caching parameters. Example body of an update connection:
where in the BLE protocol object: "services" is an array of services defined by their serviceIDs "cached" refers to whether the services need to be cached for subsequent connects, in order not to perform service discovery on each request "cacheExpiryDuration" defines how long the cache should be maintained before purging some devices support notifications on changes in services, "autoUpdate" allows the network to update services based on notification (on by default) Response: Success responses include a protocol information object with an array of discovered properties, as defined in the specific protocol. For example, for BLE, this is an array of supported services, which in turn contains an array of characteristics, which in turn contains an array of descriptors, as shown in . Example of a response:
where- "id" is the ID of the device "protocolInformation" contains an Array of BLE services as shown in and described in . A failure will generate a standard failed response. Please refer to definition of failed response.
Disconnect from a device Method: DELETE /devices/{id}/connections Description: Disconnect from a device Parameters: id: the ID of the device Response: Returns HTTP status code 204 No Content on successful disconnect. A failure will generate a standard failed response. Please refer to definition of failed response.
Get connection status Method: GET /devices/{id}/connections Description: Get connection status for a device. Success when device(s) is/are connected, includes service map for the device if available. Failure when a device is not connected. Parameters: id: the ID of the device Response: Example of a response:
where- "id" is the ID of the device "protocolInformation" contains an Array of BLE services as shown in A failure will generate a standard failed response. Please refer to definition of failed response.
NIPC Extensibility NIPC is designed to be extensible in two complementary ways: Protocol mappings: NIPC relies on SDF protocol mappings to relate protocol‑neutral affordances to protocol‑specific operations. Adding a new mapping enables support for additional device protocols (or versions) without the need to change the NIPC API itself. This allows deployments to evolve as device ecosystems change, while preserving application portability and gateway interoperability. Protocol mapping is an extension to SDF and described in . API extensions: Extensions compose multiple NIPC operations into a single request or introduce specialized flows optimized for common scenarios (e.g., bulk property updates, conditional reads, firmware operations). Extensions MUST use the “/extensions” path element and SHOULD focus on efficiency, latency reduction, and operational simplicity (fewer round trips, reduced state management). To ensure interoperability and consistent security review, extensions MUST be registered with IANA as defined in .
Protocol mappings NIPC relies on SDF protocol mappings to relate protocol‑neutral affordances to protocol‑specific operations. In BLE and Zigbee are used as examples, however the mapping mechanism is extensible; so support for additional protocols (or versions) can be added without changing the NIPC schema or API.
API extensions The extension APIs allow for extensibility of the APIs. Extension APIs may leverage the basic NIPC defined APIs and combine them in compound statements in order to streamline application operation against devices, make operations more expedient and convenient in one API call. An example of this is the bulk API extension. They may also introduce new functionality that is specific to a use case or protocol, such as the BLE transmit API. Extensions must be defined under the /extensions path element. The extension name is defined as a path parameter after the /extensions path element. Extensions may define their own request and response payloads, as well as their own query parameters. Extensions must be IANA registered as defined in . Extensions MAY implement long‑running operations (e.g., firmware updates, bulk actions). For such operations, the server SHOULD respond with 202 Accepted and a Location header referencing a status URI. Clients MAY poll the status URI (GET) to obtain progress. While the operation is in progress, the status endpoint SHOULD return 200 OK with status information; upon completion, the server MAY redirect with 303 See Other to the final result resource, or return 200 OK with the completed result from the status endpoint. This pattern minimizes client state, supports retry, and provides a uniform mechanism for tracking asynchronous execution. In the appendix , we have defined a few example extensions.
NIPC Error Handling Error types in NIPC APIs must use URI-based error type identifiers as defined in . The error types can be generic or specific to the API category. The error types are organized into the following categories: Generic: Broadly applicable errors, including authorization, invalid identifiers, and generic failures. Property APIs: Errors related to property APIs (read/write). Event APIs: Errors related to event APIs (enable/disable). Protocol specific: Errors related to protocol-specific operations. Extension APIs: Errors related to extension APIs. NIPC error types are defined in the table below: Error Type Description Category invalid-id Invalid device ID or gateway doesn't recognize the ID Generic invalid-sdf-url Invalid SDF URL or SDF affordance not found Generic extension-operation-not-executed Operation was not executed since the previous operation failed Generic sdf-model-already-registered SDF model already registered Generic sdf-model-in-use SDF model in use Generic unsupported-uri-scheme Unsupported URI scheme Generic property-not-readable Property not readable Property APIs property-not-writable Property not writable Property APIs property-read-failed Property read failed Property APIs property-write-failed Property write failed Property APIs event-already-enabled Event already enabled Event APIs event-not-enabled Event not enabled Event APIs event-not-registered Event not registered for any data application Event APIs trigger-already-enabled Trigger already enabled for this event Trigger APIs protocolmap-ble-already-connected Device already connected Protocol specific protocolmap-ble-no-connection No connection found for device Protocol specific protocolmap-ble-connection-timeout BLE connection timeout Protocol specific protocolmap-ble-bonding-failed BLE bonding failed Protocol specific protocolmap-ble-connection-failed BLE connection failed Protocol specific protocolmap-ble-service-discovery-failed BLE service discovery failed Protocol specific protocolmap-ble-invalid-service-or-characteristic Invalid BLE service or characteristic ID Protocol specific protocolmap-zigbee-connection-timeout Zigbee connection timeout Protocol specific protocolmap-zigbee-invalid-endpoint-or-cluster Invalid Zigbee endpoint or cluster ID Protocol specific extension-transmit-invalid-data Invalid transmit data Transmit APIs extension-firmware-rollback Firmware rollback Extension APIs extension-firmware-update-failed Firmware update failed Extension APIs The appropriate HTTP status code is returned in the response.
Publish/Subscribe Interface Events are delivered via a publish/subscribe interface. Event types include: (1) streaming data (enabled/disabled via the NIPC Events API), (2) broadcasts (e.g., advertisements), and (3) connection status (device link up/down). Event payloads are encoded in CBOR and MAY be transported over MQTT, webhook, or websocket. CBOR is used because non‑IP device payloads are typically binary; it encodes such data efficiently and is more compact than JSON, reducing bandwidth.
CDDL Definition The event streaming format is defined here in CDDL . A DataSubscription is a CBOR map containing the raw payload (bytes) and a timestamp (epoch seconds). It MAY include deviceID (the SCIM device identifier) when the payload is associated with a known device. Optional members (e.g., apMacAddress, rssi) MAY be present but can reveal deployment topology and SHOULD be omitted unless required. A choice group within DataSubscription indicates the event type (e.g., advertisement, subscription notification, connection status). An event publication MAY carry one or more DataSubscription entries in an array. Such an array is represented as DataBatch. The subscription type choice uses a CDDL socket ($$subscription-extension) to allow extensibility. New subscription types registered with IANA (see ) can be added using the CDDL plug syntax (//=) without modifying the base schema.
CBOR Examples This section contains a few examples of the DataSubscription struct in CBOR diagnostic notation.
Examples This section contains a few examples on how applications can leverage NIPC operations to communicate with BLE and Zigbee devices.
Property Read/Write In this example, we will connect to a device and read and write from a property. The sequence of operations for this are: Declare a device instance using the SCIM Interface (out of scope of this memo) Register an SDF model for the device
Request Body: JSON object with the SDF model, from Read a property from the BLE device
Write to a property on the BLE device
Enabling an Event on a Device In this example, we will declare a device instance, and setup an advertisement subscription event for that device. The sequence of operations for this are: Declaring a device instance and endpoint app using the SCIM Interface (out of scope of this memo) Register an SDF model for the device
Request Body: JSON object with the SDF model, from Register the data app with the event
Enable the advertisement event
Check the status of the event
Enabling an Event on a Group of Devices In this example, we will enable an advertisement subscription event for a group of devices. The sequence of operations for this are: Provision a device and endpoint app using the SCIM Interface (out of scope of this memo) Register an SDF model for the devices
Request Body: JSON object with the SDF model, from Register the data app with the event
Enable the advertisement event on a group of devices
Check the status of the event
Implementation Status This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in . The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist. According to , "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit".
TieDie IoT Organization: Cisco Systems, North Carolina State University Description: Open-source implementation of the NIPC APIs and gateway functionality for BLE. Client libraries and sample application functions for Python and Java are also provided. Level of maturity: Open-source prototype Coverage: All NIPC APIs for BLE protocol mapping Version compatibility: All versions up to draft-21 Licensing: Apache License, Version 2.0 URL:
Cisco Sensor Connect for IoT Services (Catalyst) Organization: Cisco Systems Description: Commercial solution that delivers advanced BLE capabilities over Cisco Wireless infrastructure. Level of maturity: Production Coverage: All NIPC APIs for BLE protocol mapping Version compatibility: draft-00 Licensing: Proprietary URL:
Cisco Sensor Connect for IoT Services (Meraki) Organization: Cisco Systems Description: Commercial solution that delivers advanced BLE capabilities over Cisco Wireless infrastructure. Level of maturity: Beta Coverage: All NIPC APIs for BLE protocol mapping Version compatibility: draft-21 Licensing: Proprietary
NIPC Prototype Organization: Ericsson Research Description: Prototype implementation in C of the NIPC API. Level of maturity: Research prototype Coverage: Registration and NIPC operations Version compatibility: Draft-04 Licensing: Proprietary Contact: Lorenzo Corneo lorenzo.corneo@ericsson.com
Security Considerations
Payload Encryption Considerations Responses to NIPC operations requests may contain sensitive or confidential information. Therefore, application and device implementations should consider payload encryption. NIPC does not provide any payload encryption mechanism. If payload encryption is required, it MUST be provided by the underlying device protocol (e.g., BLE security modes) or by the transport-layer security mechanism (e.g., TLS).
TLS Support Considerations NIPC MUST run on top of a transport-layer security mechanism such as TLS. When leveraging TLS, the NIPC gateway MUST support TLS 1.2 and TLS 1.3 and MAY support additional transport-layer mechanisms. When using TLS, the client MUST perform a TLS/SSL server identity check, per . Implementation security considerations for TLS can be found in .
HTTP Considerations NIPC runs on top of HTTP and is thus subject to the security considerations of HTTP .
Authorization Considerations
API authorization Considerations To enable NIPC gateway functions, the network administrator MUST authorize applications (e.g., via exchange of tokens or public keys). Authorization MAY be role‑based. The following baseline roles are RECOMMENDED: Provisioning: permitted to create and manage device and endpoint‑app identities via SCIM (typically co‑located with the gateway). Control: permitted to invoke NIPC property, action, and event APIs. Data: permitted to receive streamed event data. Deployments MAY further refine authorization at per‑API or per‑affordance granularity.
Authorization Token/Bearer Token/Cookie Considerations When using authorization tokens such as those issued by OAuth 2.0 , implementers MUST take into account threats and countermeasures as documented in . Since the possession of a bearer token, Authorization token, or cookie MAY authorize the holder to perform NIPC Operations on devices, tokens and cookies MUST contain sufficient entropy to prevent random guessing attack; for example, see and . As with all NIPC communications, bearer tokens and HTTP cookies MUST be exchanged using transport-layer security mechanism such as TLS. Bearer tokens MUST have a limited lifetime that can be determined directly or indirectly (e.g., by checking with a validation service) by the application. By expiring tokens, applications are forced to obtain a new token (which usually involves re-authentication) for continued authorized access. For example, in OAuth 2.0, an application MAY use OAuth token refresh to obtain a new bearer token after authenticating to an authorization server. See . As with bearer tokens, an HTTP cookie SHOULD last no longer than the lifetime of a browser session. An expiry time should be set that limits session cookie lifetime as per . Implementations supporting OAuth bearer tokens need to factor in security considerations of this authorization method . Implementers also need to consider authentication choices coupled with OAuth bearer tokens. For example, when using OAuth bearer tokens with client authentication via client credentials , implementers need to consider the security considerations of client authentication via client credentials as described in .
Other Security Considerations Preventing automated attacks: It is recommended to limit the number of requests that any particular application MAY make in a period of time. Logging and monitoring: It is recommended to log and monitor API usage to detect potential abuse or attacks. Input validation: It is recommended to validate all inputs to prevent injection attacks. Error handling: It is recommended to handle errors gracefully without exposing sensitive information. Least privilege: It is recommended to follow the principle of least privilege when granting access to resources. Storage and handling of sensitive data: Credentials MUST NOT be stored in clear-text, but MUST be stored using an encrypted protection mechanism (e.g., hashing).
IANA Considerations This section provides guidance to the Internet Assigned Numbers Authority (IANA) regarding registration of values related to NIPC, in accordance with .
Media Type Registration IANA is requested to add the following media type to the "Media Types" registry . This document registers the "application/nipc+json" media type for messages of the NIPC APIs defined in this document carrying parameters encoded in JSON. Type name: application Subtype name: nipc+json Required parameters: none Optional parameters: none Encoding considerations: Encoding considerations are identical to those specified for the "application/json" media type. Security considerations: See of this document. Interoperability considerations: none Published specification: This document, the NIPC API specification. Applications that use this media type: Applications implementing NIPC APIs for IoT device management. Fragment identifier considerations: none Additional information: Deprecated alias names for this type: none Magic number(s): none File extension(s): none Macintosh file type code(s): none Person & email address to contact for further information: ASDF WG mailing list (asdf@ietf.org), or IETF Applications and Real-Time Area (art@ietf.org) Intended usage: LIMITED USE Restrictions on usage: To be used for NIPC APIs as defined in this document. Author/Change controller: IETF
Well-known URIs IANA is requested to register the following well-known URI in the "Well-Known URIs" registry as defined by : URI Suffix Change Controller Specification Document nipc IETF This document, The well-known URI for NIPC is:
Registries IANA is requested to create a "Non-Internet-connected Physical Components (NIPC)" registry group, with the registries defined in this section.
API extensions IANA is requested to create a new registry called "NIPC API extensions" in the "Non-Internet-connected Physical Components (NIPC)" registry group. The registration policy for this registry is Specification Required . The registry must contain following attributes: Extension URI Extension name Description Openapi model describing the extension. This model must be reviewed by an expert. Following API extensions are described in this document: Extension URI Extension name Description Model reference /extensions/{id}/bulk Bulk API Call multiple NIPC's in a single request /extensions/{id}/properties/file File write API Write a file with multiple property ops /extensions/{id}/properties/blob Binary write API Write a binary blob with multiple property ops /extensions/{id}/properties/read/conditional Read conditional API Read a property until a condition is fulfilled /extensions/{id}/events/conditional Event conditional API Enable an event until a condition is fulfilled /extensions/{id}/transmit Transmit API Transmits a payload to a device
Data Subscription Types IANA is requested to create a new registry called "NIPC Data Subscription Types" in the "Non-Internet-connected Physical Components (NIPC)" registry group. This registry tracks the subscription types used in the NIPC publish/subscribe interface for streaming event data from devices. Each subscription type defines a specific data format for a particular protocol or use case. The registration policy for this registry is Specification Required . The registry must contain the following attributes: Type Name: The CDDL key name used in the subscription choice Description: A brief description of the subscription type CDDL Definition: Reference to the CDDL structure defining the subscription data Reference: Document defining the subscription type IANA is requested to register the following initial entries: Type Name Description CDDL Definition Reference bleSubscription BLE GATT notification/indication BleSubscription This document bleAdvertisement BLE advertisement data BleAdvertisement This document bleConnectionStatus BLE device connection status changes BleConnectionStatus This document zigbeeSubscription Zigbee attribute report or write event ZigbeeSubscription This document zigbeeConnectionStatus Zigbee device join/leave connection status ZigbeeConnectionStatus This document The CDDL definitions for these subscription types are provided in .
NIPC Protocols IANA is requested to create a new registry called "NIPC Protocols" in the "Non-Internet-connected Physical Components (NIPC)" registry group. This registry tracks the protocols used in the protocolInformation object for NIPC connection management and service discovery operations. Each protocol type defines a specific schema for protocol-specific information, as defined in . The registration policy for this registry is Specification Required . The registry must contain the following attributes: Protocol Name: The key name used in the protocolInformation object Description: A brief description of the protocol type Reference: Document defining the protocol type IANA is requested to register the following initial entries: Protocol Name Description Reference ble Bluetooth Low Energy This document zigbee Zigbee This document
Problem Details for NIPC APIs IANA is requested to create a new registry, the "NIPC Problem Type" registry, with following URL: . The registration policy for this registry is Specification Required . Registrations MUST use the prefix "" for the type URI. The registration requests MUST use the template defined in . IANA is requested to register the following URIs in the "NIPC Problem Type" registry: Problem Type URI Description Reference https://www.iana.org/assignments/nipc-problem-types#invalid-id Invalid device ID or gateway doesn't recognize the ID This document https://www.iana.org/assignments/nipc-problem-types#invalid-sdf-url Invalid SDF URL or SDF affordance not found This document https://www.iana.org/assignments/nipc-problem-types#extension-operation-not-executed Operation was not executed since the previous operation failed This document https://www.iana.org/assignments/nipc-problem-types#sdf-model-already-registered SDF model already registered This document https://www.iana.org/assignments/nipc-problem-types#sdf-model-in-use SDF model in use This document https://www.iana.org/assignments/nipc-problem-types#unsupported-uri-scheme Unsupported URI scheme This document https://www.iana.org/assignments/nipc-problem-types#property-not-readable Property not readable This document https://www.iana.org/assignments/nipc-problem-types#property-read-failed Property read failed This document https://www.iana.org/assignments/nipc-problem-types#property-not-writable Property not writable This document https://www.iana.org/assignments/nipc-problem-types#property-write-failed Property write failed This document https://www.iana.org/assignments/nipc-problem-types#event-already-enabled Event already enabled This document https://www.iana.org/assignments/nipc-problem-types#event-not-enabled Event not enabled This document https://www.iana.org/assignments/nipc-problem-types#event-not-registered Event not registered for any data application This document https://www.iana.org/assignments/nipc-problem-types#trigger-already-enabled Trigger already enabled for this event This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-already-connected Device already connected This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-no-connection No connection found for device This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-connection-timeout BLE connection timeout This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-bonding-failed BLE bonding failed This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-connection-failed BLE connection failed This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-service-discovery-failed BLE service discovery failed This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-invalid-service-or-characteristic Invalid BLE service or characteristic ID This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-zigbee-connection-timeout Zigbee connection timeout This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-zigbee-invalid-endpoint-or-cluster Invalid Zigbee endpoint or cluster ID This document https://www.iana.org/assignments/nipc-problem-types#extension-transmit-invalid-data Invalid transmit data This document https://www.iana.org/assignments/nipc-problem-types#extension-firmware-rollback Firmware rollback This document https://www.iana.org/assignments/nipc-problem-types#extension-firmware-update-failed Firmware update failed This document Each Problem Type URI is intended for use as the "type" member in Problem Details responses as described.
Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. Semantic Definition Format (SDF) for Data and Interactions of Things The Semantic Definition Format (SDF) is a format for domain experts to use in the creation and maintenance of data and interaction models that describe Things, i.e., physical objects that are available for interaction over a network. An SDF specification describes definitions of SDF Objects/SDF Things and their associated interactions (Events, Actions, and Properties), as well as the Data types for the information exchanged in those interactions. Tools convert this format to database formats and other serializations as needed. Device Schema Extensions to the System for Cross-Domain Identity Management (SCIM) Model The initial core schema for the System for Cross-domain Identity Management (SCIM) was designed for provisioning users. This memo specifies schema extensions that enable provisioning of devices using various underlying bootstrapping systems such as Wi-Fi Easy Connect, FIDO device onboarding vouchers, Bluetooth Low Energy (BLE) passcodes, and MAC Authenticated Bypass (MAB). SDF Protocol Mapping Cisco Systems Cisco Systems Ericsson This document defines protocol mapping extensions for the Semantic Definition Format (SDF) to enable mapping of protocol-agnostic SDF affordances to protocol-specific operations. The protocol mapping mechanism allows SDF models to specify how properties, actions, and events should be accessed using a specific protocol. This document defines protocol mappings for Bluetooth Low Energy and Zigbee, and the mechanism can be extended to other protocols such as HTTP and CoAP. This document also describes a method to extend SCIM with an SDF model mapping. System for Cross-domain Identity Management: Protocol The System for Cross-domain Identity Management (SCIM) specification is an HTTP-based protocol that makes managing identities in multi-domain scenarios easier to support via a standardized service. Examples include, but are not limited to, enterprise-to-cloud service providers and inter-cloud scenarios. The specification suite seeks to build upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models. SCIM's intent is to reduce the cost and complexity of user management operations by providing a common user schema, an extension model, and a service protocol defined by this document. The JavaScript Object Notation (JSON) Data Interchange Format JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. Concise Binary Object Representation (CBOR) The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. System for Cross-domain Identity Management: Core Schema The System for Cross-domain Identity Management (SCIM) specifications are designed to make identity management in cloud-based applications and services easier. The specification suite builds upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models. Its intent is to reduce the cost and complexity of user management operations by providing a common user schema and extension model as well as binding documents to provide patterns for exchanging this schema using HTTP. This document provides a platform-neutral schema and extension model for representing users and groups and other resource types in JSON format. This schema is intended for exchange and use with cloud service providers. HTTP Semantics The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. Problem Details for HTTP APIs This document defines a "problem detail" to carry machine-readable details of errors in HTTP response content to avoid the need to define new error response formats for HTTP APIs. This document obsoletes RFC 7807. The Base16, Base32, and Base64 Data Encodings This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] Uniform Resource Identifier (URI): Generic Syntax A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] URI Template A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. [STANDARDS-TRACK] Universally Unique IDentifiers (UUIDs) This specification defines UUIDs (Universally Unique IDentifiers) -- also known as GUIDs (Globally Unique IDentifiers) -- and a Uniform Resource Name namespace for UUIDs. A UUID is 128 bits long and is intended to guarantee uniqueness across space and time. UUIDs were originally used in the Apollo Network Computing System (NCS), later in the Open Software Foundation's (OSF's) Distributed Computing Environment (DCE), and then in Microsoft Windows platforms. This specification is derived from the OSF DCE specification with the kind permission of the OSF (now known as "The Open Group"). Information from earlier versions of the OSF DCE specification have been incorporated into this document. This document obsoletes RFC 4122. Textual Encodings of PKIX, PKCS, and CMS Structures This document describes and discusses the textual encodings of the Public-Key Infrastructure X.509 (PKIX), Public-Key Cryptography Standards (PKCS), and Cryptographic Message Syntax (CMS). The textual encodings are well-known, are implemented by several applications and libraries, and are widely deployed. This document articulates the de facto rules by which existing implementations operate and defines them so that future implementations can interoperate. The Transport Layer Security (TLS) Protocol Version 1.2 This document specifies Version 1.2 of the Transport Layer Security (TLS) protocol. The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. [STANDARDS-TRACK] The Transport Layer Security (TLS) Protocol Version 1.3 This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations. Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS) Many application technologies enable secure communication between two entities by means of Internet Public Key Infrastructure Using X.509 (PKIX) certificates in the context of Transport Layer Security (TLS). This document specifies procedures for representing and verifying the identity of application services in such interactions. [STANDARDS-TRACK] Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are widely used to protect data exchanged over application protocols such as HTTP, SMTP, IMAP, POP, SIP, and XMPP. Over the last few years, several serious attacks on TLS have emerged, including attacks on its most commonly used cipher suites and their modes of operation. This document provides recommendations for improving the security of deployed services that use TLS and DTLS. The recommendations are applicable to the majority of use cases. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations. The OAuth 2.0 Authorization Framework The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants This specification provides a framework for the use of assertions with OAuth 2.0 in the form of a new client authentication mechanism and a new authorization grant type. Mechanisms are specified for transporting assertions during interactions with a token endpoint; general processing rules are also specified. The intent of this specification is to provide a common framework for OAuth 2.0 to interwork with other identity systems using assertions and to provide alternative client authentication mechanisms. Note that this specification only defines abstract message flows and processing rules. In order to be implementable, companion specifications are necessary to provide the corresponding concrete instantiations. The OAuth 2.0 Authorization Framework: Bearer Token Usage This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] OAuth 2.0 Threat Model and Security Considerations This document gives additional security considerations for OAuth, beyond those in the OAuth 2.0 specification, based on a comprehensive threat model for the OAuth 2.0 protocol. This document is not an Internet Standards Track specification; it is published for informational purposes. HTTP State Management Mechanism This document defines the HTTP Cookie and Set-Cookie header fields. These header fields can be used by HTTP servers to store state (called cookies) at HTTP user agents, letting the servers maintain a stateful session over the mostly stateless HTTP protocol. Although cookies have many historical infelicities that degrade their security and privacy, the Cookie and Set-Cookie header fields are widely used on the Internet. This document obsoletes RFC 2965. [STANDARDS-TRACK] Guidelines for Writing an IANA Considerations Section in RFCs Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. Media Types IANA Well-Known URIs IANA Well-Known Uniform Resource Identifiers (URIs) This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. Bluetooth Core Specification, Version 5.3 Bluetooth SIG Zigbee Specification, Version 22 1.0 Connectivity Standards Alliance A RESTful API used to access data in devices using the functionality defined in the Bluetooth GATT profile Bluetooth SIG The Constrained Application Protocol (CoAP) The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. Improving Awareness of Running Code: The Implementation Status Section This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice.
OpenAPI definition The following non-normative model is provided for convenience of the implementer.
file "openapi.yml" =============== NOTE: '\' line wrapping per RFC 8792 ================ # yaml-language-server: $schema=https://json-schema.org/draft/2020-\ 12/schema openapi: 3.0.3 info: title: Non IP Device Control (NIPC) API description: |- This API specifies RESTful application layer interface for gateways providing operations against non-IP devices. The described interface is extensible. The examples includes leverage Bluetooth Low Energy and Zigbee as they are commonly deployed. termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.21.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ servers: - url: "{gw_host}/nipc/draft-21" variables: gw_host: default: localhost description: Gateway Host tags: - name: NIPC property APIs description: |- APIs that allow apps to get and update device properties. If the underlying protocol requires connection management, it will be performed as part of the API call. - name: NIPC event APIs description: |- APIs that allow apps to enable or disable event reporting on devices. If the underlying protocol requires connection management, it will be performed as part of the API call. - name: NIPC action APIs description: |- APIs that perform actions on devices or groups. - name: NIPC trigger APIs description: |- APIs that install triggers on actions and events for devices or groups. A trigger always triggers an action. - name: NIPC management APIs description: |- APIs that manage device connections. - name: NIPC registration APIs description: |- APIs that register sdf models or data applications paths: ### NIPC Property APIs /devices/{id}/properties: put: tags: - NIPC property APIs summary: Update a value of one or more properties on a device description: |- Write a value to a property or multiple properties to a device. If underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: UpdateProperties parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: propertyName in: query description: |- The SDF property name that needs to be written to. required: false allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ thermostat/sdfProperty/temperature" requestBody: description: |- The value to be written to the property or properties. If multiple properties are specified, the request body should be application/nipc+json. content: application/nipc+json: schema: $ref: '#/components/schemas/PropertyValueArray' "*/*": schema: description: |- Any other content type, such as application/octet-stream, application/json that will be written to the device. required: true responses: '204': description: |- Success, no content, used for a single property write '200': description: Success, used for multiple property writes content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/\ PropertyValueResponseArray' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC property APIs summary: |- Read a value from one or multiple properties on a device description: |- Read a value to a property or multiple properties from a device. If underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: GetProperties parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: propertyName in: query description: Properties to be read required: true allowReserved: true schema: type: array items: type: string example: "https://example.com/heartrate#/sdfObject/\ thermostat/sdfProperty/temperature" responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/Id' - $ref: '#/components/schemas/\ PropertyValueReadResponseArray' "*/*": schema: type: string description: |- Any other content type, such as application/octet-stream, application/json that will be read from the device. default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' ### NIPC Event APIs /devices/{id}/events: post: tags: - NIPC event APIs summary: Enable an event on a specific device description: |- Enable an event on a specific device or for a group of devices. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: EnableEvent parameters: - name: id in: path description: The ID of the device. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: eventName in: query description: event that needs to be enabled required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor/sdfEvent/fallDetected" responses: '201': description: Success headers: Location: description: Location of the created event schema: type: string format: uri example: "/devices/{id}/events?instanceId={\ instanceId}" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC event APIs summary: Disable an event on a specific device description: |- Disable an event on a specific device or a group of devices. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: DisableEvent parameters: - name: id in: path description: The ID of the device. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: instanceId in: query description: instance id of the event that needs to be \ disabled required: true schema: type: string format: uuid example: 02ee282c-8915-4b2e-bbd2-88966773134a responses: '204': description: Success, no content default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC event APIs summary: Get status of events on a device description: |- Get status of an event or multiple events on a specific \ device operationId: GetEvents parameters: - name: id in: path description: The ID of the device. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: instanceId in: query description: |- Instance ID of the events that need to be filtered required: false schema: type: array items: type: string format: uuid example: 02ee282c-8915-4b2e-bbd2-88966773134a responses: '200': description: Success content: application/nipc+json: schema: $ref: '#/components/schemas/EventStatusResponseArray' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' /groups/{id}/events: post: tags: - NIPC event APIs summary: Enable an event on a group of devices description: |- Enable an event on a group of devices. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: EnableGroupEvent parameters: - name: id in: path description: |- group id for which the event needs to be enabled required: true schema: type: string format: uuid example: 0dc729d7-f6c3-491d-9b9d-e7176d2be243 - name: eventName in: query description: event that needs to be enabled required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor/sdfEvent/fallDetected" responses: '201': description: Success, event enabled headers: Location: description: Location of the created event schema: type: string format: uri example: "/groups/{id}/events?instanceId={instanceId\ }" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC event APIs summary: Disable an event on a group of devices description: |- Disable an event on a group of devices. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: DisableGroupEvent parameters: - name: id in: path description: |- group id for which the event needs to be disabled required: true schema: type: string format: uuid example: 0dc729d7-f6c3-491d-9b9d-e7176d2be243 - name: instanceId in: query description: instance id of the event that needs to be \ disabled required: true schema: type: string format: uuid example: f1b9f26b-21ce-4deb-9d57-289ba7e17cce responses: '200': description: Success, event disabled content: application/nipc+json: schema: $ref: '#/components/schemas/\ GroupEventStatusResponseArray' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC event APIs summary: Get status of events on a group of devices description: |- Get status of an event or multiple events on a group of \ devices. operationId: GetGroupEvents parameters: - name: id in: path description: group id of the SCIM group required: true schema: type: string format: uuid example: 0dc729d7-f6c3-491d-9b9d-e7176d2be243 - name: instanceId in: query description: |- Instance IDs of the events that need to be filtered required: false schema: type: string format: uuid example: f1b9f26b-21ce-4deb-9d57-289ba7e17cce responses: '200': description: Success, events retrieved content: application/nipc+json: schema: $ref: '#/components/schemas/\ GroupEventStatusResponseArray' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' ### NIPC action APIs /devices/{id}/actions: post: tags: - NIPC action APIs summary: Perform an action on a device description: |- Perform an action on a device. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: ActionProperty parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: actionName in: query description: action that needs to be performed required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor/sdfAction/start" requestBody: content: application/octet-stream: schema: type: string format: binary required: false responses: '202': description: Accepted, action is being performed headers: Location: description: Location of the action schema: type: string format: uri example: "/devices/{id}/actions?instanceId={\ instanceId}" Retry-After: description: |- Number of seconds to wait before polling the status \ endpoint again schema: type: integer example: 5 default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC action APIs summary: Get status of an action on a device description: |- Get status of an action on a specific device or a group of devices. Success is action is active, failure if action not active. operationId: GetAction parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: instanceId in: query description: |- instance id of the action that needs to be checked required: true schema: type: string format: uuid example: 02ee282c-8915-4b2e-bbd2-88966773134a responses: '200': description: Success, action is active content: application/nipc+json: schema: $ref: '#/components/schemas/ActionResponse' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' /groups/{id}/actions: post: tags: - NIPC action APIs summary: Perform an action on a group description: |- Perform an action on a group of decvices If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: ActionGroupProperty parameters: - name: id in: path description: The ID of the group. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: actionName in: query description: action that needs to be performed required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor/sdfAction/start" requestBody: content: application/octet-stream: schema: type: string format: binary required: false responses: '202': description: Accepted, action is being performed headers: Location: description: Location of the action schema: type: string format: uri example: "/groups/{id}/actions?instanceId={\ instanceId}" Retry-After: description: |- Number of seconds to wait before polling the status \ endpoint again schema: type: integer example: 5 default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC action APIs summary: Get status of an action on a group description: |- Get status of an action on a specific group of devices. Success is action is active, failure if action not active. operationId: GetGroupAction parameters: - name: id in: path description: The ID of the group of devices. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: instanceId in: query description: |- instance id of the action that needs to be checked required: true schema: type: string format: uuid example: 02ee282c-8915-4b2e-bbd2-88966773134a responses: '200': description: Success, action is active content: application/nipc+json: schema: $ref: '#/components/schemas/\ GroupActionStatusResponseArray' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' ### NIPC Trigger APIs /devices/{id}/triggers: post: tags: - NIPC trigger APIs summary: create a trigger on an affordance of a device description: |- Creates a trigger on an affordance of a device. A trigger will trigger an action on another device or a group of \ devices operationId: CreateDeviceTrigger parameters: - name: id in: path description: The ID of the device. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: eventName in: query description: |- The SDF global name of the event that will trigger this \ action required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor/sdfEvent/fallDetected" requestBody: description: |- The NIPC API call to be called when the trigger is executed. content: application/nipc+json: schema: $ref: '#/components/schemas/Action' required: true responses: '201': description: Success headers: Location: description: Location of the created trigger schema: type: string format: uri example: "/devices/{id}/triggers?instanceId={\ instanceId}" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC trigger APIs summary: Get information about a trigger or all triggers description: |- Get information about a trigger for a device or all triggers if none specified operationId: GetDeviceTrigger parameters: - name: id in: path description: The ID of the device. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: instanceId in: query description: |- instance id of the trigger that needs to be checked required: false schema: type: string format: uuid example: 02ee282c-8915-4b2e-bbd2-88966773134a responses: '200': description: Success, action is active content: application/nipc+json: schema: $ref: '#/components/schemas/\ TriggerStatusResponseArray' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC trigger APIs summary: Delete a trigger or all triggers for a device description: |- Delete a trigger for a device or all triggers if none specified operationId: DeleteDeviceTrigger parameters: - name: id in: path description: The ID of the device. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: instanceId in: query description: |- instance id of the trigger that needs to be checked required: false schema: type: string format: uuid example: 02ee282c-8915-4b2e-bbd2-88966773134a responses: '204': description: Success, no content default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' /groups/{id}/triggers: post: tags: - NIPC trigger APIs summary: create a trigger on an affordance of a group description: |- Creates a trigger on an affordance of a group of devices. A \ trigger will trigger an action on a device or a group of devices operationId: CreateGroupTrigger parameters: - name: id in: path description: The ID of the group required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: eventName in: query description: |- The SDF global name of the event that will trigger this \ action required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor/sdfEvent/fallDetected" requestBody: description: |- The NIPC API call to be called when the trigger is executed, as well as the device or group it is to be \ executed against. content: application/nipc+json: schema: $ref: '#/components/schemas/Action' required: true responses: '201': description: Success headers: Location: description: Location of the created trigger schema: type: string format: uri example: "/groups/{id}/triggers?instanceId={\ instanceId}" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC trigger APIs summary: Get information about a trigger or all triggers description: |- Get information about a trigger or all triggers if none specified operationId: GetGroupTrigger parameters: - name: id in: path description: The ID of the group required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: instanceId in: query description: |- instance id of the trigger that needs to be checked required: false schema: type: string format: uuid example: 02ee282c-8915-4b2e-bbd2-88966773134a responses: '200': description: Success, action is active content: application/nipc+json: schema: $ref: '#/components/schemas/\ GroupTriggerStatusResponseArray' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC trigger APIs summary: Delete a trigger or all triggers for a grou of devices description: |- Delete a trigger for a group of devices or all triggers for a group of devices if none specified operationId: DeleteGroupTrigger parameters: - name: id in: path description: The ID of the group of devices. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 - name: instanceId in: query description: |- instance id of the trigger that needs to be checked required: false schema: type: string format: uuid example: 02ee282c-8915-4b2e-bbd2-88966773134a responses: '204': description: Success, no content default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' ### NIPC management APIs /devices/{id}/connections: post: tags: - NIPC management APIs summary: Connect a device description: |- Connect a device. 3 retries by default, optionally retry policy can be defined in the API body. If the protocol requires service discovery, full service discovery will be performed, unless specific services are described in the API body. operationId: ActionCreateConnection parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 requestBody: content: application/nipc+json: schema: anyOf: - $ref: '#/components/schemas/Connection' - $ref: './protocolinfo/ProtocolInfo.yaml#/\ components/schemas/ProtocolInfo-ServiceMap' example: retries: 3 protocolInformation: ble: services: - serviceID: "00001809-0000-1000-8000-\ 00805f9b34fb" cached: true cacheExpiryDuration: 3600 required: false responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/Id' - $ref: './protocolinfo/ProtocolInfo.yaml#/\ components/schemas/ProtocolInfo-ServiceMap' example: id: "1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30" protocolInformation: ble: services: - serviceID: "00001809-0000-1000-8000-\ 00805f9b34fb" characteristics: - characteristicID: "00002a19-0000-1000-\ 8000-00805f9b34fb" flags: ["read", "notify"] descriptors: - descriptorID: "00002902-0000-1000-\ 8000-00805f9b34fb" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' put: tags: - NIPC management APIs summary: Update cached ServiceMap for a device. description: |- Update cached ServiceMap for a device. Full service discovery will be performed, unless specific services are described in the API body. operationId: ActionUpdateServiceMap parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 requestBody: content: application/nipc+json: schema: $ref: './protocolinfo/ProtocolInfo.yaml#/components/\ schemas/ProtocolInfo-ServiceMap' example: retries: 3 protocolInformation: ble: services: - serviceID: "00001809-0000-1000-8000-\ 00805f9b34fb" cached: true cacheExpiryDuration: 3600 required: false responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/Id' - $ref: './protocolinfo/ProtocolInfo.yaml#/\ components/schemas/ProtocolInfo-ServiceMap' example: id: "1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30" protocolInformation: ble: services: - serviceID: "00001809-0000-1000-8000-\ 00805f9b34fb" characteristics: - characteristicID: "00002a19-0000-1000-\ 8000-00805f9b34fb" flags: ["read", "notify"] descriptors: - descriptorID: "00002902-0000-1000-\ 8000-00805f9b34fb" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC management APIs summary: Disconnect a device description: |- Disconnect a device. operationId: ActionDeleteConnection parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 responses: '204': description: Success, no content default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC management APIs summary: Get connection state for a device description: |- Get connection status for a device. Success when device(s) is/are connected, includes service map for the device if available. Failure when a device is not connected operationId: ActionGetConnection parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/Id' - $ref: './protocolinfo/ProtocolInfo.yaml#/\ components/schemas/ProtocolInfo-ServiceMap' example: id: "1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30" protocolInformation: ble: services: - serviceID: "00001809-0000-1000-8000-\ 00805f9b34fb" characteristics: - characteristicID: "00002a19-0000-1000-\ 8000-00805f9b34fb" flags: ["read", "notify"] descriptors: - descriptorID: "00002902-0000-1000-\ 8000-00805f9b34fb" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' ### Registrations /registrations/models: post: tags: - NIPC registration APIs summary: Register an sdfObject description: |- Register an sdfObject, including Properties, Events and actions operationId: registerSdfObject requestBody: content: application/sdf+json: schema: $ref: '#/components/schemas/SdfModel' required: true responses: '201': description: Created content: application/nipc+json: schema: type: array items: allOf: - $ref: '#/components/schemas/SdfReference' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC registration APIs summary: Get registered SDF models description: |- Without sdfName, returns a list of all registered SDF model references. With sdfName, returns the full SDF model for that name. operationId: getSdfRefs parameters: - name: sdfName in: query description: |- sdfName can be a reference to an sdfThing or sdfObject. If omitted, all registered model references are returned. required: false allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor" responses: '200': description: |- Without sdfName, returns a list of SDF model references. With sdfName, returns the full SDF model. content: application/sdf+json: schema: oneOf: - type: array items: $ref: '#/components/schemas/SdfReference' - $ref: '#/components/schemas/SdfModel' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' put: tags: - NIPC registration APIs summary: Update an SDF model description: |- Update an SDF model, including Properties, Events and actions operationId: updateSdf parameters: - name: sdfName in: query description: |- sdfName can be a reference to an sdfThing or sdfObject required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor" requestBody: content: application/sdf+json: schema: $ref: '#/components/schemas/SdfModel' required: true responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/SdfReference' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC registration APIs summary: Delete an sdfObject description: |- Delete an sdfObject, including Properties, Events and actions operationId: deleteSdfObject parameters: - name: sdfName in: query description: sdfObject name required: true schema: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor" responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/SdfReference' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' /registrations/data-apps: post: tags: - NIPC registration APIs summary: Register a dataApp description: |- Register a dataApp that is able to receive device data. operationId: registerDataApp parameters: - name: dataAppId in: query description: id of the data app that will be registered required: true schema: type: string format: uuid example: 0927ce7c-b258-4bfa-a345-bcc9f74385b4 requestBody: content: application/nipc+json: schema: $ref: '#/components/schemas/DataApp' required: true responses: '201': description: Created content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/DataApp' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' put: tags: - NIPC registration APIs summary: Update registration of a dataApp description: |- Update registration of a dataApp that is able to receive \ device data. operationId: UpdateDataApp parameters: - name: dataAppId in: query description: id of the data app that will be updated required: true schema: type: string format: uuid example: 0927ce7c-b258-4bfa-a345-bcc9f74385b4 requestBody: content: application/nipc+json: schema: $ref: '#/components/schemas/DataApp' required: true responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/DataApp' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC registration APIs summary: Delete registration of a dataApp description: |- Delete registration of a dataApp that is able to receive device data. operationId: DeleteDataApp parameters: - name: dataAppId in: query description: id of the data app that will be updated required: true schema: type: string format: uuid example: 0927ce7c-b258-4bfa-a345-bcc9f74385b4 responses: '204': description: Success, no content default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC registration APIs summary: Get registration of a dataApp description: |- Get registrationdetails of a dataApp that is able to receive device data. operationId: GetDataApp parameters: - name: dataAppId in: query description: id of the data app that will be updated required: true schema: type: string format: uuid example: 0927ce7c-b258-4bfa-a345-bcc9f74385b4 responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/DataApp' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' components: schemas: # Base objects ## A SCIM id, can be a device or a group Id: required: - id type: object properties: id: type: string format: uuid description: |- A SCIM-generated UUID, can be a device or group example: 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 ## A property Property: required: - property type: object properties: property: type: string example: "https://example.com/heartrate#/sdfObject/\ thermostat/sdfProperty/temperature" ## A value Value: required: - value type: object properties: value: type: string format: byte example: dGVzdA== ## A value of an property of an Device PropertyValue: allOf: - $ref: '#/components/schemas/Property' - $ref: '#/components/schemas/Value' ## An array of Property values PropertyValueArray: type: array items: $ref: '#/components/schemas/PropertyValue' ## Event Event: required: - event type: object properties: event: type: string description: |- percent-encoded JSON pointer to the SDF event object example: https://example.com/heartrate#/sdfObject/\ healthsensor/sdfEvent/fallDetected InstanceId: type: object properties: instanceId: type: string format: uuid description: |- A SCIM-generated UUID for the event instance example: 02ee282c-8915-4b2e-bbd2-88966773134a ## An Action Action: type: object properties: action: type: string description: |- NIPC action operation to execute example: /devices/3171ec43-42a5-4415-ab4b-afd0dfbe9615/\ actions?actionName=https%3A%2F%2Fexample.com%2FAlarmSystem%23%\ 2FsdfObject%2Fbell%2FsdfAction%2Fring ## A Connection Connection: type: object properties: retries: type: integer format: int32 example: 3 ## DataApp DataApp: oneOf: - $ref: '#/components/schemas/DataAppMqttClient' - $ref: '#/components/schemas/DataAppMqttBroker' - $ref: '#/components/schemas/DataAppWebhook' - $ref: '#/components/schemas/DataAppWebsocket' type: object properties: events: type: array items: $ref: '#/components/schemas/Event' DataAppMqttClient: type: object properties: mqttClient: type: boolean DataAppMqttBroker: type: object properties: mqttBroker: type: object required: - URI - username - password properties: URI: type: string example: mqtt.broker.com:8883 username: type: string example: user1 password: type: string example: password1 brokerCACert: description: PEM encoded CA certificate type: string customTopic: type: string description: custom MQTT topic to publish to example: custom/topic DataAppWebhook: type: object properties: webhook: type: object properties: URI: type: string example: webhook.com:443 headers: type: object additionalProperties: type: string example: x-api-key: fjelk-3dl33f-2wdsd serverCACert: type: string DataAppWebsocket: type: object properties: websocket: type: object properties: URI: type: string example: websocket.com:443 headers: type: object additionalProperties: type: string example: x-api-key: fjelk-3dl33f-2wdsd serverCACert: type: string ## sdfObject registration definition SdfReference: type: object description: SDF URL referring to the sdfobject properties: sdfName: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor" ## Event name reference for triggers EventNameReference: type: object description: SDF global name of the event associated with a \ trigger properties: eventName: type: string example: "https://example.com/heartrate#/sdfObject/\ healthsensor/sdfEvent/fallDetected" SdfModel: allOf: - type: object description: Sample SDF model properties: namespace: type: object additionalProperties: type: string example: heartrate: https://example.com/heartrate defaultNamespace: type: string example: heartrate - oneOf: - $ref: '#/components/schemas/SdfThing' - $ref: '#/components/schemas/SdfObject' SdfThing: type: object description: Sample SDF thing properties: sdfThing: additionalProperties: anyOf: - $ref: '#/components/schemas/SdfProperty' - $ref: '#/components/schemas/SdfEvent' - $ref: '#/components/schemas/SdfAction' - $ref: '#/components/schemas/SdfObject' example: multipleSensor: sdfEvent: isPresent: sdfProtocolMap: ble: type: advertisement sdfObject: healthsensor: sdfProperty: heartrate: sdfProtocolMap: ble: serviceID: 00001809-0000-1000-8000-\ 00805f9b34fb characteristicID: 00002a1c-0000-1000-8000-\ 00805f9b34fb sdfEvent: fallDetected: sdfProtocolMap: ble: serviceID: 00001809-0000-1000-8000-\ 00805f9b34fb characteristicID: 00002a1c-0000-1000-\ 8000-00805f9b34fb sdfAction: start: sdfProtocolMap: ble: serviceID: 00001809-0000-1000-8000-\ 00805f9b34fb characteristicID: 00002a1c-0000-1000-8000-\ 00805f9b34fb SdfObject: type: object description: Sample SDF object properties: sdfObject: additionalProperties: anyOf: - $ref: '#/components/schemas/SdfProperty' - $ref: '#/components/schemas/SdfEvent' - $ref: '#/components/schemas/SdfAction' example: healthsensor: sdfProperty: heartrate: sdfProtocolMap: ble: serviceID: 00001809-0000-1000-8000-00805f9b34fb characteristicID: 00002a1c-0000-1000-8000-\ 00805f9b34fb sdfEvent: fallDetected: sdfProtocolMap: ble: type: advertisements sdfAction: start: sdfProtocolMap: ble: serviceID: 00001809-0000-1000-8000-00805f9b34fb characteristicID: 00002a1c-0000-1000-8000-\ 00805f9b34fb SdfProperty: type: object description: Sample SDF property properties: sdfProperty: additionalProperties: allOf: - $ref: './protocolmaps/ProtocolMap.yaml#/components/\ schemas/ProtocolMap' example: heartrate: sdfProtocolMap: ble: serviceID: 00001809-0000-1000-8000-00805f9b34fb characteristicID: 00002a1c-0000-1000-8000-\ 00805f9b34fb SdfEvent: type: object description: Sample SDF event properties: sdfEvent: additionalProperties: #example, this will be the \ registered event allOf: - $ref: './protocolmaps/ProtocolMap.yaml#/components/\ schemas/ProtocolMap' example: fallDetected: sdfProtocolMap: ble: type: gatt serviceID: 00001809-0000-1000-8000-00805f9b34fb characteristicID: 00002a1c-0000-1000-8000-\ 00805f9b34fb SdfAction: type: object description: Sample SDF action properties: sdfAction: additionalProperties: allOf: - $ref: './protocolmaps/ProtocolMap.yaml#/components/\ schemas/ProtocolMap' example: start: sdfProtocolMap: ble: serviceID: 00001809-0000-1000-8000-00805f9b34fb characteristicID: 00002a1c-0000-1000-8000-\ 00805f9b34fb # responses SuccessResponse: type: object properties: status: type: integer format: int32 example: 200 description: HTTP status code ## Error 500 application Failure response FailureResponse: type: object properties: type: type: string description: URI to the error type enum: - https://www.iana.org/assignments/nipc-problem-types#\ invalid-id - https://www.iana.org/assignments/nipc-problem-types#\ invalid-sdf-url - https://www.iana.org/assignments/nipc-problem-types#\ extension-operation-not-executed - https://www.iana.org/assignments/nipc-problem-types#\ sdf-model-already-registered - https://www.iana.org/assignments/nipc-problem-types#\ sdf-model-in-use - https://www.iana.org/assignments/nipc-problem-types#\ unsupported-uri-scheme - https://www.iana.org/assignments/nipc-problem-types#\ property-not-readable - https://www.iana.org/assignments/nipc-problem-types#\ property-read-failed - https://www.iana.org/assignments/nipc-problem-types#\ property-not-writable - https://www.iana.org/assignments/nipc-problem-types#\ property-write-failed - https://www.iana.org/assignments/nipc-problem-types#\ event-already-enabled - https://www.iana.org/assignments/nipc-problem-types#\ event-not-enabled - https://www.iana.org/assignments/nipc-problem-types#\ event-not-registered - https://www.iana.org/assignments/nipc-problem-types#\ trigger-already-enabled - https://www.iana.org/assignments/nipc-problem-types#\ protocolmap-ble-already-connected - https://www.iana.org/assignments/nipc-problem-types#\ protocolmap-ble-no-connection - https://www.iana.org/assignments/nipc-problem-types#\ protocolmap-ble-connection-timeout - https://www.iana.org/assignments/nipc-problem-types#\ protocolmap-ble-bonding-failed - https://www.iana.org/assignments/nipc-problem-types#\ protocolmap-ble-connection-failed - https://www.iana.org/assignments/nipc-problem-types#\ protocolmap-ble-service-discovery-failed - https://www.iana.org/assignments/nipc-problem-types#\ protocolmap-ble-invalid-service-or-characteristic - https://www.iana.org/assignments/nipc-problem-types#\ protocolmap-zigbee-connection-timeout - https://www.iana.org/assignments/nipc-problem-types#\ protocolmap-zigbee-invalid-endpoint-or-cluster - https://www.iana.org/assignments/nipc-problem-types#\ extension-transmit-invalid-data - https://www.iana.org/assignments/nipc-problem-types#\ extension-firmware-rollback - https://www.iana.org/assignments/nipc-problem-types#\ extension-firmware-update-failed - about:blank status: type: integer format: int32 example: 400 description: HTTP status code title: type: string example: Invalid Device ID description: Human-readable error title detail: type: string example: |- Device ID 1d3b2c36-8a65-45a6-87c1-bcdbe0a32e30 does not exist or is not a device description: Human-readable error message ## Property operations responses PropertyValueResponseArrayItem: oneOf: - $ref: '#/components/schemas/SuccessResponse' - $ref: '#/components/schemas/FailureResponse' PropertyValueResponseArray: type: array items: $ref: '#/components/schemas/PropertyValueResponseArrayItem' PropertyValueReadResponseArrayItem: oneOf: - $ref: '#/components/schemas/PropertyValue' - $ref: '#/components/schemas/FailureResponse' PropertyValueReadResponseArray: type: array items: allOf: - $ref: '#/components/schemas/\ PropertyValueReadResponseArrayItem' ## Event operations responses EventStatusResponseArrayItem: oneOf: - allOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/InstanceId' - $ref: '#/components/schemas/FailureResponse' EventStatusResponseArray: type: array items: $ref: '#/components/schemas/EventStatusResponseArrayItem' GroupEventStatusResponse: type: object oneOf: - allOf: - $ref: '#/components/schemas/Event' - type: object properties: deviceId: type: string format: uuid example: 0dc729d7-f6c3-491d-9b9d-e7176d2be243 - allOf: - $ref: '#/components/schemas/FailureResponse' - type: object properties: deviceId: type: string format: uuid example: 9171ec16-e3c1-4ccf-ad23-b92a1a3f069d GroupEventStatusResponseArray: type: array items: $ref: '#/components/schemas/GroupEventStatusResponse' ActionResponse: required: - status type: object properties: status: type: string enum: - IN_PROGRESS - COMPLETED example: COMPLETED description: |- Status of the action, can be IN_PROGRESS or COMPLETED GroupActiontStatusResponse: type: object oneOf: - allOf: - $ref: '#/components/schemas/ActionResponse' - type: object properties: deviceId: type: string format: uuid example: 0dc729d7-f6c3-491d-9b9d-e7176d2be243 - $ref: '#/components/schemas/FailureResponse' GroupActionStatusResponseArray: type: array items: $ref: '#/components/schemas/GroupActiontStatusResponse' TriggerResponse: type: object allOf: - $ref: '#/components/schemas/EventNameReference' - $ref: '#/components/schemas/Action' - $ref: '#/components/schemas/InstanceId' TriggerStatusResponseArray: type: array items: $ref: '#/components/schemas/TriggerResponse' GroupTriggerResponse: type: object allOf: - type: object properties: deviceId: type: string format: uuid example: 0dc729d7-f6c3-491d-9b9d-e7176d2be243 - $ref: '#/components/schemas/EventNameReference' - $ref: '#/components/schemas/Action' GroupTriggerStatusResponseArray: type: array items: $ref: '#/components/schemas/GroupTriggerResponse' ]]>
Protocol Mapping The OpenAPI model for SDF protocol mapping is provided in .
Protocol Information
Protocol Information for BLE
Protocol Information for Zigbee
NIPC API extensions The following OpenAPI models define a few example extensions to the NIPC API.
NIPC API write binary blob extension
NIPC API bulk operations extension
NIPC API write file extension
NIPC API conditional read extension
NIPC API conditional event extension
NIPC API property extensions
NIPC API CDDL Definition The following is a combined reference of all NIPC API CDDL definitions used in this document.
text }, ; key/value headers ? serverCACert: text } } DataAppWebsocket = { websocket: { URI: text, ? headers: { * text => text }, ; key/value headers ? serverCACert: text } } ; ============================================ ; From: cddl/api/event_status_array.cddl ; ============================================ EventStatusResponseArray = [* EventStatusResponseArrayItem] EventStatusResponseArrayItem = ( EventInstanceSuccess // \ FailureResponse ) ; Success item = { event, instanceId } EventInstanceSuccess = { event: text, ; SDF global name of the event (absolute URI \ with fragment) instanceId: text ; UUID (as text) } ; ============================================ ; From: cddl/api/failure_response.cddl ; ============================================ FailureResponse = { type: FailureTypeURI, status: uint, title: text, detail: text } ; Enumerated problem type URIs registered for NIPC FailureTypeURI = ( "https://www.iana.org/assignments/nipc-problem-types#invalid-id" / "https://www.iana.org/assignments/nipc-problem-types#invalid-sdf-\ url" / "https://www.iana.org/assignments/nipc-problem-types#extension-\ operation-not-executed" / "https://www.iana.org/assignments/nipc-problem-types#sdf-model-\ already-registered" / "https://www.iana.org/assignments/nipc-problem-types#sdf-model-in-\ use" / "https://www.iana.org/assignments/nipc-problem-types#unsupported-\ uri-scheme" / "https://www.iana.org/assignments/nipc-problem-types#property-not-\ readable" / "https://www.iana.org/assignments/nipc-problem-types#property-read\ -failed" / "https://www.iana.org/assignments/nipc-problem-types#property-not-\ writable" / "https://www.iana.org/assignments/nipc-problem-types#property-\ write-failed" / "https://www.iana.org/assignments/nipc-problem-types#event-already\ -enabled" / "https://www.iana.org/assignments/nipc-problem-types#event-not-\ enabled" / "https://www.iana.org/assignments/nipc-problem-types#event-not-\ registered" / "https://www.iana.org/assignments/nipc-problem-types#trigger-\ already-enabled" / "https://www.iana.org/assignments/nipc-problem-types#protocolmap-\ ble-already-connected" / "https://www.iana.org/assignments/nipc-problem-types#protocolmap-\ ble-no-connection" / "https://www.iana.org/assignments/nipc-problem-types#protocolmap-\ ble-connection-timeout" / "https://www.iana.org/assignments/nipc-problem-types#protocolmap-\ ble-bonding-failed" / "https://www.iana.org/assignments/nipc-problem-types#protocolmap-\ ble-connection-failed" / "https://www.iana.org/assignments/nipc-problem-types#protocolmap-\ ble-service-discovery-failed" / "https://www.iana.org/assignments/nipc-problem-types#protocolmap-\ ble-invalid-service-or-characteristic" / "https://www.iana.org/assignments/nipc-problem-types#protocolmap-\ zigbee-connection-timeout" / "https://www.iana.org/assignments/nipc-problem-types#protocolmap-\ zigbee-invalid-endpoint-or-cluster" / "https://www.iana.org/assignments/nipc-problem-types#extension-\ transmit-invalid-data" / "https://www.iana.org/assignments/nipc-problem-types#extension-\ firmware-rollback" / "https://www.iana.org/assignments/nipc-problem-types#extension-\ firmware-update-failed" / "about:blank" ) ; ============================================ ; From: cddl/api/group_event_status_response_array.cddl ; ============================================ GroupEventStatusResponseArray = [* GroupEventStatusResponse] GroupEventSuccessResponse = { event: text, deviceId: text } ; Each item is either an event+deviceId success or a \ GroupFailureResponse GroupEventStatusResponse = (GroupEventSuccessResponse // \ GroupFailureResponse) GroupFailureResponse = { FailureResponse, ? deviceId: text } ; ============================================ ; From: cddl/api/group_trigger_status_array.cddl ; ============================================ ; Group Trigger status response array and item shape GroupTriggerStatusResponseArray = [* GroupTriggerResponse] GroupTriggerResponse = (GroupTriggerSuccessResponse // \ GroupTriggerFailureResponse) GroupTriggerSuccessResponse = { eventName: text, ; SDF event name action: text, ; NIPC action operation to execute deviceId: text ; UUID (as text) } GroupTriggerFailureResponse = { FailureResponse, ? deviceId: text } ; ============================================ ; From: cddl/api/trigger_status_array.cddl ; ============================================ ; Trigger status response array and item shape TriggerStatusResponseArray = [* TriggerResponse] TriggerResponse = { eventName: text, ; SDF event name action: text, ; NIPC action operation to execute instanceId: text ; UUID (as text) } ; ============================================ ; From: cddl/api/property_value_array.cddl ; ============================================ PropertyValueArray = [* PropertyValue] ; Minimal PropertyValue shape (matches allOf of Property + Value) PropertyValue = { property: text, ; SDF global name of the property value: b64text ; base64-encoded bytes (RFC 4648 Section 4) } ; Helper type for base64-with-padding encoded text b64text = text ; ============================================ ; From: cddl/api/property_value_read_response_array.cddl ; ============================================ PropertyValueReadResponseArray = [* \ PropertyValueReadResponseArrayItem] PropertyValueReadResponseArrayItem = ( PropertyValue // \ FailureResponse ) ; ============================================ ; From: cddl/api/property_value_response_array.cddl ; ============================================ PropertyValueResponseArray = [* PropertyValueResponseArrayItem] PropertyValueResponseArrayItem = ( SuccessResponse // \ FailureResponse ) ; Minimal success shape (may be extended) SuccessResponse = { status: uint } ; ============================================ ; From: cddl/api/sdf_reference.cddl ; ============================================ SdfGlobalName = text ; absolute URI with fragment referencing an \ sdfThing or sdfObject SdfReference = { sdfName: SdfGlobalName } SdfReferenceArray = [* SdfReference] ; ============================================ ; From: cddl/api/connection.cddl ; ============================================ ConnectionRequest = { ? retries: uint, ? protocol-info-service-map } ConnectionResponse = { id: text, ; Device ID ? protocol-info-service-map } ; ============================================ ; From: cddl/api/protocolinfo.cddl ; ============================================ ; Top-level wrappers protocol-info-service-map = ( ? protocolInformation: ble-service-map / zigbee-service-map ) protocol-info-broadcast = ( ? protocolInformation: ble-broadcast / zigbee-broadcast ) ; BLE protocol information ble-service-map = { ble: { ? services: [* ble-service], ? cached: bool, ? cacheExpiryDuration: int, ? autoUpdate: bool, ? bonding: bonding-type, } } bonding-type = "default" / "none" / "justworks" / "passkey" / "oob" ble-service = { serviceID: uuid, ? characteristics: [* ble-characteristic], } ble-characteristic = { characteristicID: uuid, ? flags: [* ble-flag], ? descriptors: [* ble-descriptor], } ble-flag = "read" / "write" / "notify" / "indicate" / "write-no-\ response" ble-descriptor = { descriptorID: uuid, } ble-broadcast = { ble: { ? connectable: bool, }, } ; Zigbee protocol information zigbee-service-map = { zigbee: { ? endpoints: [* zigbee-endpoint], }, } zigbee-endpoint = { endpointID: uint, ? clusters: [* zigbee-cluster], } zigbee-cluster = { clusterID: uint, ? attributes: [* zigbee-attribute], } zigbee-attribute = { attributeID: uint, attributeType: uint, ? flags: [* zigbee-flag], } zigbee-flag = "read" / "write" / "report" zigbee-broadcast = { zigbee: { }, } ; Basic types uuid = tstr .regexp "(?i)^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-\ f]{4}-[0-9a-f]{12}$" ]]>
Example SDF model with protocol mappings for BLE
Acknowledgements This document relies on SDF models described in , as such, we are grateful to the authors of this document for putting their time and effort into defining SDF in depth, allowing us to make use of it. The authors would like to thank Ari Keränen, Carsten Bormann, Eliot Lear, Michael Richardson, and Sriram Sekar for their reviews and contributions that helped improve this document.