Add examples v2 context and landing page

[msporny]

We need to be able to provide examples in the VC Data Model specification that are well formed VCs, but are constructed in such a way as to highlight certain features of the data model. We have traditionally maintained an examples context that defined all the terms that were used in the examples in the specification. In this iteration of the specification, it has been requested that we use more real-world examples in the specification. While that is a good goal, there have been objections to the types of examples that we would use. For example, some argue that the examples in the specification are too focused on education use cases, others believe that focusing on government identity use cases is not appropriate, still others feel that supply chain examples might be too complicated when certain sections in the specification are attempting to highlight a single feature.

This PR is being raised to address those concerns:

• It establishes a "Switzerland" of examples in the core specification, so we can use properties like "ExampleType" and "exampleProperty", keeping certain examples in the spec simple.
• It uses @vocab so we don't have to maintain every single "example*" type or property in the examples context like we did for v1.
• It establishes an "examples vocabulary landing page" such that if people click through on the example URLs, they will end up on a page that explains to them that they are looking at an example term that shouldn't be used in production.

Where we can use real-world examples, we will do so. Where we can't (or it muddies the waters wrt. what we're trying to show in the example), we will use the VC example vocabulary.

[TallTed]

lgtm

[iherman]

The issue was discussed in a meeting on 2023-05-03

• no resolutions were taken

View the transcript

3.4. (pr vc-data-model#1066)

See github pull request vc-data-model#1066.

Brent Zundel: next up is PR 1066.
… request for changes from manu but not here.

Orie Steele: goals.
… technical recommendation contains malformed JSON-LD.
… PR intends to remove 404.
… manu and dave and potentially others have a model of what example they'd like to see examples in the core spec.
… examples that contain multiple contexts.
… but i don't like examples with multiple contexts.
… just having some conversation on different opinions on examples.

Dave Longley: just quick clarification.
… we should have examples of both.
… first examples should be issuer independent vocabs.

Orie Steele: I am also in favor of examples of both, as I stated.

Dave Longley: and then issuer dependent vocabs but we should also say that this could be a risk.

Orie Steele: Not sure I agree regarding the "market failures" statement.

Orie Steele: but i look forward to reviewing text that elaborates on that.

Dave Longley: we should fix context instead of deleting them from examples.

Brent Zundel: two paths possible.
… one PR gets merged and then issue gets created.

Orie Steele: There are already open issues that track handling examples.

Brent Zundel: agree that the links in the examples should work.
… the other option is to create another PR that fixes the broken links.

Dave Longley: .
… another PR somewhere.
… to define an examples v2 context.
… that has examples vocab in it.
… not looked into it recently.
… but if gets traction.
… then we can merge that.
… because fixes broken links.
… and then can iterate on context.

See github pull request vc-data-model#1110.

Dave Longley: to improve examples.

Orie Steele: ^ that is the PR he is refering too.

Brent Zundel: orie?

Orie Steele: haven't had a chance to review it.

[msporny]

This PR could be merged right now, per WG process, except that (per last telecon's minutes) @OR13 has noted that he hasn't reviewed it yet and I know he has some strong opinions on it. I don't want to merge something that we might have to undo.

I'm going to hold the merge until after the VCWG call on Wednesday, hopefully @OR13 will be able to provide a review by then. Based on his approval here: #1111 (review) -- I expect he's good w/ this PR as well (but want to make sure w/ a explicit confirmation).

[OR13]

@msporny just merge the PR, this is much better context than v1.

[decentralgabe]

Merging. open over a week; multiple approvals; no conflicts.