Clarified the value of credentialSchema when type is JsonSchemaCredential

[andresuribe87]

This fixed #159 by making it clear what the value of credentialSchema MUST be. This prevents any infinite recursions.

---

Preview | Diff

[andresuribe87]

Not sure how to get this file to be published in this URL. @OR13 or @decentralgabe do either of you know?

[iherman]

At the moment I would propose that I set up a redirection from that URL to a file in the github repository. That would make the URL dereferencable, but also allow for changes. When we get to Rec, I presume a number of such redirections should be removed and replaced by the fix storage of the file on the W3C space. When the time comes, that will be on me (or anyone from the team if I am not alone).

[iherman]

That being said... I am a little bit worried of the proliferation of all kinds of URLs related to VCs on the W3C space. We have references/redirections from https://www.w3.org/2018/credentials/ with v1 and v2 or without it, and I am not sure we should bring a https://www.w3.org/2022/credentials/... into the mix. (why 2022? why not 2023?). Do we really need a v2 for something that did not even exist for v1?

Switching @msporny in, because the various URLs have been created back in the old days when neither you or I were around...

[msporny]

Yes, this is really confusing to me... it means that JsonSchemaCredential can only ever be a single value? I though JsonSchemaCredential could be used to point to a variety of different JSON Schema files... not just one of them?

[andresuribe87]

Let me try to address the confusion. First, some terminology:

• originalVC: a VC which is setting the credentialSchema property, where credentialSchema.type == "JsonSchemaCredential"
• jsonSchemaVC: The VC that results from dereferencing originalVC.credentialSchema.id. Note that jsonSchemaVC.type will contain "JsonSchemaCredential".

Note that the jsonschema that originalVC is validated against is the value of the property jsonSchemaVC.credentialSubject.jsonSchema.

What this PR is saying is that jsonSchemaVC.credentialSchema MUST be set to a fixed value.

Does this clarify things? If so, let me know what we can do to improve the language so it's clear.

[msporny]

Oh, so you're setting a base JSON Schema type for any JsonSchemaCredential? How do you add to that base schema? That is, if I have a FooCredential and I want to specify a JsonSchemaCredential that says exactly what goes in a FooCredential... how do I do that if the only valid value for JsonSchemaCredential is an object (and not an array of JsonSchemas)?

[andresuribe87]

Oh, so you're setting a base JSON Schema type for any JsonSchemaCredential?

No. It's a schema for any VC that has type JsonSchemaCredential (perhaps we are saying the same thing?)

That is, if I have a FooCredential and I want to specify a JsonSchemaCredential that says exactly what goes in a FooCredential... how do I do that if the only valid value for JsonSchemaCredential is an object (and not an array of JsonSchemas)?

You would set the property FooCredential.credentialSchema to be

{
  "type": "JsonSchemaCredential",
  "id": "https://example.com/credentials/1234"
}

Then you define the contents of the result of dereferending the id value. That is, you make sure that when dereferencing https://example.com/credentials/1234, clients would get something like what's below:

{
  "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "id": "https://example.com/credentials/3734",
  "type": ["VerifiableCredential", "JsonSchemaCredential"],
  "issuer": "https://example.com/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSchema": {
    "id": "https://www.w3.org/2022/credentials/v2/json-schema-credential-schema.json",
    "type": "JsonSchema",
    "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
  },
  "credentialSubject": {
    "id": "https://example.com/schemas/email-credential-schema.json",
    "type": "JsonSchema",
    "jsonSchema": {
       "$id": "https://example.com/schemas/email-credential-schema.json",
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "name": "EmailCredential",
       "description": "EmailCredential using JsonSchemaCredential",
       "type": "object",
       "properties": {
         "credentialSubject": {
           "type": "object",
           "properties": {
             "emailAddress": {
               "type": "string",
               "format": "email"
             }
           },
           "required": ["emailAddress"]
         }
       }
    }
  }
}

Notice that values of credentialSchema and credentialSubject.

What I'm fixing is the value of the credentialSubject property of this last VC. You would want to tailor the value of the property credentialSubject.jsonSchema so that it suits your needs, and you can validate that FooCredential is structurally correct.

[andresuribe87]

Let me know if there are any further questions. @iherman I'm going to keep this URL for now. If we decided to change, I'll update in a future PR.

[msporny]

This is confusing to me... it sounds like the JsonSchemaCredential can only have one schema associated with it? Doesn't this result in a ton of repetition in each VC?

[andresuribe87]

it sounds like the JsonSchemaCredential can only have one schema associated with it?

Yes.

Doesn't this result in a ton of repetition in each VC?

Yes, it will be repeated for all VCs who's type property has the value JsonSchemaCredential. This is no different than specifying a credentialSchema property on any other VC.

[andresuribe87]

I updated the example, which I had originally missed. I'm hoping this clarifies things further.

[decentralgabe]

@msporny this is a 'meta schema'

The idea is to prevent a credential schema having a credential schema having a credential schema....

So this limits the nesting to a single level:

• A JsonSchemaCredential can have a single JsonSchema
• A JsonSchema can have a single jsonSchema

[OR13]

I added some test cases related to this to vc-jose-cose-test-suite.

In case it helps with comprehension... Or in case I still don't get the point of JsonSchemaCredential.

[decentralgabe]

@msporny you can see here the base schema just enables the use of the schema versions the spec allows

[decentralgabe]

nice job - with the MUST this makes us enforce this in a test suite which is useful