String enum strategy

[garethsb]

To be considered by @AMWA-TV/nmos-architecture-review group and the NMOS Stream Mappings activity group:

Flow string attributes like profile and level have enumerated values that are open to extensibility for two reasons:

• Adding support for a new media type with completely different acceptable values for these attributes
• Adding new profiles and levels for existing media types, e.g. in amendments to existing standards as has happened for MPEG-2, MPEG-4, JPEG XS (see Proposed changes for BCP-006 #38 (comment))

The schemas included in the parameter register wouldn't be very useful if they allowed any string value for these attributes, so perhaps there's nothing we can do about the latter point, other than quickly update schemas when that happens?

It probably is possible to make the set of permitted enum values depend on the Flow media_type value, though that may need a more recent version of JSON Schema than draft-04?

[garethsb]

It probably is possible to make the set of permitted enum values depend on the Flow media_type value, though that may need a more recent version of JSON Schema than draft-04?

Using draft-07: https://www.jsonschemavalidator.net/s/PqKGCvsE

Which could be transformed to draft-04 using Boolean implication, but gets even more verbose...
https://json-schema.org/understanding-json-schema/reference/conditionals.html#id7

Either way, not going to be very elegant to combine with the main flow_video_register.json or sender_register.json schemas...

[garethsb]

Here's a stab at it...

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes Video Flow additional and extensible attributes defined in the NMOS Parameter Registers.",
  "title": "Video Flow resource",
  // Base definition schema and all of the media type constraints schemas must validate successfully
  "allOf": [
    {
      "description": "Base definition of registered properties",
      "properties": {
        "bit_rate": {
          "description": "Bit rate, in kilobits/second. Integer value expressed in units of 1000 bits per second, rounding up.",
          "type": "integer"
        },
        "profile": {
          "description": "Profile. Indicates the subset of coding tools that are in use, as defined for the Flow media type.",
          "type": "string"
          // no enum here
        },
        // other properties
      }
    },
    {
      // This schema says "if the media type is video/jxsv, then additional property value constraints apply"
      // implemented as "either the media type is not video/jxsv or the additional property value constraints apply"
      "anyOf": [
        {
          "not": {
            "properties": {
              "media_type": {
                "enum": [
                  "video/jxsv"
                ]
              }
            }
          }
        },
        // or on one line:
        // { "not": { "properties": { "media_type": { "enum": [ "video/jxsv" ] } } } },
        {
          "description": "Definition of constrained property values for video/jxsv",
          "properties": {
            "profile": {
              "enum": [
                "High444.12",
                "Main444.12",
                "Light444.12",
                "Main422.10",
                "Light422.10",
                // etc.
              ]
            },
            "level": {
              "enum": [
                "1k-1",
                "Bayer2k-1",
                "2k-1",
                "Bayer4k-1",
                "4k-1",
                "Bayer8k-1",
                "4k-2",
                // etc.
              ]
            }
          }
        }
      ]
    },
    {
      "anyOf": [
        {
          "not": {
            "properties": {
              "media_type": {
                "enum": [
                  "video/cats"
                ]
              }
            }
          }
        },
        {
          "properties": {
            "profile": {
              "enum": [
                "meow",
                "purr",
                "hiss",
                "yowl"
              ]
            }
          }
        }
      ]
    },
    // other media_type constraints schemas
  ]
}

There are pros and cons to factoring that into several files like:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Describes Video Flow additional and extensible attributes defined in the NMOS Parameter Registers.",
  "title": "Video Flow resource",
  "allOf": [
    { "$ref": "flow_video_base_register.json" },
    {
      "anyOf": [
        { "not": { "properties": { "media_type": { "enum": [ "video/jxsv" ] } } } },
        { "$ref": "flow_video_jxsv_register.json" }
      ]
    },
    {
      "anyOf": [
        { "not": { "properties": { "media_type": { "enum": [ "video/cats" ] } } } },
        { "$ref": "flow_video_cats_register.json" }
      ]
    },
    // etc.
  ]
}

[garethsb]

Of course this technique won't work to validate codec-dependent transport attributes that are held on the Sender, e.g. packet_transmission_mode which we're defining in #43 but consider reusing with different enumerated values for e.g. H.264 (AVC). 🤔