Skip to content

8.2

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 10 Aug 16:26
8.2
34fb31b

Rendered v8.2 specification

What's Changed

  • Source collected by query parameter by @johnbilt in #183
    • Adds the collected_by_ids query parameter to Source and Flow listings, mirroring existing functionality in Webhooks
  • Make role optional in collections, capture the same information elsewhere by @samdbmg in #225
    • The use of the collection role parameter has been inconsistent and vague. An editorial_purpose tag with a managed list of recommended values has been specified. In conjunction with the above collected_by_ids query parameter, it is now possible to filter collected Sources/Flows by their purpose in a single request.
    • See AppNote0025 for more info
  • Add support for init segments in Flows by @j616 in #167
    • Enables the use of formats with initialisation segments, such as fMP4
    • See AppNote0024 for more info
  • Flow profiles by @johnbilt in #130
    • Adds support for the Profile resource, which may be used to populate Flow technical metadata, and to filter Flow listings
    • See AppNote0020 for more info
  • Add fine-grained auth support to Storage Backends by @j616 in #229
    • This has been achieved by adding tags to Storage Backends. These may also be used for other purposes beyond fine-grained auth
  • Support specification of presigned/non-presigned URLs on put_urls by @j616 in #222
    • Allows clients to select if returned put_urls should be pre-signed or not
    • Adds further clarity on authentication methods used by put_urls and get_urls
  • include_object_timerange improvements by @j616 in #215
    • Adds include_object_timerange option to webhooks, to match HTTP API
    • Always return object_timerange when include_object_timerange is true, replacing potentially behaviour where object_timerange would always be omitted if it matched the Flow Segments timerange
  • Explicitly specify default ordering of segments listing by @j616 in #223
    • The ordering of this listing has always been implied by the text of the reverse_order query parameter to be by timerange. This change makes that explicit.
  • Specify the sorting of resource listings by @j616 in #224
    • Defines the default sorting of all other resource listings, and provides a means for clients to specify the sorting where appropriate
  • Tag status review by @j616 in #227
    • Revises the status of tags in the tag listing
    • Notably, elevates flow_status to the core Flow metadata as the status attribute
  • Add AppNote0022 - Architectures for the transforming of media by @j616 in #181
    • Extended by: Add option for Transform on Request to AppNote0022 by @j616 in #182
    • Describe possible architectures for transforming media in TAMS, including automatic triggering of transcodes, and just-in-time transforming of media
  • Other changes:
    • Describe generation more clearly by @samdbmg in #212
    • Add missing return codes to webhooks by @j616 in #216
    • Make example code match adjacent diagram in README by @j616 in #218
    • Fix tag endpoints that should permit lists by @j616 in #238

Implementation considerations

This section calls out changes implementations may need/want to make. It also calls out behavior which has been clarified where developers should verify their implementations.

Warning

This release significantly re-factors the schemas in the TAMS specification.
Implementations which rely on the schema structures (e.g for automatic generation of libraries and data structures) should carefully review these changes.

Service Considerations
  • collected_by_ids query parameter
  • Make role optional in collections
    • Make this attribute optional on Source and Flow collections
    • Ensure that the ordering of Source and Flow collections is preserved
  • Add support for init segments
    • This PR affects multiple shemas and endpoints in the TAMS specification
    • See PR #167 for more info
  • Flow profiles
    • Add the /service/profiles endpoint tree
    • Add the profile attribute to Flows, including populating Flow technical metadata using it
    • Add the profile_id query parameter to /flows
    • See the diagram in ADR0047 for more information on how Flow schemas have been restructured
  • Storage Backend tags
    • Add tag attributes, and query parameters to Storage Backends
      • These tags should be set in deployment configurations
    • Add storage_backend_tag query parameters to Flow Segment and Object endpoints
    • If supporting AppNote0016 fine-grained auth, update auth logic to handle auth_classes tag on Storage Backend, and endpoints that serve storage PUT/GET URLs
  • Object instance PUT/GET URLs
  • include_object_timerange improvements
  • Resource listing sorting
    • Ensure Segments are sorted by timerange in GET /flows/{flowId}/segments responses, and sorting correctly takes into account timerange clusivity markers
    • Ensure default sorting of listings match specification
    • Ensure paging headers are all present and correct
    • reverse_order and sort_by query parameters with specificed fallback bahaviours to listing endpoints that provide them per the specification
  • status Flow parameter
  • AppNote0022 - Architectures for the transforming of media
    • Implementations may consider supporting built in transcode mechanisms, as specified in AppNote0022
  • Webhook return codes
    • Ensure webhook return codes are handled appropriately
  • Tag list values
    • Ensure all tag endpoints support list value type correctly
Client Considerations
  • collected_by_ids query parameter
    • Clients should expose this filter to users where applicable
    • Clients should consider using this to select Sources and Flows in place of making multiple queries to the parent and then child resources
  • Make role optional in collections
    • Prefer using the editorial_purpose tag over role to identify collected Source and Flows
    • Writing Clients should populate the editorial_purpose tag according to AppNote0025 where possible
    • Clients MUST NOT rely on the existance of role in collections
    • Consider using the sorting of collection items to preserve sorting of Source/Flows in UIs
  • Add support for init segments
    • Consider adding support for Flows using initialisation segments, for formats such as fMP4
    • Use the init_segments Flow attribute to identify Client-Flow compatibility
    • See AppNote and PR #167 for more info
  • Flow profiles
    • Consider using Profiles to consistently populate Flow metadata
    • Consider using the profile_id query parameter on /flows to filter Flows based on the Flow Profile they were created with
    • See AppNote0020 for more info
  • Storage backend tags
  • Object instance PUT/GET URLs
  • include_object_timerange improvements
  • Resource listing sorting
    • Consider using sort_by query parameter to specify sorting of listings, on endpoints where it is available
  • status Flow parameter
    • Replace usage of the flow_status tag with the Flow status parameter
    • Consider maintaining the deprecated flow_status tag as a fallback
  • AppNote0022 - Architectures for the transforming of media
    • Write Client implementations may consider supporting the trigger_transcode tag, as specified in AppNote0022
    • Transform/transcode Clients may consider conforming to the architectures specified in AppNote0022
  • generation Flow parameter
    • Ensure generation is set appropriately per the advice in the spec
  • Webhook return codes
    • Ensure webhook clients set HTTP return codes appropriately

Full Changelog: 8.1...8.2

Contributors

j616, samdbmg, and johnbilt
Assets 2
Loading