From 952ccf9d550a8d275f05002f49a0633c3f1c9ddc Mon Sep 17 00:00:00 2001 From: James Sandford Date: Fri, 10 Jul 2026 16:43:15 +0100 Subject: [PATCH 1/7] Elevate `flow_status` tag to core specification --- docs/README.md | 2 +- docs/adr/0006-flow-status.md | 5 ++++- docs/appnotes/0003-tag-names.md | 4 +++- docs/appnotes/0022-transform-architectures.md | 10 +++++----- 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/README.md b/docs/README.md index 8941907b..b4de0b8f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -46,7 +46,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 | diff --git a/docs/adr/0006-flow-status.md b/docs/adr/0006-flow-status.md index fc429bb7..10606c4b 100644 --- a/docs/adr/0006-flow-status.md +++ b/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. diff --git a/docs/appnotes/0003-tag-names.md b/docs/appnotes/0003-tag-names.md index e68b421c..94f26455 100644 --- a/docs/appnotes/0003-tag-names.md +++ b/docs/appnotes/0003-tag-names.md @@ -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. diff --git a/docs/appnotes/0022-transform-architectures.md b/docs/appnotes/0022-transform-architectures.md index 73e7907e..b88f7399 100644 --- a/docs/appnotes/0022-transform-architectures.md +++ b/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. From f8031f93d8706bee428bd4bbb24ca4788cab8397 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Fri, 10 Jul 2026 16:44:14 +0100 Subject: [PATCH 2/7] Elevate `auth_classes` tags to Proposed --- docs/appnotes/0003-tag-names.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/appnotes/0003-tag-names.md b/docs/appnotes/0003-tag-names.md index 94f26455..75f42487 100644 --- a/docs/appnotes/0003-tag-names.md +++ b/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. @@ -267,7 +267,7 @@ 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. From b02a71eafa17e3c0bcbc36344f2c21d02ca8a2e2 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Fri, 10 Jul 2026 16:44:50 +0100 Subject: [PATCH 3/7] Elevate `language_code` tags to Proposed --- docs/appnotes/0003-tag-names.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/appnotes/0003-tag-names.md b/docs/appnotes/0003-tag-names.md index 75f42487..cf30f910 100644 --- a/docs/appnotes/0003-tag-names.md +++ b/docs/appnotes/0003-tag-names.md @@ -160,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. @@ -284,7 +284,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. From 8b4bbe4661f06f3155b22790267b31434affc253 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Fri, 10 Jul 2026 16:52:35 +0100 Subject: [PATCH 4/7] Deprecate `originating_id` and `originating_timerange` tags --- docs/appnotes/0003-tag-names.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/appnotes/0003-tag-names.md b/docs/appnotes/0003-tag-names.md index cf30f910..2af286ec 100644 --- a/docs/appnotes/0003-tag-names.md +++ b/docs/appnotes/0003-tag-names.md @@ -184,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). @@ -193,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). From 85fda1d823bbb4c38cdc1509dcf13b628c3f0be1 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Fri, 10 Jul 2026 16:54:25 +0100 Subject: [PATCH 5/7] Mark `hls_exclude` and `hls_segments` tags as Implementation specific to discourage use --- docs/appnotes/0003-tag-names.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/appnotes/0003-tag-names.md b/docs/appnotes/0003-tag-names.md index 2af286ec..8cdae05c 100644 --- a/docs/appnotes/0003-tag-names.md +++ b/docs/appnotes/0003-tag-names.md @@ -120,7 +120,7 @@ Known values: ### hls_exclude -Status: **Experimental** +Status: **Implementation specific** Used in the TAMS demonstration at NAB 2025. @@ -130,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. @@ -278,7 +278,7 @@ 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. From 97ede9f08f4dd3d3b6b4d52a847cf44538a6fb94 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Tue, 14 Jul 2026 15:23:39 +0100 Subject: [PATCH 6/7] Add query parameter to filter on Flow `status` --- api/TimeAddressableMediaStore.yaml | 10 ++++++++++ api/schemas/flow-common.json | 3 +++ api/schemas/flow-status.json | 11 +++++++++++ 3 files changed, 24 insertions(+) create mode 100644 api/schemas/flow-status.json diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml index 03cb0e46..8884f54a 100644 --- a/api/TimeAddressableMediaStore.yaml +++ b/api/TimeAddressableMediaStore.yaml @@ -1204,6 +1204,11 @@ paths: - created - metadata_updated - label + - 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: | @@ -1331,6 +1336,11 @@ paths: - created - metadata_updated - label + - 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: | diff --git a/api/schemas/flow-common.json b/api/schemas/flow-common.json index 05a163be..806d246d 100644 --- a/api/schemas/flow-common.json +++ b/api/schemas/flow-common.json @@ -59,6 +59,9 @@ "type": "string", "format": "date-time" }, + "status": { + "$ref": "flow-status.json" + }, "read_only": { "description": "If set to 'true', service implementations SHOULD reject client requests to update Flow metadata (other than the read_only property), and Flow Segments. Service implementations should also reject requests to the [`/flows/{flowId}/storage`](#/operations/POST_flows-flowId-storage) endpoint for the Flow, and requests to delete the Flow.", "type": "boolean" diff --git a/api/schemas/flow-status.json b/api/schemas/flow-status.json new file mode 100644 index 00000000..a9aa0585 --- /dev/null +++ b/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" + ] +} From 640f55f8400eab61ed0924550342b8007418bbac Mon Sep 17 00:00:00 2001 From: James Sandford Date: Thu, 23 Jul 2026 15:23:41 +0100 Subject: [PATCH 7/7] Add note on automation of Flow status lifecycle --- api/schemas/flow-status.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/schemas/flow-status.json b/api/schemas/flow-status.json index a9aa0585..d04bfd5c 100644 --- a/api/schemas/flow-status.json +++ b/api/schemas/flow-status.json @@ -1,6 +1,6 @@ { "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.", + "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. Service Implementers MAY consider adding more active management of the `status` of Flows to mitigate Clients failing to tidy up on completion/failure, as part of more general lifecycle management capability, in line with the approach described for [retention management](https://github.com/bbc/tams/blob/main/docs/appnotes/0019-implementing-retention-management.md). But Clients should not assume such capability.", "type": "string", "enum": [ "awaiting_content",