Make label mandatory when registering uncontrolled Object Instances

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:

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"
                     }
                 }

api/schemas/objects-instances-post.json

@@ -22,15 +22,16 @@
             "title": "Uncontrolled instance",
             "type": "object",
             "required": [
-                "url"
+                "url",
+                "label"
             ],
             "properties": {
                 "url": {
                     "description": "A URL to which a GET request can be made to directly retrieve the contents of the media object. Clients should include credentials if the provide URL is on the same origin as the API endpoint",
                     "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"
                 }
             }

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

docs/adr/0042-uncontrolled-object-instance-labels.md

@@ -0,0 +1,35 @@
+---
+status: "accepted"
+---
+# 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
+
+Implemented by <https://github.com/bbc/tams/pull/155>
+
+## 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, 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
+
+* 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