Proposal: Enable versioned schema validation

[vdice]

Goal

CNAB Implementations have a need to validate against specific versions of CNAB schemata

Proposed Requirements

The CNAB Spec authority (cnabio/cnab-spec) should:

• Produce schema artifacts for each specific schema version and persist these in a publicly-available manner (Note that, at time of writing, the schema versions currently visible/served via e.g. https://cnab.io/v1/bundle.schema.json always represent the latest/master branch versions)

Implementations should be able to fetch the version(s) of schemata they implement and:

• May use the schemata to validate implementations at build/test-time
• May include the schemata into their binaries/library code for runtime validation or downstream consumers

Proposed Implementations

Proposed implementation for cnabio/cnab-spec to achieve the requirement(s) above:

• Issue a git tag for each schema version

  • e.g. cnab-core-v1.0.0, cnab-claim-v1.0.0-DRAFT, cnab-dependencies-v1.0.0-DRAFT
    • For schemata still in draft, I propose we cut additional tags for implementation-use only (these aren't considered official schema versions). In doing so, we enable implementations to incrementally update to the latest version of the working draft schema.
    • e.g. cnab-claim-v1.0.0-DRAFT+8a4242d (short git SHA points to exact commit)

• Configure CI to produce artifacts (i.e. all schema.json files present at time of tag) based on the pushed git tag. A couple options (not mutually exclusive, if we'd like both):

  • Push to blob store

    • Upload the artifacts (schema.json files) to a location with incorporation of the git tag/version in the name
    • e.g. cnab-core-v1.0.0/bundle.schema.json
    • Enable anonymous users to download this artifact
    • Perhaps ideally via a custom domain, e.g. https://cdn.cnab.io/cnab-core-v1.0.0/bundle.schema.json. This also would/could enable web view.
    • An additional benefit: The cnab.io website should be able to serve all of the same cdn-hosted assets via a single Netlify redirect entry, e.g. /schema/* https://cdn.cnab.io/schema/:splat. Resulting in, say, https://cnab.io/schema/cnab-core-v1.0.0/bundle.schema.json

  • Push as OCI artifact to compatible registry (with anonymous access)

    • Can utilize oras (https://github.com/deislabs/oras) to push artifacts to a compatible registry (ACR has compatibility)
    • e.g. oras push vdice.azurecr.io/claim.schema.json:v1.0.0-DRAFT-8a4242d claim.schema.json:application/vnd.cnab.schema.config.v1+json
      • where claim.schema.json is the artifact
      • vdice.azurecr.io/claim.schema.json:v1.0.0-DRAFT-8a4242d is the reference
      • application/vnd.cnab.schema.config.v1+json is the custom mediaType (optional)
    • Users can pull via oras pull vdice.azurecr.io/claim.schema.json:v1.0.0-DRAFT-8a4242d
    • oras also offers a golang library for programmatic use, if desired

The first option will most likely be preferred as it enables more modes of artifact accessibility and isn't as limited by tools/tech, but I wanted to list the second option for funsies.

CNAB Implementation use

CNAB implementations may then achieve one or both of the stated goals above by consuming the schema artifacts and validating their code with the JSON Schema validation tool(s) of their choosing.

Use case: the main golang library, https://github.com/cnabio/cnab-go, could:

• Fetch versioned schemata at build-time and use these for build/test validation
• Package versioned schemata into the consumed code (e.g. via packr) which can be used for runtime and/or library consumer validation

Ref https://github.com/cnabio/cnab-go/issues/194

[vdice]

I'm planning on proceeding with the first option listed above (Push to blob store, etc.) as a solution to host versioned/tagged schemata from this repo.

[vdice]

Implemented in #350