From 4d322eaa10eca14ad1ed9ff5d0ad66c2c6bfb681 Mon Sep 17 00:00:00 2001 From: Jeremy LaCivita Date: Mon, 19 Feb 2024 16:14:30 -0500 Subject: [PATCH] feat: Split Core & Extension APIs --- .../device/device-information.md | 4 + .../device/syndication-ontology.md | 109 ++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 requirements/specifications/device/syndication-ontology.md diff --git a/requirements/specifications/device/device-information.md b/requirements/specifications/device/device-information.md index 3aae6d543..9d368457b 100644 --- a/requirements/specifications/device/device-information.md +++ b/requirements/specifications/device/device-information.md @@ -15,6 +15,8 @@ See [Firebolt Requirements Governance](../../governance.md) for more info. ## 1. Overview This document outlines the requirements for ontological, intrinsic, and product-related device indentification APIs. +**TODO**: add capabilities to all APIs + 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](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. ## 2. Table of Contents @@ -55,6 +57,8 @@ This API will likely only be permitted to fisrt-party apps and **MUST** only be The value of this **MUST** be unique within a distributor. +This API requires `use` access to the `xrn:firebolt:capability:device:identification` capability. + **NOTE**: we probably need a registry of Firebolt distributors to avoid collisions. ### 3.2. Anonymized Device Identifier diff --git a/requirements/specifications/device/syndication-ontology.md b/requirements/specifications/device/syndication-ontology.md new file mode 100644 index 000000000..1703d7bb8 --- /dev/null +++ b/requirements/specifications/device/syndication-ontology.md @@ -0,0 +1,109 @@ +# Syndication SDK + +Document Status: Working Draft + +See [Firebolt Requirements Governance](../../governance.md) for more info. + +| Contributor | Organization | +| --------------- | -------------- | +| Jeremy LaCivita | Comcast | +| Peter Yu | Comcast | + +## 1. Overview +This document outlines the requirements for ontological, intrinsic, and product-related device indentification APIs. + +**TODO**: add capabilities to all APIs + +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](https://www.rfc-editor.org/rfc/rfc2119.txt) [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +## 2. Table of Contents +- [1. Overview](#1-overview) +- [2. Table of Contents](#2-table-of-contents) +- [3. Ontology](#3-ontology) + - [3.1. OS Class](#31-os-class) + - [3.2. Leased](#32-leased) + - [3.3. Experience](#33-experience) + - [3.4. Account Type](#34-account-type) + - [3.5. Account Sub Type](#35-account-sub-type) + - [3.6. Programmer](#36-programmer) + - [3.7. Retailer](#37-retailer) + +## 3. Ontology +The Syndication Extension SDK **MUST** expose an `Ontology` module to contain the APIs outlined below. + +### 3.1. OS Class +The `Ontology` module of the Syndication Extension SDK **MUST** have a string `osClass` property that returns what software and bootstrap configuration needs to be loaded on the device for a given operator. + +This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +The value **SHOULD** be set during device activation by a 1st party setup experience. + +Examples values: + +- `entos-rdk-residential` +- `entos-rdk-commercial` +- `skyq-rdk` +- `xre-rdk` +- `flex-rdk` + +### 3.2. Leased +The `Ontology` module of the Syndication Extension SDK **MUST** have a boolean `leased` property that returns whether or not the device is leased by the customer (true) or owned (false). + +This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +The value **SHOULD** be set during device activation by a 1st party setup experience. + +### 3.3. Experience +The `Ontology` module of the Syndication Extension SDK **MUST** have a string `experienceAppId` property that returns the appId of the primary aggregated experience app, aka "launcher", aka EPG, installed on this device. + +This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +The value **SHOULD** be set during device activation by a 1st party setup experience. + +**TODO**: is app id okay here? what if a Firebolt app is using this API and is running on a different distribution platform w/ different app ids? + +### 3.4. Account Type +The `Ontology` module of the Syndication Extension SDK **MUST** have a string `accountType` property that returns the type of account that is active on this device, e.g. `"residential"` or `"business"`. + +This property **MUST** be read only by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +The value of this property **MUST** be configurable as a pass-through provider and may be provided by an App, a middleware component, or a cloud REST API. + +See [Cloud Pass-through Providers](#) for more info. + +### 3.5. Account Sub Type +The `Ontology` module of the Syndication Extension SDK **MUST** have a string `accountSubType` property that returns the type of account that is active on this device, e.g. `"hospitality"` or `"university"`. + +This property **MUST** be read only by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +The value of this property **MUST** be configurable as a pass-through provider and may be provided by an App, a middleware component, or a cloud REST API. + +See [Cloud Pass-through Providers](#) for more info. + +### 3.6. Programmer +The `Ontology` module of the Syndication Extension SDK **MUST** have a string `programmerId` property that returns the ID of the partner that is providing programming to the primary aggregated experience. + +This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +The value **SHOULD** be set during device activation by a 1st party setup experience. + +**TODO**: What is the scope of these ids? + +### 3.7. Retailer +The `Ontology` module of the Syndication Extension SDK **MUST** have a string `retailerId` property that returns the ID of the partner that initially retailed the device. + +This property **MUST** be readable by any app with `use` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +This property **MUST** be read/write and have a setter available to any app with `manage` access to the `xrn:firebolt:capability:syndication:ontology` capability. + +The value **SHOULD** be set during device activation by a 1st party setup experience. + +**TODO**: What is the scope of these ids?