Versioning json context file.

[xaviaracil]

During the JFF/VC-EDU plugfest, the context file changed causing mismatches between implementers (especially between issuers & wallets) leading to invalid signatures & errors. This cost implementers a lot of time (very costly) to rectify.

Versioning every change is one way to prevent these issues. This is different than how 1EdTech has managed the context files previously but keep in mind that any change to the context (even a spacing or punctuation change) could cause signature errors for issuers.

Risen by @kayaelle via mail.

[xaviaracil]

The working group agreed to propose exactly 2 publishing moments between now and spec final release. One "candidate final public" publishing moment, and then we don't change the live context at all until the spec is ready to go final, and IF changes are needed, we change it one more time at publication time. After final, we should not make any "breaking" change as an errata level change to the spec until we get to 3.1.

[martyr280]

+1 to this recommendation. @kayaelle

[kayaelle]

Correction to above: JSON formatting changes such as whitespace changes or changing single quotes to double quotes are not breaking changes.

Breaking changes do include:

• Adding terms
• Removing terms
• Changing term URLs

When a VC is signed using JSON-LD Signatures, the issuer actually uses the context and vocab to fetch the semantic meaning behind each of the terms in the JSON-LD credential. These vocab definitions are included in the canonicalized data prior to signing. So the issuer is embedding the semantic meaning of the terms in the data that it's signed.

When the VC is presented to a verifier, the verifier checks the signature on that canonicalized data... which means it is also checking the digital signature on both the text of the credential and the vocab behind each of the terms. It uses the context to do this.

Issuers and verifiers may dynamically load the context from the URL where it is hosted... or they may keep static copies of the context that they've downloaded ahead of time. (The latter is used by many issuers and verifiers for security purposes).

Either way... if you are verifying the JSON-LD Signature on a Verifiable Credential that was issued sometime in the past, you'll need access to the context that was embedded in that signed credential. So, if the context has been changed after the Verifiable Credential was issued, it will break the verification process for that Verifiable Credential (and any other VCs that were issued with the old context).

Recommendations:

• Use a development branch that deploys to a different URL to manage the publishing moments until the spec is final
• Employ a dependable and documented semantic versioning for any future publications

Keep in mind that some Open Badges 3.0 have already been issued and since many vendors have already implemented the spec, many more may be issued prior to the final release. Vendors are already working with each other on pilots and we want to facilitate and encourage this work.

[justinpitcher]

+1 some kind of semver-ish approach

I don't think the the fact that "patch" level changes could be breaking changes matter as much and is trumped by the intuitiveness of having version numbers align closely to spec version.

[xaviaracil]

Working group agreements on Dec 1st:

• We need a versioning of the context file so we don’t create a breaking change for early adopters
• Notifications in GitHub for any update/versioning required is an option
• Changes to Context Files will need to have a new URL
• “Patch fix” not new Spec
• Proposed the URL scheme https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.0.json --> https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json