Add ADR for adding flow collections to the API

Add implementation of flow and source collections Update readme.md
bbc · Mar 27, 2024 · 4704e1a · 4704e1a
1 parent fd49dc9
commit 4704e1a
Show file tree

Hide file tree

Showing 19 changed files with 298 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -93,6 +93,10 @@ Media workflows and applications are likely to use Sources as their references t
 Then some logic can be applied to identify a suitable Flow representing that Source at the point when operations need to be performed on the media, for example choosing between proxy-quality for an offline edit and full-quality for a render.
 
 The TAMS API stores both Flows and Sources, each of which can be assigned a label, description and some tags alongside relevant technical metadata.
+Flows can be collected into other Flows (with a `role` parameter to ascribe meaning to the relationship).
+Sources can collect together other Sources, by inference from the relationships defined by their Flows.
+This implementation is deliberately kept very simple, and lacks efficient mechansisms to query the graph of Sources and Flows.
+More sophisticated mechanisms for recording and querying relationships between model entities is out of scope for this API, but could in principle be provided by a separate complementary service dedicated to that purpose in the future.
 
 ### Mutation
 

diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml
@@ -563,6 +563,11 @@ paths:
                   description: TAMS can also be used for storing non-AV content such as subtitles or event data
                   value:
                     $ref: examples/flow-get-200-data-ttml.json
+                multi:
+                  summary: Multi-essence Flow
+                  description: Multi-essence Flows are used to collect multiple Flows of different formats under one Flow ID
+                  value:
+                    $ref: examples/flow-get-200-multi.json
         "404":
           description: The requested flow does not exist.
         "400":
@@ -575,8 +580,15 @@ paths:
       requestBody:
         content:
           application/json:
-            example:
-              $ref: examples/flow-put.json
+            examples:
+              audio:
+                summary: Stereo audio Flow
+                value:
+                  $ref: examples/flow-put.json
+              multi:
+                summary: Multi-essence Flow
+                value:
+                  $ref: examples/flow-put-multi.json
             schema:
               $ref: schemas/flow.json
         required: true

diff --git a/api/examples/flow-get-200-audio-aac.json b/api/examples/flow-get-200-audio-aac.json
@@ -25,5 +25,8 @@
             "coded_frame_size": 1024,
             "mp4_oti": 2
         }
-    }
+    },
+    "collected_by": [
+      "e85efab4-993b-4ad6-9af3-4cd8d0d38860"
+    ]
 }
diff --git a/api/examples/flow-get-200-data-ttml.json b/api/examples/flow-get-200-data-ttml.json
@@ -11,5 +11,8 @@
     "container": "application/ttml+xml",
     "essence_parameters": {
         "data_type": "urn:x-tams:data:subtitle"
-    }
+    },
+    "collected_by": [
+      "e85efab4-993b-4ad6-9af3-4cd8d0d38860"
+    ]
 }
diff --git a/api/examples/flow-get-200-multi.json b/api/examples/flow-get-200-multi.json
@@ -0,0 +1,24 @@
+{
+    "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",
+    "source_id": "a77d0061-0878-4e8a-a114-772d03f952c1",
+    "format": "urn:x-nmos:format:multi",
+    "generation": 0,
+    "created": "2023-12-14T16:34:58.131620",
+    "tags": {
+        "ingested_by": "ingest_service_api"
+    },
+    "flow_collection": [
+        {
+            "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
+            "role": "video"
+        },
+        {
+            "id": "6101df05-06bb-41b8-8af4-cf7cd33df209",
+            "role": "audio"
+        },
+        {
+            "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",
+            "role": "subtitles"
+        }
+    ]
+}
diff --git a/api/examples/flow-get-200-video-h264.json b/api/examples/flow-get-200-video-h264.json
@@ -44,5 +44,8 @@
       "level": 31,
       "flags": 0
     }
-  }
+  },
+  "collected_by": [
+    "e85efab4-993b-4ad6-9af3-4cd8d0d38860"
+  ]
 }
diff --git a/api/examples/flow-put-multi.json b/api/examples/flow-put-multi.json
@@ -0,0 +1,24 @@
+{
+    "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",
+    "source_id": "a77d0061-0878-4e8a-a114-772d03f952c1",
+    "description": "SRT Feed 1",
+    "label": "OB Truck A Mix Out",
+    "format": "urn:x-nmos:format:multi",
+    "tags": {
+        "ingested_by": "ingest_service_api"
+    },
+    "flow_collection": [
+        {
+            "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
+            "role": "video"
+        },
+        {
+            "id": "6101df05-06bb-41b8-8af4-cf7cd33df209",
+            "role": "audio"
+        },
+        {
+            "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",
+            "role": "subtitles"
+        }
+    ]
+}
diff --git a/api/examples/source-get-200-basic.json b/api/examples/source-get-200-basic.json
@@ -7,7 +7,7 @@
     "modified_by": "tams-dev",
     "created": "2008-05-27T18:51:00Z",
     "updated": "2008-05-27T18:51:00Z",
-    "tags": {
-        "ingested_by": "ingest_service_api"
-    }
+    "collected_by": [
+        "86761f3a-5998-4cfe-9a89-8459bcb8ea52"
+    ]
 }
diff --git a/api/examples/source-get-200-multi.json b/api/examples/source-get-200-multi.json
@@ -0,0 +1,20 @@
+{
+    "id": "86761f3a-5998-4cfe-9a89-8459bcb8ea52",
+    "format": "urn:x-nmos:format:multi",
+    "label": "bbb",
+    "description": "Big Buck Bunny",
+    "created_by": "tams-dev",
+    "modified_by": "tams-dev",
+    "created": "2008-05-27T18:51:00Z",
+    "updated": "2008-05-27T18:51:00Z",
+    "source_collection": [
+        {
+            "id": "2aa143ac-0ab7-4d75-bc32-5c00c13d186f",
+            "role": "video"
+        },
+        {
+            "id": "7ba3fed1-3fd3-4f0e-8488-92c4ffe13838",
+            "role": "audio"
+        }
+    ]
+}
diff --git a/api/examples/sources-get-200.json b/api/examples/sources-get-200.json
@@ -8,28 +8,38 @@
     "modified_by": "tams-dev",
     "created": "2008-05-27T18:51:00Z",
     "updated": "2008-05-27T18:51:00Z",
-    "tags": {
-        "ingested_by": "ingest_service_api"
-    }
+    "collected_by": [
+        "86761f3a-5998-4cfe-9a89-8459bcb8ea52"
+    ]
   },
   {
     "id": "86761f3a-5998-4cfe-9a89-8459bcb8ea52",
-    "format": "urn:x-nmos:format:mux",
+    "format": "urn:x-nmos:format:multi",
     "label": "bbb",
     "description": "Big Buck Bunny",
     "created_by": "tams-dev",
     "modified_by": "tams-dev",
     "created": "2008-05-27T18:51:00Z",
     "updated": "2008-05-27T18:51:00Z",
-    "tags": {
-        "ingested_by": "ingest_service_api"
-    }
+    "source_collection": [
+      {
+          "id": "2aa143ac-0ab7-4d75-bc32-5c00c13d186f",
+          "role": "video"
+      },
+      {
+          "id": "7ba3fed1-3fd3-4f0e-8488-92c4ffe13838",
+          "role": "audio"
+      }
+  ]
   },
   {
     "id": "7ba3fed1-3fd3-4f0e-8488-92c4ffe13838",
     "format": "urn:x-nmos:format:audio",
     "description": "Big Buck Bunny audio",
     "created": "2008-05-27T18:51:00Z",
-    "updated": "2008-05-27T18:51:00Z"
+    "updated": "2008-05-27T18:51:00Z",
+    "collected_by": [
+        "86761f3a-5998-4cfe-9a89-8459bcb8ea52"
+    ]
   }
 ]
diff --git a/api/schemas/collection-item.json b/api/schemas/collection-item.json
@@ -0,0 +1,20 @@
+{
+    "type": "object",
+    "description": "Describes how an object (Source or Flow) is collected into another object of the same type",
+    "title": "Collection Item",
+    "required": [
+        "id",
+        "role"
+    ],
+    "properties": {
+        "id": {
+            "description": "Source or Flow Identifier of the member of this collection.  Must already be registered in TAMS",
+            "type": "string",
+            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+        },
+        "role": {
+            "description": "A human-readable role of the element in this collection (e.g. 'R' to denote a right audio channel in a collection of mono audio Sources, or )",
+            "type": "string"
+        }
+    }
+}
diff --git a/api/schemas/flow-audio.json b/api/schemas/flow-audio.json
@@ -10,7 +10,9 @@
       "type": "object",
       "required": [
         "format",
-        "essence_parameters"
+        "essence_parameters",
+        "codec",
+        "container"
       ],
       "properties": {
         "format": {

diff --git a/api/schemas/flow-core.json b/api/schemas/flow-core.json
@@ -4,9 +4,7 @@
   "title": "Flow Core",
   "required": [
     "id",
-    "source_id",
-    "container",
-    "codec"
+    "source_id"
   ],
   "properties": {
     "id": {
@@ -86,6 +84,21 @@
     "timerange": {
       "description": "The timerange of samples available in the flow, as described by the [TimeRange](../schemas/timerange#top) type",
       "$ref": "timerange.json"
+    },
+    "flow_collection": {
+        "type": "array",
+        "description": "List of Flows that are collected together by this Flow.",
+        "items": {
+            "$ref": "collection-item.json"
+        }
+    },
+    "collected_by": {
+      "type": "array",
+      "description": "Flows that reference this Flow to include it in a collection. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally",
+      "items": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+      }
     }
   }
 }
diff --git a/api/schemas/flow-data.json b/api/schemas/flow-data.json
@@ -10,7 +10,9 @@
       "type": "object",
       "required": [
         "format",
-        "essence_parameters"
+        "essence_parameters",
+        "codec",
+        "container"
       ],
       "properties": {
         "format": {

diff --git a/api/schemas/flow-multi.json b/api/schemas/flow-multi.json
@@ -0,0 +1,25 @@
+{
+  "type": "object",
+  "description": "Describes a multi-essence Flow",
+  "title": "Multi-essence Flow",
+  "allOf": [
+    {
+      "$ref": "flow-core.json"
+    },
+    {
+      "type": "object",
+      "required": [
+        "format"
+      ],
+      "properties": {
+        "format": {
+          "description": "The primary content type URN for the flow.",
+          "type": "string",
+          "enum": [
+            "urn:x-nmos:format:multi"
+          ]
+        }
+      }
+    }
+  ]
+}
diff --git a/api/schemas/flow-video.json b/api/schemas/flow-video.json
@@ -10,7 +10,9 @@
             "type": "object",
             "required": [
                 "format",
-                "essence_parameters"
+                "essence_parameters",
+                "codec",
+                "container"
             ],
             "properties": {
                 "format": {

diff --git a/api/schemas/flow.json b/api/schemas/flow.json
@@ -5,6 +5,7 @@
   "oneOf": [
     { "$ref": "flow-video.json" },
     { "$ref": "flow-audio.json" },
-    { "$ref": "flow-data.json" }
+    { "$ref": "flow-data.json" },
+    { "$ref": "flow-multi.json" }
   ]
 }
diff --git a/api/schemas/source.json b/api/schemas/source.json
@@ -19,7 +19,7 @@
                 "urn:x-nmos:format:video",
                 "urn:x-nmos:format:audio",
                 "urn:x-nmos:format:data",
-                "urn:x-nmos:format:mux"
+                "urn:x-nmos:format:multi"
             ],
             "format": "uri"
         },
@@ -51,6 +51,21 @@
         },
         "tags": {
             "$ref": "tags.json"
+        },
+        "source_collection": {
+            "type": "array",
+            "description": "List of Sources that are collected together by this Source. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally. Source collections can be inferred from Flow collection definitions.",
+            "items": {
+                "$ref": "collection-item.json"
+            }
+        },
+        "collected_by": {
+          "type": "array",
+          "description": "Sources that reference this Source to include it in a collection. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally. Source collections can be inferred from Flow collection definitions.",
+          "items": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+           }
         }
     }
 }