-
Notifications
You must be signed in to change notification settings - Fork 110
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update term definition for vc json schemas as creds #1215
Conversation
This should be merged (and will need to fix conflicts) after #1209 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Concrete change request: date-stamped or not?
contexts/credentials/v2
Outdated
@@ -123,9 +123,9 @@ | |||
} | |||
}, | |||
|
|||
"VerifiableCredentialSchema2023": { | |||
"JsonSchemaCredential2023": { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"JsonSchemaCredential2023": { | |
"JsonSchemaCredential": { |
Are you keeping the date or removing it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
removed
contexts/credentials/v2
Outdated
"@id": | ||
"https://w3.org/2018/credentials#VerifiableCredentialSchema2023", | ||
"https://w3.org/2018/credentials#JsonSchemaCredential2023", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"https://w3.org/2018/credentials#JsonSchemaCredential2023", | |
"https://w3.org/2018/credentials#JsonSchemaCredential", |
Same question as above?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
removed
678f01c
to
207bbcb
Compare
removing versioning here w3c/vc-json-schema#192 |
The issue was discussed in a meeting on 2023-08-01
View the transcript1.5. Update term definition for vc json schemas as creds (pr vc-data-model#1215)See github pull request vc-data-model#1215. Brent Zundel: Update Term Definition for VC JSON Schema as creds, raised by Gabe, so far no reviews. Gabe Cohen: there is a change to the naming of the credential representation of the JSON Schema VC, which this PR addresses. Brent Zundel: thank you, seem straightforward. Manu Sporny: Gabe, I was waiting for you to update before reviewing, I thought you'd get rid of the datestamp stuff. (I just added a request). Gabe Cohen: not intentional. I know Ivan has another PR opened, 1218, that does add it to vocab. Manu Sporny: it's sufficient if you just use the vocab term from that PR. Gabe Cohen: happy to delay the merge, till the VC JSON Spec removes the year; I didn't want to be the first one to do that. Manu Sporny: you don't have to wait, if you're gonna update the JSON Schema spec, you can do both in parallel. Gabe Cohen: thanks, will do. Brent Zundel: Gabe is quick to respond, so changes will be in very soon, so folks, review those. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still requires fixes to use the https://w3.org/2018/credentials#
base vocabulary URL... see PR https://github.com/w3c/vc-data-model/pull/1218/files for details.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See my suggestion and +1 to @msporny's suggestions.
contexts/credentials/v2
Outdated
@@ -112,9 +112,9 @@ | |||
} | |||
}, | |||
|
|||
"JsonSchema2023": { | |||
"JsonSchema": { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks like a duplicate of what's below. This one should be removed as the one below looks more correct (has jsonSchema
defined in its scoped context).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
updated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
updated
Co-authored-by: Manu Sporny <msporny@digitalbazaar.com>
contexts/credentials/v2
Outdated
"@id": | ||
"https://w3.org/2018/credentials#JsonSchema2023", | ||
"https://w3.org/2018/credentials#JsonSchemaCredential", | ||
"@context": { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm -- this scoped context has now moved into JsonSchemaCredential
. It should be under JsonSchema
instead. That way, when an object of "type" JsonSchema
is used, it will have the jsonSchema
property (where the actual JSON schema goes) defined. It's that object that has that property, not the JsonSchemaCredential
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dlongley that seems reversed to me. Perhaps examples make this clearer:
Pulled from https://w3c.github.io/vc-json-schema/#jsonschema
Case 1
JsonSchema
... a type that refers to a JSON Object that validates JSON... (we intend to implement this one).
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3732",
"type": ["VerifiableCredential", "EmailCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"emailAddress": "subject@example.com"
},
"credentialSchema": {
"id": "https://example.com/schemas/email-credential-schema.json",
"type": "JsonSchema" // type
}
}
Case 2
JsonSchemaCredential
... a type that refers to a VerifiableCredential, that contains a json object, that validates JSON... (we do not plan to implement this one).
{
"@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"], // type
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"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"]
}
}
}
}
}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps you are suggesting this?
{
"@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"], // type
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"$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"]
}
}
}
}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My suggestions will make Case 1 and Case 2 work. The "Perhaps you were suggesting this" is not something I was suggesting and don't believe we should do.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right now, this PR will create these term mappings:
"JsonSchemaCredential": {
"@id":
"https://w3.org/2018/credentials#JsonSchemaCredential",
"@context": {
"@protected": true,
"id": "@id",
"type": "@type",
"jsonSchema": {
"id": "https://w3.org/2018/credentials#JsonSchema",
"type": "@json"
}
},
"JsonSchema": {
"@id": "https://w3.org/2018/credentials#JsonSchema",
"@context": {
"@protected": true,
"id": "@id",
"type": "@type"
},
This would mean that jsonSchema
would only be defined at the top-level of a VC that used the type JsonSchemaCredential
. Something like this (which we do not want):
{
"@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"], // type which
// defines the scoped-context with "jsonSchema" for use on this object
// which we do not want
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
// we do not want this
"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"]
}
}
},
"credentialSubject": {
"id": "https://example.com/schemas/email-credential-schema.json",
"type": "JsonSchema" // note that "jsonSchema" would be undefined in here
}
}
Instead, it should do this:
"JsonSchemaCredential": "https://w3.org/2018/credentials#JsonSchemaCredential",
"JsonSchema": {
"@id": "https://w3.org/2018/credentials#JsonSchema",
"@context": {
"@protected": true,
"id": "@id",
"type": "@type",
"jsonSchema": {
"id": "https://w3.org/2018/credentials#JsonSchema",
"type": "@json"
}
},
Which will enable Case 2:
{
"@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"], // type
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "https://example.com/schemas/email-credential-schema.json",
"type": "JsonSchema", // this type has the scoped-context that
// defines "jsonSchema" for use on this object
"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"]
}
}
}
}
}
It also enables Case 1 by simply defining JsonSchema
as a usable type at all.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dlongley I've updated the PR to reflect your changes ( I think )
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dlongley one question -- I would assume since we want to expose the term jsonSchema
inside the credentialSubject
of a JsonSchemaCredential
then the term would need to be defined under JsonSchemaCredential
why is it that there's no need to define jsonSchema
within the JsonSchemaCredential
type?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's a situation I don't quite understand. Imagine the following scenario
The VC has the property below.
{
"credentialSchema": {"id": "https://example.com/my-json-schema.json", "type": "JsonSchema"}
}
And the contents that result from dereferencing https://example.com/my-json-schema.json
are the following:
{
"$id": "https://example.com/my-json-schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"name": "EmailCredential",
"type": "object",
"properties": {}
}
Would the VC.credentialSchema.type
conflict with dereferenceURL(VC.credentialSchema.id).type
? Note that the result of dereferenceURL
does not contain any jsonSchema
property within it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dlongley one question -- I would assume since we want to expose the term
jsonSchema
inside thecredentialSubject
of aJsonSchemaCredential
then the term would need to be defined underJsonSchemaCredential
why is it that there's no need to definejsonSchema
within theJsonSchemaCredential
type?
Because jsonSchema
is not a property of an object of type JsonSchemaCredential
. It's a property of an object of type JsonSchema
.
Type-scoped contexts are applied to the objects where the type
is declared. It's similar to OOP where you declare the properties that can appear on an object of a certain type. An object of type JsonSchema
can use the jsonSchema
property. We want that property to be defined on an object of that type, not on JsonSchemaCredential
.
As an example:
{
"@context": {
"pet": "example:pet",
"id": "@id",
"type": "@type",
"Dog": {
"@id": "example:Dog",
"@context": {
"id": "@id",
"type": "@type",
"name": "example:name",
"breed": "example:breed",
"favoriteToy": "example:favoriteToy"
// etc.
}
}
},
"pet": {
"id": "example:some_id",
"type": "Dog",
"name": "Bark Hamill",
"breed": "Chihuahua"
// "favoriteToy" you don't have to use every defined property
}
}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's a situation I don't quite understand. Imagine the following scenario
The VC has the property below.
{ "credentialSchema": {"id": "https://example.com/my-json-schema.json", "type": "JsonSchema"} }And the contents that result from dereferencing
https://example.com/my-json-schema.json
are the following:{ "$id": "https://example.com/my-json-schema.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "name": "EmailCredential", "type": "object", "properties": {} }Would the
VC.credentialSchema.type
conflict withdereferenceURL(VC.credentialSchema.id).type
? Note that the result ofdereferenceURL
does not contain anyjsonSchema
property within it.
Just because a term mapping exists in a JSON-LD context does not mean it has to be used. Also, since the content at that URL is not application/ld+json
, there's no reason to think (nor any automated way) its contents should be merged into a knowledge graph. If you wanted to enable some kind of automated way to merge, you could also serve application/ld+json
from that URL with a different representation (when requested via content negotiation), but that doesn't sound like it's really even a use case here.
Btw, the alternative representation in (application/ld+json
) could be something like this:
{
"@context": "https://www.w3.org/ns/credentials/v2",
"id": "https://example.com/my-json-schema.json",
"type": "JsonSchema",
"jsonSchema": {
"$id": "https://example.com/my-json-schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"name": "EmailCredential",
"type": "object",
"properties": {}
}
}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@decentralgabe, very close -- a couple more suggestions.
The jsonSchema
suggestion is important since the property jsonSchema
should be mapped to the URL with the matching lower case URL fragment. The class / type name JsonSchema
(upper case) is mapped to the URL with the upper case URL fragment.
contexts/credentials/v2
Outdated
"JsonSchemaCredential": { | ||
"@id": | ||
"https://w3.org/2018/credentials#JsonSchema2023", | ||
"https://w3.org/2018/credentials#JsonSchemaCredential", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since no scoped context is needed here, this can be simplified to:
"JsonSchemaCredential": "https://w3.org/2018/credentials#JsonSchemaCredential",
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thanks, updated
Co-authored-by: Dave Longley <dlongley@digitalbazaar.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Based on the discussion on the PR, I don't feel comfortable approving this until additional examples are added along with the context changes.
We have the following test case today: Case A.1{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/1872",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "https://university.example/issuers/565049",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSchema": {
"id": "https://university.example/schemas/ExampleAlumniCredential",
"type": "JsonSchema"
},
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
}
} After this PR is merged, will this test case still be valid? Can we include an example to make this clearer? Can we also add an example based on the thread above? Case A.2{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/1872",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "https://university.example/issuers/565049",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSchema": {
"id": "https://university.example/schemas/ExampleAlumniCredential",
"type": "JsonSchema",
"jsonSchema": {
"$id": "https://university.example/schemas/ExampleAlumniCredential",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"name": "ExampleAlumniCredential",
"type": "object",
"properties": { ... }
}
},
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
}
} To be clear, current blocking feedback:
|
FWIW, @OR13's understanding of the PR is aligned with my understanding of the PR, but I think there is another use case that needs to be explained... Non-blocking thought: I wouldn't expect In addition to the examples above, I'd also expect an example that would be something along these lines Case A.2{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/schemas/9288",
"type": ["VerifiableCredential", "JsonSchemaCredential"],
"issuer": "https://university.example/issuers/827",
"validFrom": "2023-08-01T19:23:24Z",
"credentialSubject": {
"id": "https://university.example/schemas/ExampleAlumniCredential",
"type": "JsonSchema",
"jsonSchema": {
"$id": "https://university.example/schemas/ExampleAlumniCredential",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"name": "ExampleAlumniCredential",
"type": "object",
"properties": { ... }
}
}
} ... and then, again, I also question if these examples should be in the base specification, or the JSON Schema specification (and we point over to that document for examples). Again, all of the above are non-blocking thoughts on this PR. |
And for the case where we have: {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/1872",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "https://university.example/issuers/565049",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSchema": {
"id": "http://university.example/credentials/schemas/9288",
"type": "JsonSchemaCredential",
},
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
}
}
It would point to: {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/schemas/9288",
"type": ["VerifiableCredential", "JsonSchemaCredential"],
"issuer": "https://university.example/issuers/827",
"validFrom": "2023-08-01T19:23:24Z",
"credentialSubject": {
"id": "https://university.example/schemas/ExampleAlumniCredential",
"type": "JsonSchema",
"jsonSchema": {
"$id": "https://university.example/schemas/ExampleAlumniCredential",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"name": "ExampleAlumniCredential",
"type": "object",
"properties": { ... }
}
}
} Or alternatively: {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/1872",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "https://university.example/issuers/565049",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSchema": {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/schemas/9288",
"type": ["VerifiableCredential", "JsonSchemaCredential"],
"issuer": "https://university.example/issuers/827",
"validFrom": "2023-08-01T19:23:24Z",
"credentialSubject": {
"id": "https://university.example/schemas/ExampleAlumniCredential",
"type": "JsonSchema",
"jsonSchema": {
"$id": "https://university.example/schemas/ExampleAlumniCredential",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"name": "ExampleAlumniCredential",
"type": "object",
"properties": { ... }
}
}
},
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
}
} {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/1872",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "https://university.example/issuers/565049",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSchema": "compact jwt or sd-jwt here", // ?,
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
}
} Regardless of where the examples are, there will need to be tests that cover the following:
I'd tend to recommend against including schema's by value especially for data integrity proofs because it will increase the processing time... unless I'm approving based on the comments... no need to add these 4 cases to the core spec as examples... but we should remove any RDF types that are in the core data model context, that are not tested fully in a securing specification... or there will not be interoperability. I am assuming nobody wants to use "JsonSchemaCredential" without some proof... either internal or external... so the examples should include "things with proofs"... not plain JSON objects |
comments addressed. multiple approvals from editors. open for >1 week. merging. |
The issue was discussed in a meeting on 2023-08-09
View the transcript2.6. (pr vc-data-model#1215)See github pull request vc-data-model#1215. See github pull request vc-data-model#1218. Manu Sporny: PR 1215 1218. approvals. |
As per w3c/vc-json-schema#186 (comment)
Preview | Diff