Installation State Specification

[carolynvs]

After having the claims specification implemented for a while, and as new features are suggested, we've identified areas where the spec could be improved. For example, storing installation data in namespaces.

Rather than immediately bumping the CNAB Claim spec to v2, I am introducing a new specification "Installation State" that tools can implement and provide feedback on. Eventually when it stabilizes we can consider using it as the Claims v2 spec or replacing the Claims spec with this spec instead.

• Introduce installation document to store data associated only with the installation that isn't related to a particular bundle execution (claim).
• Support namespace and labels
  • Namespaces allow us to scope documents to a particular namespace or leave empty to define it in the global namespace.
  • Labels let us define key/value pairs on data stored that we can use to query later.
  • Add labels to bundles, credential sets, installations, claims, results, and outputs
  • Add namespaces to credential sets, installations, claims, results, and outputs.
  • Bundles already had the concept of namespacing via using the format com.example.mybundle. I did not want to use this format for the other documents and opted to use a separate field to preserve existing behavior. People could have named their other documents with periods not intending for it to be interpreted as namespaces.
• Expand credential sets to include parameter sets, and include namespaces and labels to the schema.

[carolynvs]

I'm so glad you remembered about the schema version! I'll make sure that all the docs have that going forward.

[carolynvs]

@vdice I have added schemaVersion to the following documents:

• installation
• claim
• claim result
• parameter set
• credential set

For the installation/claim/result docs, the value will be the version # of the installation state spec. For parameter/credential sets, it's a bit fuzzier since neither are actual formal specs with a version. Right now we have been tagging the spec following the cnab core version number, https://github.com/cnabio/cnab-spec/releases/tag/cnab-credentialsets-1.0.0-DRAFT%2Bb6c701f. Now that it is going to encompass both parameter and credential sets, I think we need to change this.

What if I made a new formal spec based on parameter and credential sets and name it ValueSet Specification (that's the name from cnab-go)? Then we can version it going forward. Thoughts?

[vdice]

@carolynvs Thanks for adding! Looks great.

What if I made a new formal spec based on parameter and credential sets and name it ValueSet Specification (that's the name from cnab-go)? Then we can version it going forward. Thoughts?

Definitely in support. Are we thinking of adding to this same PR?

[carolynvs]

I will take the changes I made to the non-normative cred spec out of this PR and move it into a separate PR that makes a real spec and adds schemaVersion, namespace and labels.

[carolynvs]

@radu-matei @jlegrone Can you take a look? I have incorporated Chris and Vaughn's feedback. The changes to parameter/credential sets have been moved into a new PR (incoming) but I still need a second review from a code owner.

[carolynvs]

After discussing with @technosophos and @vdice, I have realized that I was putting too many client concerns into this spec. I was losing sight that we only need to specify runtime concerns, or anything necessary that a bundle can be executed by any conformant runtime. Clients can extend the documents here and it doesn't need to be standardized.

We've always shared some common CRUD functionality in cnab-go, and used by the action package, which helped drive the confusion for me on what belongs or not. It made sense to share common structs for what a claim should look like, but things like the CRUD data access layer shouldn't have been in there IMO. It forced a tighter level of agreement between consumers of that library than was necessary.

I'm going to do another pass at this to just define the documents and terms necessary for what we need at runtime, which AFAIK is the concept of defining an installation within an namespace with associated labels that can be used to filter them. This is necessary for our plans for the dependencies spec, where a bundle can take a dependency on an existing installation that matches certain criteria. For example: "I need a mysql database in my namespace, with the following matching labels", and the runtime can use that criteria to decide to either create a new installation or reuse an existing one.

[carolynvs]

I'm going to close this and submit a new PR with the changes when they are ready.