From 85ae3849ba6aeadb6edc4a467f52e2f4c4692161 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Mon, 13 Oct 2025 15:11:03 +0100 Subject: [PATCH 1/5] Make `label` mandatory when registering uncontrolled Object Instances sem-ver: api-break --- api/TimeAddressableMediaStore.yaml | 16 ++++----- api/schemas/flow-segment-post.json | 5 +-- api/schemas/objects-instances-post.json | 5 +-- ...042-uncontrolled-object-instance-labels.md | 33 +++++++++++++++++++ 4 files changed, 47 insertions(+), 12 deletions(-) create mode 100644 docs/adr/0042-uncontrolled-object-instance-labels.md diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml index 065f3d8e..3de9b5c2 100644 --- a/api/TimeAddressableMediaStore.yaml +++ b/api/TimeAddressableMediaStore.yaml @@ -1785,7 +1785,7 @@ paths: A comma separated list of labels of Flow Segment `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Flow Segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Flow Segment `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -1795,7 +1795,7 @@ paths: description: | A comma separated list of `storage_id`s of Flow Segment `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Flow Segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Flow Segment `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -1912,7 +1912,7 @@ paths: A comma separated list of labels of Flow Segment `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Flow Segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Flow Segment `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -1922,7 +1922,7 @@ paths: description: | A comma separated list of `storage_id`s of Flow Segment `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Flow Segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Flow Segment `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -2194,7 +2194,7 @@ paths: A comma separated list of labels of Media Object `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Media object `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Media object `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. @@ -2205,7 +2205,7 @@ paths: description: | A comma separated list of `storage_id`s of Media Object `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Media object `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Media object `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the `service/storage-backends` endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -2291,7 +2291,7 @@ paths: A comma separated list of labels of Media Object `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Media object `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Media object `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. @@ -2302,7 +2302,7 @@ paths: description: | A comma separated list of `storage_id`s of Media Object `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Media object `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Media object `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the `service/storage-backends` endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: diff --git a/api/schemas/flow-segment-post.json b/api/schemas/flow-segment-post.json index 31a86a51..9bbdf0a6 100644 --- a/api/schemas/flow-segment-post.json +++ b/api/schemas/flow-segment-post.json @@ -55,7 +55,8 @@ "type": "object", "required": [ - "url" + "url", + "label" ], "properties": { @@ -66,7 +67,7 @@ }, "label": { - "description": "Label identifying this URL. Service implementations should reject any requests using labels that are already associated with Storage Backends. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter.", + "description": "Label identifying this URL. Service implementations should reject any requests using labels that are already associated with Storage Backends. Service implementations should reject any requests containing multiple `get_urls` with the same `label`.", "type": "string" } } diff --git a/api/schemas/objects-instances-post.json b/api/schemas/objects-instances-post.json index 74cc4f46..e4b8e81c 100644 --- a/api/schemas/objects-instances-post.json +++ b/api/schemas/objects-instances-post.json @@ -22,7 +22,8 @@ "title": "Uncontrolled instance", "type": "object", "required": [ - "url" + "url", + "label" ], "properties": { "url": { @@ -30,7 +31,7 @@ "type": "string" }, "label": { - "description": "Label identifying this Media Object instance. Service implementations should reject any requests using labels that are already associated with Storage Backends. If the 'label' is not set then this instance can't be filtered for using the 'accept_get_urls' API query parameter.", + "description": "Label identifying this Media Object instance. Service implementations should reject any requests using labels that are already associated with Storage Backends.", "type": "string" } } diff --git a/docs/adr/0042-uncontrolled-object-instance-labels.md b/docs/adr/0042-uncontrolled-object-instance-labels.md new file mode 100644 index 00000000..547d043f --- /dev/null +++ b/docs/adr/0042-uncontrolled-object-instance-labels.md @@ -0,0 +1,33 @@ +--- +status: "proposed" +--- +# Make `label` Mandatory for Uncontrolled Object Instances + +## Context and Problem Statement + +In [ADR0038](./0038-improved-storage-management.md), we added endpoints under `/objects` to facilitate the management of multiple Object Instances. Since accepting that ADR, we have received feedback that `label` being optional for uncontrolled Object Instances makes it unclear how such Object Instances should be managed. This ADR seeks to remedy that by making `label` mandatory when registering new uncontrolled Object Instances. + +## Considered Options + +* Option 1: Leave `label` as optional when registering uncontrolled Object Instances +* Option 2: Make `label` mandatory when registering uncontrolled Object Instances + +## Decision Outcome + +Chosen Option 2: Make `label` mandatory when registering uncontrolled Object Instances + +### Implementation + +{Once the proposal has been implemented, add a link to the relevant PRs here} + +## Pros and Cons of the Options + +### Option 1: Leave `label` as optional when registering uncontrolled Object Instances + +* Neutral, because this avoids a breaking change to a lesser used part of the API +* Bad, because mechanisms for managing uncontrolled Object Instances without labels are undefined + +### Option 2: Make `label` mandatory when registering uncontrolled Object Instances + +* Good, because mechanisms for managing all Object Instances will be defined +* Neutral, because this is a breaking change to a lesser used part of the API that will be released alongside the existing changes to Object management mechanisms From 7c0a1517a97cfac8313203e9bd19269206d2eb52 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Mon, 13 Oct 2025 15:14:16 +0100 Subject: [PATCH 2/5] Fix linting --- docs/adr/0042-uncontrolled-object-instance-labels.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/adr/0042-uncontrolled-object-instance-labels.md b/docs/adr/0042-uncontrolled-object-instance-labels.md index 547d043f..d93f26e3 100644 --- a/docs/adr/0042-uncontrolled-object-instance-labels.md +++ b/docs/adr/0042-uncontrolled-object-instance-labels.md @@ -5,7 +5,9 @@ status: "proposed" ## Context and Problem Statement -In [ADR0038](./0038-improved-storage-management.md), we added endpoints under `/objects` to facilitate the management of multiple Object Instances. Since accepting that ADR, we have received feedback that `label` being optional for uncontrolled Object Instances makes it unclear how such Object Instances should be managed. This ADR seeks to remedy that by making `label` mandatory when registering new uncontrolled Object Instances. +In [ADR0038](./0038-improved-storage-management.md), we added endpoints under `/objects` to facilitate the management of multiple Object Instances. +Since accepting that ADR, we have received feedback that `label` being optional for uncontrolled Object Instances makes it unclear how such Object Instances should be managed. +This ADR seeks to remedy that by making `label` mandatory when registering new uncontrolled Object Instances. ## Considered Options From d0bef9bf25425db05aa69d5b3b6cb4809baa01c8 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Tue, 14 Oct 2025 15:53:31 +0100 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Sam Mesterton-Gibbons --- api/TimeAddressableMediaStore.yaml | 8 ++++---- docs/adr/0042-uncontrolled-object-instance-labels.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml index 3de9b5c2..725c4134 100644 --- a/api/TimeAddressableMediaStore.yaml +++ b/api/TimeAddressableMediaStore.yaml @@ -2194,7 +2194,7 @@ paths: A comma separated list of labels of Media Object `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Media object `get_urls` with no label will only be returned if `accept_get_urls` is omitted. + Media Object `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. @@ -2205,7 +2205,7 @@ paths: description: | A comma separated list of `storage_id`s of Media Object `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Media object `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. + Media Object `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the `service/storage-backends` endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -2291,7 +2291,7 @@ paths: A comma separated list of labels of Media Object `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Media object `get_urls` with no label will only be returned if `accept_get_urls` is omitted. + Media Object `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. @@ -2302,7 +2302,7 @@ paths: description: | A comma separated list of `storage_id`s of Media Object `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Media object `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. + Media Object `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the `service/storage-backends` endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: diff --git a/docs/adr/0042-uncontrolled-object-instance-labels.md b/docs/adr/0042-uncontrolled-object-instance-labels.md index d93f26e3..ee0d412e 100644 --- a/docs/adr/0042-uncontrolled-object-instance-labels.md +++ b/docs/adr/0042-uncontrolled-object-instance-labels.md @@ -20,14 +20,14 @@ Chosen Option 2: Make `label` mandatory when registering uncontrolled Object Ins ### Implementation -{Once the proposal has been implemented, add a link to the relevant PRs here} +Implemented by ## Pros and Cons of the Options ### Option 1: Leave `label` as optional when registering uncontrolled Object Instances * Neutral, because this avoids a breaking change to a lesser used part of the API -* Bad, because mechanisms for managing uncontrolled Object Instances without labels are undefined +* Bad, because mechanisms for managing uncontrolled Object Instances without labels are undefined, because there is no natural key by which to identify a particular Object Instance - for example `DELETE /objects/{objectId}/instances` requires a label (or storage ID) ### Option 2: Make `label` mandatory when registering uncontrolled Object Instances From 8a8eae64f438d8b192cdf0c1711a80de509ade14 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Mon, 20 Oct 2025 15:43:56 +0100 Subject: [PATCH 4/5] Mark ADR0042 as accepted --- docs/adr/0042-uncontrolled-object-instance-labels.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/0042-uncontrolled-object-instance-labels.md b/docs/adr/0042-uncontrolled-object-instance-labels.md index ee0d412e..a76f3970 100644 --- a/docs/adr/0042-uncontrolled-object-instance-labels.md +++ b/docs/adr/0042-uncontrolled-object-instance-labels.md @@ -1,5 +1,5 @@ --- -status: "proposed" +status: "accepted" --- # Make `label` Mandatory for Uncontrolled Object Instances From 5659e5ae24d9f05950ed2d82117c502d23760ca0 Mon Sep 17 00:00:00 2001 From: James Sandford Date: Mon, 20 Oct 2025 15:49:28 +0100 Subject: [PATCH 5/5] Add ADR0042 to listing --- docs/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/README.md b/docs/README.md index 8d760cfb..38706d3f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -74,5 +74,6 @@ For more information on how we use ADRs, see [here](./adr/README.md). | [0039](./adr/0039-remove-pre-actions.md) | Proposal to remove pre-actions from storage allocation response | | [0040](./adr/0040-tag-usability-enhancements.md) | Tag Usability Enhancements | | [0041](./adr/0041-require-explicit-framerate.md) | Requiring explicit frame rates | +| [0042](./adr/0042-uncontrolled-object-instance-labels.md) | Make `label` Mandatory for Uncontrolled Object Instances | \* Note: ADR 0004a was the unintended result of a number clash in the early development of TAMS which wasn't caught before publication