How to handle protocol-specific parameters in renditions?

[bquinn]

Some rendition protocols have specific attributes that need to be specified, eg SRT caller / listener.

These can probably be handled in the URL, but for some properties we may want to include them as separate metadata, particularly so they can be displayed in UX for users without having to parse the URLs and extract query params.

Options:

1. Current approach - add properties for each parameter used by new protocols as they arise. This could lead to a bloated renditions property. 1b could be to see if we can set the JSON SSChema definition to allow for "SRT Rendition", "still image rendition" etc and each type would allow different properties to be used. And we could use a type property to choose between the SRTRenditionType and ImageRenditionType at the schema validation stage. This would mean we have a base rendition type and extensions to cover specific protocols. We're not sure whether this is possible in JSON Schema but could look into it. See https://json-schema.org/understanding-json-schema/reference/combining for details.
2. Have a sub-property under renditions that is a set of key-value pairs, which carries all parameters used by a media-specific rendition. 2a is to have an array of role/value properties, as we do in altIds. 2b is to have an object with key/value pairs. 2b is simpler but means that we can't serialise the object to protocol buffers etc.
3. Only include generic, protocol-agnostic parameters in the renditions object and require that everything else goes in the URI and must be parsed out by customers. A danger of this is that some protocol that we haven't yet analysed might not express everything it needs in the URL and we need another place to put it.

A problem with options 2 and 3 is that we aren't controlling the key list - someone could say "SRTListener" and someone else could say "SRT_Listener" and we can't tell whether they are right or wrong. A possibility could be to create a controlled vocabulary and maintain it as one of the NewsCodes vocabularies so it wouldn't need standards committee approval.

Another factor is that whatever we do should be serialisable into protobufs or Avro or CBOR etc. So would one or another option be more suitable? Probably the key/value pair options as they are simpler from a schema point of view.

And also we need to consider that we want to make it possible to use the JSON Schema as the payload validation part of an OpenAPI (Swagger) definition file. It only supports some JSON Schema features.

[bquinn]

Discussion on today's call: We seem to be talking ourselves into option 2a, given the considerations above. But a short-term possibility is to go for option 3 and leave out protocol-specific paramters for now, leaving us the option to go to option 2 by adding a parameters object to a future version of the spec.

[bquinn]

Example SRT URI: srt://gb2.pa-live.video:1002?latency=500&streamid=PA-LiveVideo-Channel1&passphrase=curve-xddrh-gyt

If we include this in the URI property, is this enough to fully specify an SRT feed?

[bquinn]

@bquinn to do a PR along the lines of option 3, taking out protocol-specific parameters, as a first approach to this problem.