ADR: TDF spec version enforcement

[biscoe916]

Context

The Base ZTDF specification includes a yet to be implemented tdf_spec_version field. This version field is sufficient in the context of of the OpenTDF ecosystem, but we also want to support 3rd parties to "extend" the specification to accommodate their unique use-cases. For example, a 3rd party who is leveraging OpenTDF may want to require their applications require the inclusion of specific assertions, or attributes. This ADR proposes two potential approaches for how we might allow the inclusion of version information for vendor specific spec requirements.

Current State

Below is a snippet of the payload portion of a ZTDF's manifest.

    "payload": {
        "type": "reference",
        "url": "0.payload",
        "protocol": "zip",
        "isEncrypted": true,
        "mimeType": "text/plain",
        "tdf_spec_version": "1.0.0" // Made up version as this isn't implemented yet
    }

Option 1 - Separate version fields.

Use a separate field for vendor specific versioning.

    "payload": {
        "type": "reference",
        "url": "0.payload",
        "protocol": "zip",
        "isEncrypted": true,
        "mimeType": "text/plain",
        "tdf_spec_version": "1.0.0", // Made up version as this isn't implemented yet
        "vendor_version": "0.2.1"
    }

Advantages

• Clear separation of concerns
• Independent versioning lifecycles
• Full semver support for both versions
• Simple version comparison logic
• Explicit and self-documenting
• Easy to add additional version fields if needed

Disadvantages

• Requires an update to ZTDF spec
• Slightly more complex version handling code
• Requires coordination between version fields for compatibility

Option 2 - Leverage semver build metadata

    "payload": {
        "type": "reference",
        "url": "0.payload",
        "protocol": "zip",
        "isEncrypted": true,
        "mimeType": "text/plain",
        "tdf_spec_version": "1.0.0+p1.2" // Made up version as this isn't implemented yet
    }

Advantages

• Doesn't require spec update
• Single version field
• Fully compliant with semver specification
• Build metadata doesn't affect version precedence
• Compact representation
• Easy to parse base version

Disadvantages

• Less explicit than separate fields
• Limited vendor version format (no dots in build metadata)

Recommended approach - Option 2

Using build metadata allows for sufficient versioning information, while not requiring an update to the existing specification. The base OpenTDF platform will will be able to function properly even if vendor specific code adds build metadata by ignoring it.

[jrschumacher]

I agree with Option 2.

[damorris25]

Agreed - option 2 is flexible and aligned to existing version standards.

[cassandrabailey293]

this is an additional requirement that we are adding as part of this ADR - discussed 11/12
opentdf/spec#52

this will bubble up the version to the root rather than on various policy objects within the tdf.