Make `role` optional in collections, capture the same information elsewhere by samdbmg · Pull Request #225 · bbc/tams

samdbmg · 2026-07-10T12:23:06Z

Details

Adds an ADR exploring what role should be used for in collections, and concluding it should become optional
Makes the corresponding change to the API
...and examples
Adds an ADR considering where to capture the "editorial purpose" of a Source or Flow (something role has been used for), and corresponding appnote, tags and examples

Issue (if relevant)

GitHub Issue: Fixes #188
Also tracked as https://jira.dev.bbc.co.uk/browse/CLOUDFIT-5509

Related PRs

Replaces #173 since that PR had got rather messy!

Submitter PR Checks

PR completes task/fixes bug
API version has been incremented if necessary
ADR status has been updated, and ADR implementation has been recorded
Documentation updated (README, etc.)
PR added to Jira Issue (if relevant)
Follow-up stories added to Jira

Reviewer PR Checks

PR completes task/fixes bug
Design makes sense, and fits with our current code base
Code is easy to follow
PR size is sensible
Commit history is sensible and tidy

Info on PRs

The checks above are guidelines. They don't all have to be ticked, but they should all have been considered.

Adds an ADR considering the use of the `role` property, and recommending that for most cases properties of Flows and Sources should be stored on the objects themselves

Implements the proposal in ADR0047 by making `role` in a collection optional, and adding a `priority` field for sort order. sem-ver: feature

Also adds AppNote 0020 suggesting values

j616 · 2026-07-17T15:14:45Z

+        },
        "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": "An optional string describing the purpose of this element in the collection, primarily intended to be human-readable.",


Suggested change

"description": "An optional string describing the purpose of this element in the collection, primarily intended to be human-readable.",

"description": "The purpose of this element in the collection, primarily intended to be human-readable.",

NIT: optional and string feel redundant as they're in the machine readable part of the spec

j616 · 2026-07-17T15:16:48Z

        {
            "id": "4f79cfd1-c057-47f4-8e4d-1b126ca7bf34",
-            "role": "video"
+            "priority": 1


The example priorities seem to be unique to Flow type. Should they be unique among the collection? One use case is track ordering in an NLE, and I don't think they are always grouped by type? I also wonder if there are other interfaces that are more generic that might group everything together.

j616 · 2026-07-17T15:20:56Z

        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 the `priority` in `source_collection` and `flow_collection` not matching.


I think the conflicting "role" is still appropriate here? It's optional but still shouldn't conflict.

j616 · 2026-07-17T15:21:44Z

+* Option 2: Replace `role` with additional controlled fields
+* Option 3: Use `role` as editorial purpose, use other queries for Flow/Source properties
+* Option 4a: Capture editorial purpose elsewhere, use `role` as an optional label
+* Option 4b: Capture editorial purpose elsehwere, use `role` as an optional label, add a `priority` for sorting


Suggested change

* Option 4b: Capture editorial purpose elsehwere, use `role` as an optional label, add a `priority` for sorting

* Option 4b: Capture editorial purpose elsewhere, use `role` as an optional label, add a `priority` for sorting

j616 · 2026-07-17T15:46:27Z

+As Option 1a, using MPEG-DASH role values instead.
+
+MPEG-DASH contains a role attribute for an `AdaptationSet`, which describes the purose of that particular track.
+A number of values for that attribute are given in the specification (see ISO/IEC 23009-1:2022 section 5.8.5.5), covering the `main` content along with others such as `alternate`, `supplementary`, `commentary`, `description`, etc.


j616 · 2026-07-17T15:51:28Z

+
+An `editorial_purpose` tag is defined in [AppNote 0003: Tag Names](./0003-tag-names.md) to give a hint about what a particular Source or Flow contains and how it could be used.
+The tag's values are primarily intended to be human-readable and uncontrolled, however this list provides suggested values and their meanings to allow some commonality.
+Much like other tag definitions in TAMS, the list can be amended and will likely grow over time.


Nit: Do we want to provide any guidance on implemnentation specific values, akin to that in the tags listing? e.g. value starts with _<implementationName>....

j616 · 2026-07-17T15:52:20Z

+
+Status: **Proposed**
+
+Captures the editorial purpose of a piece of content, giving a hint about what it's for and what can be found inside.


Do we need to call out if these are single values, or if lists are allowed?

j616 · 2026-07-17T15:53:50Z

+| Name | Description |
+| ---- | ----------- |
+| `primary` | Primary, or default audio for a piece of content, e.g. that will be edited or distributed on to the audience. |
+| `descriptive video` | Audio description track, mixed with primary programme content for presentation to visually impaired audiences. |


NIT: The video values above use underscores, these have spaces. I suspect underscores should be preferred to reduce the potential need to escape values

j616 · 2026-07-17T15:56:26Z

+The tag's values are primarily intended to be human-readable and uncontrolled, however this list provides suggested values and their meanings to allow some commonality.
+Much like other tag definitions in TAMS, the list can be amended and will likely grow over time.
+
+## Editorial Purposes


Should we have a data section here with values for subtitles, in particular? I'm thinking sdh for Subtitles for the Deaf and Hard of Hearing, and transcript for subtitles without any descriptive info regarding sound effects etc.

samdbmg added 6 commits July 10, 2026 12:53

Add ADR0047 exploring use of role in collections

adfe445

Adds an ADR considering the use of the `role` property, and recommending that for most cases properties of Flows and Sources should be stored on the objects themselves

api: Make collection role optional, add priority

b655f02

Implements the proposal in ADR0047 by making `role` in a collection optional, and adding a `priority` field for sort order. sem-ver: feature

Rework examples for new usage of role

b10bc0f

Add ADR on storing editorial purpose as a tag

86dd561

appnote: Add editorial_purpose to list of tags

8d6a65c

Also adds AppNote 0020 suggesting values

Add examples of editorial purpose tag

33c126d

samdbmg requested a review from a team as a code owner July 10, 2026 12:23

This was referenced Jul 10, 2026

Role name description should be more specific #188

Open

Describe naming convention for role in collections #173

Closed

j616 reviewed Jul 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Make `role` optional in collections, capture the same information elsewhere#225

Make `role` optional in collections, capture the same information elsewhere#225
samdbmg wants to merge 6 commits into
mainfrom
sammg/adr/collection-roles

samdbmg commented Jul 10, 2026

Uh oh!

j616 Jul 17, 2026

Uh oh!

j616 Jul 17, 2026

Uh oh!

j616 Jul 17, 2026

Uh oh!

j616 Jul 17, 2026

Uh oh!

j616 Jul 17, 2026

Uh oh!

j616 Jul 17, 2026

Uh oh!

j616 Jul 17, 2026

Uh oh!

j616 Jul 17, 2026

Uh oh!

j616 Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	"description": "An optional string describing the purpose of this element in the collection, primarily intended to be human-readable.",
	"description": "The purpose of this element in the collection, primarily intended to be human-readable.",

	* Option 4b: Capture editorial purpose elsehwere, use `role` as an optional label, add a `priority` for sorting
	* Option 4b: Capture editorial purpose elsewhere, use `role` as an optional label, add a `priority` for sorting


		Status: Proposed

		Captures the editorial purpose of a piece of content, giving a hint about what it's for and what can be found inside.

Uh oh!

Conversation

samdbmg commented Jul 10, 2026

Details

Issue (if relevant)

Related PRs

Submitter PR Checks

Reviewer PR Checks

Info on PRs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants