Create or Replace Flow

Create or replace the Flow metadata.

Clients should aim to populate as many of the Flow metadata fields as possible and practical. The fewer parameters that are set, the higher the likelihood that reading clients will have to retrieve the media to determine technical metadata to e.g. configure decoders.

Some parameters may be ignored/overridden by service implementations. This is to enable the Flow json-blob to be re-used with no/minimal editing in various use cases. Such parameters are called out in their description.

Service implementations SHOULD verify that Flow metadata is compatible with the associated Source. 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 role or ordering in source_collection and flow_collection not matching. It may also be possible for service implementations to detect some instances where multiple Flows should not be considered of the same Source, such as audio Flows with different numbers of tracks. Further guidance on when Flows/Sources may be considered the same/different may be found in the Practical Guidance for Media section of AMWA MS-04.

Flows can be created either by directly supplying all the required technical metadata or by referencing an existing Profile in the store.
When using a Profile, the Service Implementation will populate the Flow's technical parameters (format, codec, essence_parameters etc.) from that profile, along with the metadata provided.
It is up to the Service Implementation whether this is normalised on the Flow creation or on read.

When creating a flow using a Profile it is not possible to override any specific fields as this would invalidate the link to the Profile.
Supplying a Profile ID and any technical metadata should result in a 400 validation error.

When updating a Flow created using a profile then consideration needs to be given to the fields which were inherited. For the standard fields (eg label, description, tags) which form part of the common Flow metadata and provided directly regardless of the Profile then these can be updated through the standard process.

In the scenario where the technical characteristics do need to be changed on a Flow created from a Profile then it is necessary to remove the link to the Profile as part of the update since it will no longer match the Profile entirely. This is achieved by means of setting the profile_id field to an empty string as part of the update. This will then break the link to the Profile and allow the store to update the technical parameters. It should be noted that searching for Flows using a Profile will no longer include the updated Flow since it no longer matches or is linked to the Profile.