Add "credential boilerplates" as examples #935

OR13 · 2022-09-17T18:19:32Z

Developers copy spec examples, we should plan to have better boilerplates in v2, here is an example:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
  ],
  "id": "http://example.edu/credentials/1872",
  "type": ["VerifiableCredential", "NewCredentialType"],
  "issuer": { 
    "id": "did:example:123", 
     "type": ["Organization", "OrganizationType"] 
   },
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:456", 
    "type": ["Person", "JobType"],
    "claimName": "claimValue"
  }
}

OR13 · 2022-12-14T20:40:45Z

Here is the minimal VCDM 1.1 boilerplate for the record:

{
  "@context": "https://www.w3.org/2018/credentials/v1",
  "type": ["VerifiableCredential"],
  "issuer": "did:example:123",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:456"
  }
}

David-Chadwick · 2022-12-15T14:46:11Z

Referring to my diagram in issue #982 , the first four are credential metadata properties and the last one is the credential.

OR13 · 2023-02-07T16:50:37Z

I believe this is now valid:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2"
  ],
  "id": "http://example.edu/credentials/1872",
  "type": ["VerifiableCredential", "NewCredentialType"],
  "issuer": { 
    "id": "did:example:123", 
     "type": ["Organization", "OrganizationType"] 
   },
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:456", 
    "type": ["Person", "JobType"],
    "claimName": "claimValue"
  }
}

OR13 · 2023-02-07T16:51:21Z

https://www.w3.org/ns/credentials/v2 (404)... cc @iherman @pchampin @msporny

pchampin · 2023-02-07T20:13:24Z

https://www.w3.org/ns/credentials/v2 (404)... cc @iherman @pchampin @msporny

According to our CVS log, this URL has never yet returned anything. If I'm wrong, then I'm missing something big time.

I'm assuming the plan is to put there the content generated from https://github.com/w3c/vc-data-model/tree/main/vocab/credentials/v2, right?

OR13 · 2023-02-07T23:13:46Z

Should point to

https://github.com/w3c/vc-data-model/blob/main/contexts/credentials/v2

Which is live at:

https://w3c.github.io/vc-data-model/contexts/credentials/v2

iherman · 2023-02-08T08:26:03Z

Before doing anything... I would like to be completely clear on what we plan to do.

It seems that we agreed (? is that so) that the new @context is in /ns/credentials/. That is what the /TR document tells me.
I presume https://www.w3.org/ns/credentials/examples/v2 should also move accordingly
The v2 context still refers to https://www.w3.org/2018/credentials for the vocabulary. Should that move to /ns/ as well? AFAIK this is not decided yet, there are pros and cons around it.
What about that default @vocab value? That should also point somewhere, not be a 404. This isn't in the /TR document yet.

Basically, we are not talking about a simple redirection in the /ns directory, but a slightly more complex .htaccess file to be put into /ns/credentials/. I am happy to do this, eventually, but all the details should be agreed upon before I do...

cc @msporny @pchampin @OR13

iherman · 2023-02-08T08:31:04Z

Just looking at the original issue introduction, using https://www.w3.org/ns/credentials# for that fall-back @vocab is incorrect. If /ns/credentials is the base for all VC URL-s, then /ns/credentials/ is the logical place for the vocabulary URL-s (just as /https://www.w3.org/2018/credentials/ is the vocabulary URL today). We should use something like

"@vocab" : "https://www.w3.org/ns/credentials/extras#:

for this. (I know, long bike-shedding around the term extras ahead.)

OR13 · 2023-02-08T14:12:36Z

@iherman the working group already merged a default vocab:

https://github.com/w3c/vc-data-model/blob/main/contexts/credentials/v2#L4

Let's not rehash it on this issue, but I am happy to discuss elsewhere.

The primary problem I am trying to address is that the examples in the current spec are broken (due to the 404).

Lets start by just fixing that.

https://www.w3.org/ns/credentials/v2 -> https://w3c.github.io/vc-data-model/contexts/credentials/v2

https://www.w3.org/ns/credentials/examples/v2 -> https://w3c.github.io/vc-data-model/contexts/credentials/examples/v1

^ I am against including examples like this "everywhere"... since they tend to cause a lot of "context setup" when working with the data model.

Because we have a built in vocab, I feel that this style of example is now "advanced example" where as this style example, is "simple / basic example":

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2"
  ],
  "id": "http://example.edu/credentials/1872",
  "type": ["VerifiableCredential", "NewCredentialType"],
  "issuer": { 
    "id": "did:example:123", 
     "type": ["Organization", "OrganizationType"] 
   },
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:456", 
    "type": ["Person", "JobType"],
    "claimName": "claimValue"
  }
}

^ The only thing preventing this minimal example from being valid is this link being 404:

https://www.w3.org/ns/credentials/v2

iherman · 2023-02-08T14:19:13Z

Ah. Indeed, the megrged new context says


 "@vocab": "https://www.w3.org/ns/credentials/issuer-dependent#",

which perfectly fine with me. But then what is the usage of @vocab in the example in the intro of this issue?

Also: at this moment https://www.w3.org/ns/credentials/issuer-dependent also leads to a 404. We would need at least a short HTML file to explain what this is meant for.

OR13 · 2023-02-08T14:20:21Z

@iherman I edited the original example, which predated the vocab merge to make it clear, its not needed.

https://www.w3.org/ns/credentials/issuer-dependent being 404 is less of an issue, its very common for RDF terms to not resolve to definitions... sadly.

However, it should resolve to an html page where we can address the nature of the "term being not defined in a context".

perhaps an html file in here:

https://github.com/w3c/vc-data-model/tree/main/vocab/credentials

"issuer-dependent.html" or "issuer-dependent/index.html"

Again fixing this won't make the examples valid, but fixing the first 404 will.

We would need at least a short HTML file to explain what this is meant for.

Here is some boilerplate to start:

The working group is preparing to address issuer defined terms in a way that provides an excellent experience for issuers and verifiers who rely on @vocab... The working group still recommends defining all the terms in a credential without relying on the default vocab.

iherman · 2023-02-08T14:24:45Z

@iherman I edited the original example, which predated the vocab merge to make it clear, its not needed.

Ah. Our comments crossed. Perfect.

What about the fact whether '/ns/credentials/'? Where would that go? To the vocabulary? Depending from the answers the way the redirection is set up (via a .htaccess or something else) is technically different, and I would prefer to have a clear picture before doing anything...

OR13 · 2023-02-08T14:28:45Z

https://www.w3.org/ns/credentials -> https://www.w3.org/2018/credentials for now.

TallTed · 2023-02-08T20:06:21Z

@OR13 — In the last line of your boilerplate, I think —
defining all the in a credential
— was meant to be —
defining all the terms in a credential

OR13 · 2023-02-08T21:53:43Z

@TallTed thanks, I edited the suggested text.

msporny · 2023-02-15T20:31:23Z

Please add a section called "How to get started with VCs as a Developer" and provide a simple starting template, then add JSON, then define a context and include it.

iherman · 2023-02-16T10:20:25Z

The issue was discussed in a meeting on 2022-09-15

no resolutions were taken

View the transcript

5.6. Add "credential boilerplates" as examples (issue vc-data-model#935)

See github issue vc-data-model#935.

Orie Steele: Developers copy the examples and change them.
… There are several problems in our examples that make them not valid JSON-LD.
… I want them to have no @vocab-extended terms.
… This issue is an attempt lead developers gently into this reality.

Manu Sporny: We need to give people a nice gentle introduction.
… Maybe this belongs in the Implementer's Guide.
… The base verifiable credential is pretty much useless.
… I'm concerned that people won't be patient and read through all three examples.
… I'm concerned about adding examples that are not where we want people to end up.

Brent Zundel: I think that starting with basic boilerplate and gradually getting more complex is something I find useful when reading specs..

Orie Steele: I agree with that statement.

Manu Sporny: Our present examples try to exercise too many spec features.

Orie Steele: The first example cannot have two contexts.

Paul Dietrich: As a developer, I will search the examples for the features I want.

Dmitri Zagidulin: +1000 specs can /never/ have too many examples.

Paul Dietrich: I'm a fan of having numerous examples.

Ted Thibodeau Jr.: We can include links to spec text that we want people to read in the examples.

Manu Sporny: Let's use some real-world examples.
… For instance, a simple open badge example.
… If they copy/paste them, they're going to work.
… It's a lot of work to go through the spec and revise the examples.
… We can have a "start here" section.
… It would be good to have a section in the spec saying how to move through the developer cycle.

Kristina Yasuda: I disagree with real-world examples in the core spec. But it's fine to have them in an annex..

Orie Steele: +1 kristina.

Kristina Yasuda: We don't want to distract readers.

Michael Jones: That's the approach we use in the SD-JWT spec.

David Chadwick: I think I've now received conflicting instructions.
… I was asked to describe the terms of use used by Train.

Kristina Yasuda: I see them as being different.
… Adding properties one by one demonstrates that they're useful.

Orie Steele: I think its a judgement call, and its possibly a good idea to start with a real world example for scenarios we have never seen....

Kristina Yasuda: if that is possible....

Manu Sporny: If we have a section on "how to get started" that builds things up bit by bit it can be early.

Orie Steele: I will do individual PRs for the examples.

OR13 · 2023-06-06T22:37:51Z

There is no action here, lets close it.

iherman · 2023-06-07T07:10:45Z

The issue was discussed in a meeting on 2023-06-06

no resolutions were taken

View the transcript

1.8. Add "credential boilerplates" as examples (issue vc-data-model#935)

See github issue vc-data-model#935.

Brent Zundel: Add credential boilerplates as examples, ready for PR -- we could add he post-CR label because this has to do with examples, or it could be closed.

Orie Steele: Manu solved this, this can be closed.

Orie Steele: I think it's been addressed by certain PRs, if it's my issue, I'm happy to close it.

Brent Zundel: Ok, marking pending close and it'll get closed.

brentzundel · 2023-06-13T13:58:03Z

No objections raised since marked pending close, closing.

OR13 mentioned this issue Oct 4, 2022

Tracking Issue from TPAC: What does JSON-LD compatible JSON mean? #929

Closed

OR13 mentioned this issue Oct 19, 2022

Add @vocab for private claims in /credentials/v2 @context #953

Closed

OR13 mentioned this issue Oct 27, 2022

IEEE Ontology Standards Working Group Credential Example #963

Closed

Sakurann added the ready for PR This issue is ready for a Pull Request to be created to resolve it label Jan 18, 2023

Sakurann assigned OR13 Feb 15, 2023

iherman mentioned this issue Feb 17, 2023

Setting up a user dependent namespace document #1049

Merged

brentzundel added pending close Close if no objection within 7 days and removed ready for PR This issue is ready for a Pull Request to be created to resolve it labels Jun 6, 2023

brentzundel closed this as completed Jun 13, 2023

Add "credential boilerplates" as examples #935

Add "credential boilerplates" as examples #935

Comments

OR13 commented Sep 17, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

OR13 commented Dec 14, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

David-Chadwick commented Dec 15, 2022

Uh oh!

OR13 commented Feb 7, 2023

Uh oh!

OR13 commented Feb 7, 2023

Uh oh!

pchampin commented Feb 7, 2023

Uh oh!

OR13 commented Feb 7, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iherman commented Feb 8, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iherman commented Feb 8, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

OR13 commented Feb 8, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iherman commented Feb 8, 2023

Uh oh!

OR13 commented Feb 8, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iherman commented Feb 8, 2023

Uh oh!

OR13 commented Feb 8, 2023

Uh oh!

TallTed commented Feb 8, 2023

Uh oh!

OR13 commented Feb 8, 2023

Uh oh!

msporny commented Feb 15, 2023

Uh oh!

iherman commented Feb 16, 2023

5.6. Add "credential boilerplates" as examples (issue vc-data-model#935)

Uh oh!

OR13 commented Jun 6, 2023

Uh oh!

iherman commented Jun 7, 2023

1.8. Add "credential boilerplates" as examples (issue vc-data-model#935)

Uh oh!

brentzundel commented Jun 13, 2023

Uh oh!

OR13 commented Sep 17, 2022 •

edited

Loading

OR13 commented Dec 14, 2022 •

edited

Loading

OR13 commented Feb 7, 2023 •

edited

Loading

iherman commented Feb 8, 2023 •

edited

Loading

iherman commented Feb 8, 2023 •

edited

Loading

OR13 commented Feb 8, 2023 •

edited

Loading

OR13 commented Feb 8, 2023 •

edited

Loading