Tag status review

api/TimeAddressableMediaStore.yaml

@@ -835,6 +835,11 @@ paths:
           description: Filter on Flows that have the given label.
           schema:
             type: string
+        - name: status
+          in: query
+          description: Filter on Flows on the value of `status`.
+          schema:
+            $ref: schemas/flow-status.json
         - name: tag.{name}
           in: query
           description: |
@@ -927,6 +932,11 @@ paths:
           description: Filter on Flows that have the given label.
           schema:
             type: string
+        - name: status
+          in: query
+          description: Filter on Flows on the value of `status`.
+          schema:
+            $ref: schemas/flow-status.json
         - name: tag.{name}
           in: query
           description: |

api/schemas/flow-core.json

@@ -81,6 +81,10 @@
             "type": "integer",
             "minimum": 0
         },
+        "status": {
+            "description": "The current ingest status of a Flow. Available values are as follows. `awaiting_content` - Flow is expecting, but not currently receiving content. `ingesting` - Content is currently being ingested. `replication_in_progress` - Content is currently being ingested to this Flow from another Service Instance via a replication process. `closed_complete` - Flow is complete and will not receive any more content. NOTE: Because this parameter is maintained/updated by a Client, the value of this parameter is only indicative and not authoritative. If the Client ingesting the content becomes unavailable, it may leave this parameter in an incorrect state. Clients should aim to tidy up this state appropriately once they recover.",
+            "$ref": "flow-status.json"
+        },
         "segment_duration": {
             "description": "The target Flow Segment duration in seconds. The duration for each Segment may vary around this target value. See also the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote for how this property can be used to calculate buffer sizes.",
             "type": "object",

api/schemas/flow-status.json

@@ -0,0 +1,11 @@
+{
+    "title": "Flow Status",
+    "description": "The current ingest status of a Flow. Available values are as follows. `awaiting_content` - Flow is expecting, but not currently receiving content. `ingesting` - Content is currently being ingested. `replication_in_progress` - Content is currently being ingested to this Flow from another Service Instance via a replication process. `closed_complete` - Flow is complete and will not receive any more content. NOTE: Because this parameter is maintained/updated by a Client, the value of this parameter is only indicative and not authoritative. If the Client ingesting the content becomes unavailable, it may leave this parameter in an incorrect state. Clients should aim to tidy up this state appropriately once they recover.",
+    "type": "string",
+    "enum": [
+        "awaiting_content",
+        "ingesting",
+        "replication_in_progress",
+        "closed_complete"
+    ]
+}

docs/README.md

@@ -45,7 +45,7 @@ For more information on how we use ADRs, see [here](./adr/README.md).
 | [0004](./adr/0004-content-deletion.md)                             | Deletion of Content and IDs                                                |
 | [0004a](./adr/0004a-ancestry-relationships.md)*                    | Flow and Source References                                                 |
 | [0005](./adr/0005-flow-read-write-permissions.md)                  | Flow Read-Write Permissions                                                |
-| [0006](./adr/0006-flow-status.md)                                  | Flow Update Status                                                         |
+| [0006](./adr/0006-flow-status.md)                                  | Flow Update Status - **Deprecated**                                        |
 | [0007](./adr/0007-use-timerange-in-flow-segments.md)               | Use Timerange in Flow Segments                                             |
 | [0008](./adr/0008-move-flow-parameters-into-a-sub-property.md)     | Move Flow Parameters into a sub-property                                   |
 | [0009](./adr/0009-allow-segment-overlap.md)                        | Allow Segments to Overlap                                                  |

docs/adr/0006-flow-status.md

@@ -1,8 +1,11 @@
 ---
-status: "accepted"
+status: "deprecated"
 ---
 # Flow Update Status
 
+> [!CAUTION]
+> The tag described in the [More Information](#tamsaws-workshop-discussion---13th-february-2024) section of this ADR has been elevated to the core specification as the `status` [Flow parameter](https://bbc.github.io/tams/main/index.html#/operations/GET_flows-flowId)
+
 ## Context and Problem Statement
 
 Flow readers, and media players in particular, operate in different modes based on whether the Flow content they are consuming is expected to be updated or not.

docs/appnotes/0003-tag-names.md

@@ -51,7 +51,7 @@ The tags below are marked with the following statuses:
 
 ### auth_classes
 
-Status: **Experimental**
+Status: **Proposed**
 
 Suggested as a way to build lightweight Attribute-based Access Control in [AppNote0016: Authorisation in TAMS workflows](./0016-authorisation-in-tams-workflows.md).
 A comma seperated list of auth classes used to derive permissions on the Flow.
@@ -99,10 +99,12 @@ Example: For a Flow with `metadata_updated` of `2023-09-14T09:45:26Z`, `segments
 
 ### flow_status
 
-Status: **Proposed**
+Status: **Deprecated**
 
 Proposed in [ADR0006 - Flow Update Status](../adr/0006-flow-status.md).
 
+Replaced by the `status` field in Flow metadata.
+
 Signals the current status of a Flow.
 
 **NOTE:** Because these tags are maintained updated by a service other than the TAMS store, the value of this tag is only indicative and not authoritative.
@@ -118,7 +120,7 @@ Known values:
 
 ### hls_exclude
 
-Status: **Experimental**
+Status: **Implementation specific**
 
 Used in the TAMS demonstration at NAB 2025.
 
@@ -128,7 +130,7 @@ Defaults to `false` if the tag is not set.
 
 ### hls_segments
 
-Status: **Experimental**
+Status: **Implementation specific**
 
 Used in the TAMS demonstration at IBC 2024.
 
@@ -158,7 +160,7 @@ Known values:
 
 ### language_code
 
-Status: **Experimental**
+Status: **Proposed**
 
 The language of the Flow as an [ISO 639:2023 Set 3 code](https://iso639-3.sil.org/code_tables/639/data/all) (This replaces ISO 639-3, but is still tracked by the linked website which uses the old naming).
 Where possible, the equivalent Source tag should also be set.
@@ -182,7 +184,9 @@ Oldest Segments that take the duration over the specified duration will be delet
 
 ### originating_id
 
-Status: **Proposed**
+Status: **Deprecated**
+
+Instead, use `first_referenced_by_flow` in the Object metadata to determine the originating Flow(s) for content.
 
 Proposed in [ADR0004a - Flow and Source References](../adr/0004a-ancestry-relationships.md).
 
@@ -191,7 +195,9 @@ Contains the ID of the originating Flow.
 
 ### originating_timerange
 
-Status: **Proposed**
+Status: **Deprecated**
+
+Instead, use `first_referenced_by_flow` in the Object metadata to determine the originating Flow(s) for content, and the Segment metadata or the originating and destination Flows to determine the mapping of Objects between their respective timelines.
 
 Proposed in [ADR0004a - Flow and Source References](../adr/0004a-ancestry-relationships.md).
 
@@ -265,14 +271,14 @@ Actual Segment rates/durations may vary.
 
 ### auth_classes
 
-Status: **Experimental**
+Status: **Proposed**
 
 Suggested as a way to build lightweight Attribute-based Access Control in [AppNote0016: Authorisation in TAMS workflows](./0016-authorisation-in-tams-workflows.md).
 A comma separated list of auth classes used to derive permissions on the Source.
 
 ### hls_exclude
 
-Status: **Experimental**
+Status: **Implementation specific**
 
 Used in the TAMS demonstration at NAB 2025.
 
@@ -282,7 +288,7 @@ Defaults to `false` if the tag is not set.
 
 ### language_code
 
-Status: **Experimental**
+Status: **Proposed**
 
 The language of the Source as an [ISO 639-3 code](https://iso639-3.sil.org/code_tables/639/data/all).
 Where possible, the equivalent Flow tag should also be set.

docs/appnotes/0022-transform-architectures.md

@@ -57,9 +57,9 @@ In the case of the 3rd-party API approach, a client makes a request to the the t
 The transform client will then register a new Flow, and provide the Flow ID to the requesting client.
 
 The transform client will transform each Segment in the originating Flow, and write the resultant media back to TAMS against the destination Flow.
-The transform client should set the destination Flow's `flow_status` tag to `awaiting_content` on initial registration, `ingesting` on first write of a Segment, and `closed_complete` once the transform is complete.
+The transform client should set the destination Flow's `status` parameter to `awaiting_content` on initial registration, `ingesting` on first write of a Segment, and `closed_complete` once the transform is complete.
 
-Where the originating Flow has a `flow_status` of `ingesting`, the transform client may need to subscribe to `flows/segments_added` webhook events for the originating Flow and transform new Segments as they become available.
+Where the originating Flow has a `status` of `ingesting`, the transform client may need to subscribe to `flows/segments_added` webhook events for the originating Flow and transform new Segments as they become available.
 
 The transform client may be designed such that all Segments are transformed in parallel, allowing for faster than real-time transforms in many cases.
 
@@ -88,10 +88,10 @@ The requesting client will create a new Flow against the existing Source with th
 The creation of this Flow will result in an event that will be received by the transcode service configured above.
 
 The transcode service will transcode each Segment in the originating Flow, based on the technical properties of the destination Flow, and write the resultant media back to TAMS against the destination Flow.
-The transcode service should set the destination Flow's `flow_status` tag to `awaiting_content` on initial registration, `ingesting` on first write of a Segment, and `closed_complete` once the transcode is complete.
+The transcode service should set the destination Flow's `status` parameter to `awaiting_content` on initial registration, `ingesting` on first write of a Segment, and `closed_complete` once the transcode is complete.
 When the transcode is complete, the `trigger_transcode` tag should be removed from the originating Flow.
 
-Where the originating Flow has a `flow_status` of `ingesting`, the transcode service may need to subscribe to `flows/segments_added` webhook events for the originating Flow and transcode new Segments as they become available.
+Where the originating Flow has a `status` of `ingesting`, the transcode service may need to subscribe to `flows/segments_added` webhook events for the originating Flow and transcode new Segments as they become available.
 
 The transcode service may be designed such that all Segments are transcoded in parallel, allowing for faster than real-time transcodes in many cases.
 
@@ -123,7 +123,7 @@ These Objects will have instances that are "virtual".
 That is to say that the Objects do not exist on disk.
 When a GET request is performed with the instance URL, the Service will perform the transcode to create the Object and return it, as if the media existed on disk.
 
-Where the originating Flow has a `flow_status` of `ingesting`, new Virtual Objects and corresponding Segments should be created as new originating Segments are registered.
+Where the originating Flow has a `status` of `ingesting`, new Virtual Objects and corresponding Segments should be created as new originating Segments are registered.
 
 Clients may wish to initiate a transcode without actually downloading the content.
 For example, to ensure content is available in an appropriate format ahead of playout into broadcast.