feat: Play Intent (#151)

* First draft of Play Intent * Fix document headers * feat: Added Entity specs * fix: Updating github.io publish script to handle index.md better * Iterations from spec review * fix: Iteration w/ Simon's feedback * fix: Split play intent into play-entity and play-query * fix: Adding assetId back to spec * feat: Adding Play Intent schemas * fix: Schema cleanup * fix: adding validate:each to dist task * fix: Remove enum form context.source * fix: Fix links and formatting
rdkcentral · Oct 27, 2023 · d1ddf3f · d1ddf3f
1 parent e75f449
commit d1ddf3f
Show file tree

Hide file tree

Showing 11 changed files with 16,409 additions and 739 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -23,7 +23,7 @@
     "test:setup": "npm run test:setup --workspaces",
     "test": "npm run test:setup && NODE_OPTIONS=--experimental-vm-modules npx --config=jest.config.json --detectOpenHandles jest",
     "clean": "rm -rf dist && npm run clean --workspaces",
-    "dist": "npm run fs:setup && npm run compile && npm run specification && npm run version && npm run dist:notest --workspaces && npm run test",
+    "dist": "npm run fs:setup && npm run validate:each && npm run compile && npm run specification && npm run version && npm run dist:notest --workspaces && npm run test",
     "specification": "node ./src/js/version-specification/index.mjs --source ./src/json/firebolt-specification.json",
     "specification:report": "node ./src/js/version-specification/index.mjs --source ./dist/firebolt-specification.json --report",
     "version": "node ./src/js/version.mjs sync",
@@ -45,7 +45,7 @@
     "@commitlint/cli": "^17.0.3",
     "@commitlint/config-conventional": "^17.0.3",
     "@firebolt-js/openrpc": "2.1.0",
-    "@firebolt-js/schemas": "1.0.0-next.0",
+    "@firebolt-js/schemas": "2.0.0-next.0",
     "@saithodev/semantic-release-backmerge": "^3.2.0",
     "@semantic-release/changelog": "^6.0.1",
     "@semantic-release/git": "^10.0.1",

diff --git a/requirements/specifications/entities/channels.md b/requirements/specifications/entities/channels.md
@@ -0,0 +1,57 @@
+# Channel Entities
+
+Document Status: Proposed Specification 
+
+See [Firebolt Requirements Governance](../../governance.md) for more info. 
+
+| Contributor     | Organization |
+| --------------- | ------------ |
+| Jeremy LaCivita | Comcast      |
+
+## 1. Overview
+TBD... 
+
+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. Channel Entities](#3-channel-entities)
+
+
+## 3. Channel Entities
+Every Channel Entity **MUST** be an [Entity](./index.md#3-entities). 
+
+Every Channel Entity **MUST** have a `const` property named `entityType`, which 
+**MUST** have the value `"channel"`. 
+
+Every Channel Entity **MUST** have a `string` property named `channelType`, 
+whose value **MUST** be one of: 
+
+ - `"streaming"`
+ - `"broadcast"`
+
+An example Channel Entity: 
+
+```json
+{
+    "entityType": "channel",
+    "channelType": "streaming",
+    "entityId": "streaming/xyz"
+}
+``` 
+
+Another example Channel Entity: 
+
+```json
+{
+    "entityType": "channel",
+    "channelType": "broadcast",
+    "entityId": "broadcast/xyz"
+}
+``` 
diff --git a/requirements/specifications/entities/index.md b/requirements/specifications/entities/index.md
@@ -0,0 +1,86 @@
+# Firebolt Entities
+
+Document Status: Proposed Specification 
+
+See [Firebolt Requirements Governance](../../governance.md) for more info. 
+
+## 1. Overview
+Entities are object which identify a piece of content that an end-user may 
+consume within an app. 
+
+Firebolt uses Entities or Entity Ids as parameters and/or results of 
+content-centric Firebolt APIs that an App may interact with. 
+
+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. Entities](#3-entities)
+- [4. Playlist Entities](#4-playlist-entities)
+- [5. Entity Specifications](#5-entity-specifications)
+
+## 3. Entities
+Every Entity **MUST** be of type `object`. 
+
+Every Entity object **MUST** have a `string` property named `entityId`, which 
+identifies the entity. The scope of entity identifiers **SHOULD** be defined by 
+the app providing or receiving the Entity, so that the App may work across 
+Firebolt distrubutions without mapping IDs from a distributor space to the 
+App's space. 
+
+Every Entity object **MAY** have a `string` property named `assetId`, which 
+disambiguates the asset from the entity, if needed. The scope of asset 
+identifiers **SHOULD** be defined by the app providing or receiving the Entity, 
+so that the App may work across Firebolt distrubutions without mapping IDs from 
+a distributor space to the App's space. 
+
+Every Entity object **MAY** have a `string` property named `appContentData`, 
+limited to 256 characters, which provides additional information useful for 
+targeting that Entity, e.g. a deeplink path. 
+
+An example Entity: 
+
+```json
+{
+    "entityId": "entity/abc"
+}
+``` 
+
+Another example Entity: 
+
+```json
+{
+    "entityId": "entity/abc",
+    "assetId": "asset/123",
+    "appContentData": "xyz"
+}
+``` 
+
+Firebolt platforms **MUST NOT** infer anything from the values of these fields, 
+although back-office systems operated by Firebolt distributors may. 
+
+## 4. Playlist Entities
+A playlist is a type of entity that points to a list of other entities. 
+
+Since entity IDs are in the target app's scope, it is up to each app to know 
+what to do with the contents of a given playlist. 
+
+
+```json
+{
+    "entityType": "playlist",
+    "entityId": "playlist/xyz"
+}
+``` 
+
+## 5. Entity Specifications
+
+- [Program Entities](./programs.md)
+- [Channel Entities](./channels.md)
+- [Music Entities](./music.md)
diff --git a/requirements/specifications/entities/music.md b/requirements/specifications/entities/music.md
@@ -0,0 +1,74 @@
+# Music Entities
+
+Document Status: Proposed Specification 
+
+See [Firebolt Requirements Governance](../../governance.md) for more info. 
+
+| Contributor     | Organization |
+| --------------- | ------------ |
+| Jeremy LaCivita | Comcast      |
+| Liz Sheffield   | Comcast      |
+
+## 1. Overview
+TBD... 
+
+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. Music Entities](#3-music-entities)
+  - [3.1. Optional Music Entity Properties](#31-optional-music-entity-properties)
+
+
+## 3. Music Entities
+Every Music Entity **MUST** be an [Entity](./index.md#3-entities). 
+
+Every Music Entity **MUST** have a `const` property named `entityType`, which 
+**MUST** have the value `"music"`. 
+
+Every Music Entity **MUST** have a `string` property named `musicType`, whose 
+value **MUST** be one of: 
+
+ - `"song"`
+ - `"album"`
+
+An example Music Entity: 
+
+```json
+{
+    "entityType": "music",
+    "musicType": "song",
+    "entityId": "song/xyz"
+}
+``` 
+
+Another example Music Entity: 
+
+```json
+{
+    "entityType": "music",
+    "musicType": "album",
+    "entityId": "album/xyz"
+}
+``` 
+
+### 3.1. Optional Music Entity Properties
+A Music Entity **MAY** have a `string` property named `albumId` if its 
+musicType is `song`, otherwise the entity **MUST NOT** have this property. 
+
+An example Music Entity: 
+
+```json
+{
+    "entityType": "music",
+    "musicType": "song",
+    "entityId": "song/xyz",
+    "albumId": "album/xyz"
+}
+``` 
diff --git a/requirements/specifications/entities/programs.md b/requirements/specifications/entities/programs.md
@@ -0,0 +1,100 @@
+# Program Entities
+
+Document Status: Proposed Specification 
+
+See [Firebolt Requirements Governance](../../governance.md) for more info. 
+
+| Contributor     | Organization |
+| --------------- | ------------ |
+| Seth Kelly      | Comcast      |
+| Jeremy LaCivita | Comcast      |
+
+## 1. Overview
+TBD... 
+
+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. Program Entities](#3-program-entities)
+  - [3.1. Optional TV Entity Properties](#31-optional-tv-entity-properties)
+
+
+## 3. Program Entities
+Every Program Entity **MUST** be an [Entity](./index.md#3-entities). 
+
+Every Program Entity **MUST** have a `const` property named `entityType`, which 
+**MUST** have the value `"program"`. 
+
+Every Program Entity **MUST** have a `string` property named `programType`, 
+whose value **MUST** be one of: 
+
+ - `"movie"`
+ - `"episode"`
+ - `"season"`
+ - `"series"`
+ - `"other"`
+ - `"preview"`
+ - `"extra"`
+ - `"concert"`
+ - `"sportingEvent"`
+ - `"advertisement"`
+ - `"musicVideo"`
+ - `"minisode"`
+
+An example Program Entity: 
+
+```json
+{
+    "entityType": "program",
+    "programType": "movie",
+    "entityId": "entity/abc"
+}
+``` 
+
+Another example Entity: 
+
+```json
+{
+    "entityType": "program",
+    "programType": "episode",
+    "entityId": "entity/xyz"
+}
+``` 
+
+### 3.1. Optional TV Entity Properties
+A Program Entity **MAY** have a `string` property named `seasonId` if its 
+programType is `episode`, otherwise the entity **MUST NOT** have this property. 
+
+A Program Entity **MAY** have a `string` property named `seriesId` if its 
+programType is either `episode` or `season`, otherwise the entity **MUST NOT** 
+have this property. 
+
+An example TV Program Entity: 
+
+```json
+{
+    "entityType": "program",
+    "programType": "episode",
+    "entityId": "entity/def",
+    "seriesId": "entity/hij",
+    "seasonId": "entity/klm"
+}
+``` 
+
+Another example TV Program Entity: 
+
+```json
+{
+    "entityType": "program",
+    "programType": "season",
+    "entityId": "entity/klm",
+    "seriesId": "entity/hij"
+}
+```