Make role optional in collections, capture the same information elsewhere

README.md

@@ -95,7 +95,7 @@ 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).
+Flows can be collected into other Flows (with an optional `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.

api/TimeAddressableMediaStore.yaml

@@ -923,6 +923,10 @@ paths:
                   summary: Multi-essence Source
                   description: Multi-essence Sources collect multiple Sources of different formats under one Source ID.
                   externalValue: examples/source-get-200-multi.json
+                tags:
+                  summary: Source with tags
+                  description: Source example with tags set matching associated Flow
+                  externalValue: examples/source-get-200-tags.json
         "404":
           description: The requested Source does not exist.
   /sources/{sourceId}/tags:
@@ -1542,6 +1546,9 @@ paths:
                 video_vfr:
                   summary: Video Flow - H.264 Codec, Variable Frame Rate
                   externalValue: examples/flow-get-200-video-h264-vfr.json
+                video_cleanfeed:
+                  summary: Video Flow - H.264 Codec, with Editorial Purpose Tag
+                  externalValue: examples/flow-get-200-video-h264-cleanfeed.json
                 audio:
                   summary: Audio Flow - AAC Codec
                   externalValue: examples/flow-get-200-audio-aac.json
@@ -1586,7 +1593,7 @@ paths:
         Service implementations SHOULD verify that Flow metadata is compatible with the associated Source.
         Service implementations MAY accept modification/addition of parameters, and reflect such changes in the Source, where it will not bring any Flows of the Source into conflict.
         Where metadata would result in any Flow of the Source coming into conflict, the request SHOULD be rejected with a 400 response.
-        Examples of conflicting metadata include `format` not matching, or the `role` in `source_collection` and `flow_collection` not matching.
+        Examples of conflicting metadata include `format` not matching, or `role` or ordering in `source_collection` and `flow_collection` not matching.
         It may also be possible for service implementations to detect some instances where multiple Flows should not be considered of the same Source, such as audio Flows with different numbers of tracks.
         Further guidance on when Flows/Sources may be considered the same/different may be found in the [Practical Guidance for Media](https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/3.0._Practical_Guidance_for_Media.html) section of AMWA MS-04.
 
@@ -2014,7 +2021,7 @@ paths:
           $ref: '#/components/responses/trait_resource_info_head_404'
     get:
       summary: Flow Collection
-      description: Returns the Flow collection property. A list of Flows that are collected together by this Flow.
+      description: Returns the Flow collection property. An ordered list of Flows that are collected together by this Flow.
       operationId: GET_flows-flowId-flow-collection
       tags:
         - Flows
@@ -2032,7 +2039,7 @@ paths:
     put:
       summary: Create or Update Flow Collection
       description: |
-        Create or update the Flow collection property. A list of Flows that are collected together by this Flow.
+        Create or update the Flow collection property. An ordered list of Flows that are collected together by this Flow.
 
         Service implementations SHOULD verify that Flow metadata is compatible with the associated Source.
         Service implementations MAY accept modification/addition of parameters, and reflect such changes in the Source, where it will not bring any Flows of the Source into conflict.

api/examples/flow-collection-get-200.json

@@ -1,14 +1,11 @@
 [
     {
-        "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
-        "role": "video"
+        "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34"
     },
     {
-        "id": "6101df05-06bb-41b8-8af4-cf7cd33df209",
-        "role": "audio"
+        "id": "6101df05-06bb-41b8-8af4-cf7cd33df209"
     },
     {
-        "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",
-        "role": "subtitles"
+        "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860"
     }
 ]

api/examples/flow-collection-put.json

@@ -1,14 +1,11 @@
 [
     {
-        "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
-        "role": "video"
+        "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34"
     },
     {
-        "id": "6101df05-06bb-41b8-8af4-cf7cd33df209",
-        "role": "audio"
+        "id": "6101df05-06bb-41b8-8af4-cf7cd33df209"
     },
     {
-        "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",
-        "role": "subtitles"
+        "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860"
     }
 ]

api/examples/flow-get-200-multi-container-map.json

@@ -11,11 +11,14 @@
     "flow_collection": [
         {
             "id": "32b75860-83e5-48c9-8d6b-de46bdbc7f80",
-            "role": "video"
+            "container_mapping": {
+                "mp2ts_container": {
+                    "pid": 256
+                }
+            }
         },
         {
             "id": "94996f2e-0cb5-43d3-ab6c-db5a9cf667aa",
-            "role": "L",
             "container_mapping": {
                 "track_index": 1,
                 "format_track_index": 0,
@@ -26,7 +29,6 @@
         },
         {
             "id": "9ba0523e-22a0-4c69-a598-baf4be244a79",
-            "role": "R",
             "container_mapping": {
                 "track_index": 2,
                 "format_track_index": 1,

api/examples/flow-get-200-multi.json

@@ -1,6 +1,8 @@
 {
     "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",
     "generation": 0,
     "created": "2023-12-14T16:34:58.131620",
@@ -9,12 +11,14 @@
     },
     "flow_collection": [
         {
-            "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
-            "role": "video"
+            "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34"
         },
         {
-            "id": "6101df05-06bb-41b8-8af4-cf7cd33df209",
-            "role": "audio"
+            "id": "6101df05-06bb-41b8-8af4-cf7cd33df209"
+        },
+        {
+            "id": "c8943cb3-08df-46de-8ce8-0d7d70ed204c",
+            "role": "audio_description"
         },
         {
             "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",

api/examples/flow-get-200-video-h264-cleanfeed.json

@@ -0,0 +1,49 @@
+{
+    "id": "18e7f92e-4cbf-40e2-beb6-e9f6e2fb5af3",
+    "source_id": "a0456629-b25d-4c4b-b631-0861621f67c7",
+    "generation": 0,
+    "created": "2008-05-27T18:53:00Z",
+    "metadata_updated": "2023-09-14T09:45:26Z",
+    "segments_updated": "2023-09-14T09:45:26Z",
+    "description": "OB Truck A cleanfeed video",
+    "label": "SRT Feed 3",
+    "format": "urn:x-nmos:format:video",
+    "created_by": "ob-truck-a",
+    "updated_by": "ob-truck-a",
+    "tags": {
+        "input_quality": "contribution",
+        "editorial_purpose": "cleanfeed"
+    },
+    "codec": "video/h264",
+    "container": "video/mp2t",
+    "avg_bit_rate": 25000,
+    "segment_duration": {
+        "numerator": 10
+    },
+    "essence_parameters": {
+        "frame_rate": {
+            "numerator": 50,
+            "denominator": 1
+        },
+        "frame_width": 1920,
+        "frame_height": 1080,
+        "bit_depth": 8,
+        "interlace_mode": "progressive",
+        "colorspace": "BT709",
+        "transfer_characteristic": "SDR",
+        "aspect_ratio": {
+            "numerator": 16,
+            "denominator": 9
+        },
+        "pixel_aspect_ratio": {
+            "numerator": 1,
+            "denominator": 1
+        },
+        "component_type": "YCbCr",
+        "vert_chroma_subs": 2,
+        "horiz_chroma_subs": 2
+    },
+    "collected_by": [
+        "e85efab4-993b-4ad6-9af3-4cd8d0d38860"
+    ]
+}

api/examples/flow-put-multi.json

@@ -9,12 +9,14 @@
     },
     "flow_collection": [
         {
-            "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
-            "role": "video"
+            "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34"
         },
         {
-            "id": "6101df05-06bb-41b8-8af4-cf7cd33df209",
-            "role": "audio"
+            "id": "6101df05-06bb-41b8-8af4-cf7cd33df209"
+        },
+        {
+            "id": "c8943cb3-08df-46de-8ce8-0d7d70ed204c",
+            "role": "audio_description"
         },
         {
             "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",

api/examples/source-get-200-multi.json

@@ -9,12 +9,10 @@
     "updated": "2008-05-27T18:51:00Z",
     "source_collection": [
         {
-            "id": "2aa143ac-0ab7-4d75-bc32-5c00c13d186f",
-            "role": "video"
+            "id": "2aa143ac-0ab7-4d75-bc32-5c00c13d186f"
         },
         {
-            "id": "7ba3fed1-3fd3-4f0e-8488-92c4ffe13838",
-            "role": "audio"
+            "id": "7ba3fed1-3fd3-4f0e-8488-92c4ffe13838"
         }
     ]
 }

api/examples/source-get-200-tags.json

@@ -0,0 +1,16 @@
+{
+    "id": "a0456629-b25d-4c4b-b631-0861621f67c7",
+    "created": "2008-05-27T18:53:00Z",
+    "updated": "2023-09-14T09:45:26Z",
+    "description": "OB Truck A cleanfeed video",
+    "label": "SRT Feed 3",
+    "format": "urn:x-nmos:format:video",
+    "created_by": "ob-truck-a",
+    "updated_by": "ob-truck-a",
+    "tags": {
+        "editorial_purpose": "cleanfeed"
+    },
+    "collected_by": [
+        "a77d0061-0878-4e8a-a114-772d03f952c1"
+    ]
+}

api/examples/sources-get-200.json

@@ -23,12 +23,10 @@
         "updated": "2008-05-27T18:51:00Z",
         "source_collection": [
             {
-                "id": "2aa143ac-0ab7-4d75-bc32-5c00c13d186f",
-                "role": "video"
+                "id": "2aa143ac-0ab7-4d75-bc32-5c00c13d186f"
             },
             {
-                "id": "7ba3fed1-3fd3-4f0e-8488-92c4ffe13838",
-                "role": "audio"
+                "id": "7ba3fed1-3fd3-4f0e-8488-92c4ffe13838"
             }
         ]
     },
@@ -41,5 +39,21 @@
         "collected_by": [
             "86761f3a-5998-4cfe-9a89-8459bcb8ea52"
         ]
+    },
+    {
+        "id": "a0456629-b25d-4c4b-b631-0861621f67c7",
+        "created": "2008-05-27T18:53:00Z",
+        "updated": "2023-09-14T09:45:26Z",
+        "description": "OB Truck A cleanfeed video",
+        "label": "SRT Feed 3",
+        "format": "urn:x-nmos:format:video",
+        "created_by": "ob-truck-a",
+        "updated_by": "ob-truck-a",
+        "tags": {
+            "editorial_purpose": "cleanfeed"
+        },
+        "collected_by": [
+            "a77d0061-0878-4e8a-a114-772d03f952c1"
+        ]
     }
 ]

api/schemas/collection-item.json

@@ -3,16 +3,15 @@
     "description": "Describes how an entity (Source or Flow) is collected into another entity of the same type",
     "type": "object",
     "required": [
-        "id",
-        "role"
+        "id"
     ],
     "properties": {
         "id": {
             "description": "Source or Flow Identifier of the member of this collection. Sources MUST only collect Sources, and Flows MUST only collect Flows. Must already be registered in this service instance",
             "$ref": "uuid.json"
         },
         "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)",
+            "description": "The purpose of this element in the collection, primarily intended to be human-readable.",
             "type": "string"
         }
     }

api/schemas/flow-collection.json

@@ -1,6 +1,6 @@
 {
     "title": "Flow Collection",
-    "description": "Describes how Flows are collected into another Flow",
+    "description": "Describes how Flows are collected into another Flow. Note that this is an ordered list.",
     "type": "array",
     "items": {
         "type": "object",

docs/README.md

@@ -30,6 +30,7 @@ For more information on how we use application notes, see [here](./appnotes/READ
 | [0021](./appnotes/0021-media-integrity.md)                           | Integrity model for media in TAMS, and when interacting with other systems |
 | [0022](./appnotes/0022-transform-architectures.md)                   | Architectures for the transforming of media                     |
 | [0024](./appnotes/0024-using-init-segments.md)                       | Using Media with Initialisation Segments in TAMS                |
+| [0020](./appnotes/0025-editorial-purpose.md)                         | Editorial purpose                                               |
 
 ## ADRs
 
@@ -90,7 +91,9 @@ For more information on how we use ADRs, see [here](./adr/README.md).
 | [0047](./adr/0047-flow-profiles.md)                                | Adding Flow Profiles to TAMS                                               |
 | [0048](./adr/0048-media-integrity.md)                              | Integrity model for media in TAMS, and when interacting with other systems |
 | [0052](./adr/0052-specifying-the-sorting-of-listings.md)           | Options for specifying the sorting of listings                             |
+| [0053](./adr/0053-editorial-purpose-tag.md)                        | Editorial Purpose Tag |
 | [0054](./adr/0054-selectable-presigned-storage-urls.md)            | Support for selectable presigned storage PUT URLs                          |
 | [0055](./adr/0055-fine-grained-auth-storage-backends.md)           | Support for Fine-Grained Authorisation on Storage Backends                 |
+| [0056](./adr/0056-roles-in-collections.md)                         | Roles in Collections |
 
 \* Note: ADR 0004a was the unintended result of a number clash in the early development of TAMS which wasn't caught before publication