vc-data-model
vc-data-model copied to clipboard
w3c
Implementation Issues and under specification
I have been trying to implement this specification and having issues, here is one issue I ran into, I'm plodding along to try to finish my implementation.
"The value of the issuer property MUST be either a URI or an object containing an id property. It is RECOMMENDED that the URI in the issuer or its id be one which, if dereferenced, results in a document containing machine-readable information about the issuer that can be used to verify the information expressed in the credential."
I take this is intended to mean the Issuer field specifies the entity that issued the credential, and the value of the field should be a URI that resolve to the data/keys required for verifying the credential, such as a DID/DID Doc, JWK at the specified URL endpoint, etc.
The issue is how do you know what the return document will be, like DID Doc vs JWK vs ___? This must be clearly specified in the field before resolution; The NOTE may be trying to vaguely allude to that https://www.w3.org/TR/vc-data-model/#issuer but does not.
Suggest to use object descriptor as the value that specifically type-identifies what will come back from the resolution of the URI.
issuer: { uri: “did:foo:123”, format: “did-document” }
issuer: { uri: “https://example.edu/comp-sci/identity-root”, format: “jwk” }
issuer: { uri: “ipfs:QmPXME1oRtoT627YKaDPDQ3PwA8tdP9rWuAAweLzqSwAWT”, format: “jwk” }
I don't think it will be a problem to add an example to the data model that shows an issuer property with a value that is an object.
It may also be possible to give more detail about this in the implementation guide
@brentzundel Example I don't believe is enough as examples are non-normative. Trying to implement I find the specification under specified in this area. I can't handle a return object properly without knowing what type it is.
Suggest to use object descriptor as the value that specifically type-identifies what will come back from the resolution of the URI.
The functionality you desire does not require the spec to be changed in any way. As it is written, the data model supports exactly what you propose.
I can't handle a return object properly without knowing what type it is.
An implementation (such as yours) is free to specify what return type it expects when dereferencing a URI associated with an issuer. The data model supports this by allowing the value of in issuer property to be an object (as long as the object has an id property which specifies the URI). The issuer object may also contain properties such as those you describe. The example added via PR #710 shows this.
Example I don't believe is enough as examples are non-normative.
If an example is not sufficient, then the appropriate place to add greater detail about this would be the implementation guide. You may wish to open an issue there suggesting this.
I have been trying to implement this specification
I hope that when it is ready you might include an implementation report in the vc-test-suite. Please feel free to reach out if you need any assistance doing so.
@brentzundel I disagree that this is a implementation guide issue, the specification is underspecified. This leads to data model interoperability issues and implementation expectation error conditions
@nadalin The spec clearly allows you to add the feature you want. It just doesn't require it. So you can already do what you want.
However, there's no reason an issuer should be prevented from changing the format of the proof mechanism for credentials it has already issued, and there are plenty of reasons that they would want to do so, including future-proofing to support better formats. What you're suggesting is like requiring that a particular URL always return the same format, which, frankly, would break the web.
The traditional way to address your use case is for the end-point to be self-describing, which is how http urls have worked for decades. Mime-types/media types already solved this problem. DIDs also solve it by requiring that all DIDs resolve to DID Documents unless a service endpoint is specified, in which case, the mime-type returned by the service endpoint provides the format.
Decision on 13 August 2019 WG call:
RESOLVED: Issue #709 is addressed by PR #710, which adds a non-normative example to the specification demonstrating how an issuer value can be a dictionary (a set of key-value pairs).
@stonematt This does not address the issue since it is non-normative, the text needs to be update and a value pair mandatory for interop or at least recommended
Is there some issue with just making the return expectations explicit? I sympathize with Tony's point that while one can use the spec in a way that is explicit, what is the benefit of having it be unknown? Wouldn't a simple compromise be to simply have folks mark the return type as a required field of a descriptor?
There is no issue with making the return expectations explicit. It is certainly possible to simply have folks mark the return type. The spec as written supports this. PR #710 provides an example of how this may be done.
@brentzundel so we can just specify that people MUST use a descriptor object, instead of a single amorphous value that could return anything? If so, that's cool, I think we address Tony's objection that way and benefit from devs always knowing what's coming back in the process. Is everyone OK with this change?
We don't need to require that people MUST use a descriptor object. There are implementers who neither need nor desire this. Those who do desire this are free to do so without any changes to the spec.
On Wed, Aug 14, 2019 at 10:27 AM Daniel Buchner [email protected] wrote:
@brentzundel https://github.com/brentzundel so we can just specify that people MUST to use a descriptor object, instead of a single amorphous value that could return anything? If so, that's cool, I think we address Tony's objection that way and benefit from devs always knowing what's coming back in the process. Is everyone OK with this change?
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/w3c/vc-data-model/issues/709?email_source=notifications&email_token=ACPFKPZ54X6A3YC6XG55M7TQEQW7TA5CNFSM4IJXDTC2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD4JLDTA#issuecomment-521318860, or mute the thread https://github.com/notifications/unsubscribe-auth/ACPFKPZOHEAAM7KBZNCNMX3QEQW7TANCNFSM4IJXDTCQ .
@brentzundel I guess I just see this as an odd hill to die on, given the worst thing it does is makes things explicit and likely make code/handling of this part of VCs clearer. My 2 cents would be to just make simple changes that don't really change the overarching spec/functionality and be done with it, but I will let you all sort it out.
@brentzundel To achieve interop there would have to be normative guidance, which is not in the specification today and the propsed text is non-normative. I don't understand the reluctance to improve the specification for implementation and interop purposes as I have tried to implement this specification and having issues that I have reported here.
The group has been considering PR #710 to address this issue. I've been thinking about this PR over the last week or so as I was on the fence about it. Fundamentally, I think the examples using a key as the issuer is an anti-pattern that we don't want people to use, for the following reason:
The key-as-issuer pattern suggests that people should use public keys to identify issuers. This is a bad practice because you don't get key rotation when you do this, which is one of the things that DIDs achieved (and why so many of us are proceeding along those lines).
We had started a few years ago ago by using keys as issuers, but we've gone away from doing that over the years because of the bind it puts issuers and verifiers in. Everyone needs to track whose keys are whose and that leads to complex and fragile systems (as exemplified by some of the systems utilizing JWKs as ways to identify issuers).
As such, we came up with the controller pattern, where (at least in LD Proofs) the key is associated with a proof, which points to the key via something like (in the Verifiable Credential LD Proof):
"verificationMethod": "did:example:1234567#key-1",
When you go and look at that key (in the DID Document), it's expected that it has a controller or some way of associating it with the entity that controls the key. These keys are usually tied to entities in the DID Document, and thus it enables you to do stuff like this (in the Verifiable Credential):
"issuer": "did:example:1234567"
... which is great for issuers and verifiers, because that's a long lived identifier that doesn't break when you rotate keys.
This example goes against that very hard earned lesson, and thus I think we should defer pulling this example into the specification.
There are examples that do make sense, like this one:
"issuer": {
"id": "did:example:123456789",
"name": "Example University"
}
... and I'll modify @brentzundel's PR to that and pull it into the spec so there is a good example of how you can use issuer in its expanded form. The reason we have both is because there are solid use cases for both (as discussed multiple times in the WG).
In 20 Aug 2019 VCWG meeting:
RESOLVED: PR #715 mostly addresses issue #709, but the issue commenter has raised other concerns that the group has agreed to defer until another group picks up the specification.
@brentzundel . I was able to implement the support of JWT based claims and proofs and pass the tests listed under JWT in https://w3c.github.io/vc-test-suite/implementations/ specification. There are some issues raised in #709, #712 and #713. I can't seem to update the the vc-test-suite so if you can help I would appreciate.
There are 2 things being discussed on this issue:
What is the shape of issuer in a VerifiableCredential.
Today, these are all valid:
"issuer": {
"id": "did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U",
"type": "Organization",
"name": "Hauck Group",
"description": "Focused secondary synergy",
"address": {
"type": "PostalAddress",
"streetAddress": "3198 O'Kon Wall",
"addressLocality": "North Adolphchester",
"addressRegion": "Nevada",
"postalCode": "50788",
"addressCountry": "Cote d'Ivoire"
},
"email": "[email protected]",
"phoneNumber": "555-171-4411",
"faxNumber": "+1-555-758-9761"
},
"issuer": {
"id": "did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U",
},
"issuer": "did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U",
"issuer": "https://example.com/issuer/123",
What is the shape of the document that is resolved from the issuer.
These are the formats that I have seen that work for this scenario:
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/jws-2020/v1"
],
"id": "did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U",
"verificationMethod": [
{
"id": "did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U#z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U",
"type": "JsonWebKey2020",
"controller": "did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U",
"publicKeyJwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "zX2zoGmW36TTL_kw3g-KFVjh5IoaDcoSc08jID4uGrs"
}
},
{
"id": "did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U#z6LSnwWmr9SEPihTosSC6huv6hN22NkFnrFZjxvgZBYppNEi",
"type": "JsonWebKey2020",
"controller": "did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U",
"publicKeyJwk": {
"kty": "OKP",
"crv": "X25519",
"x": "p15wup5TtVlX-A1RWSJYcoaKyxGwMO1nLTk7whNfLDc"
}
}
],
"assertionMethod": [
"did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U#z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U"
],
"authentication": [
"did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U#z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U"
],
"capabilityInvocation": [
"did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U#z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U"
],
"capabilityDelegation": [
"did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U#z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U"
],
"keyAgreement": [
"did:key:z6MktHQo3fRRohk44dsbE76CuiTpBmyMWq2VVjvV6aBSeE3U#z6LSnwWmr9SEPihTosSC6huv6hN22NkFnrFZjxvgZBYppNEi"
]
}
I am not aware of any interoperability regarding VCs that come from documents of other shapes...
I can imagine inventing support using the approach taken by OIDC... including .well-known/oidc-configuration and jwks_uri.
The issue was discussed in a meeting on 2022-08-17
- no resolutions were taken
View the transcript
2.1. Implementation Issues and under specification (issue vc-data-model#709)
See github issue vc-data-model#709.
Antony Nadalin: we do not know what type of info is at this URI.
Orie Steele: what is the relationship between the issuer attribute and a DID document. Orie says they should be the same.
… we should cover all cases.
Dave Longley: +1 to Orie to showing examples with DID dereferencing.
Manu Sporny: DavidC: What about a .well-known URL?.
Dmitri Zagidulin: what about putting issuer related fields directly into the issuer object?.
… in JFF we want to store things like name and logo of the issuer.
Antony Nadalin: would like some more time to think about this issue.
Oliver Terbu: https://w3c-ccg.github.io/vc-ed/plugfest-1-2022/.
Antony Nadalin: not sure that discussion so far will help implementors determine what they are likely to get back.
We discussed this on the call today. It was suggested that we split this issue into two more focused issues as @OR13 has pointed out here https://github.com/w3c/vc-data-model/issues/709#issuecomment-1218401700 .
The issue was discussed in a meeting on 2022-10-19
- no resolutions were taken
View the transcript
3.2. Implementation Issues and under specification (issue vc-data-model#709)
See github issue vc-data-model#709.
Brent Zundel: revolves around whether issuer is an object or not.
Manu Sporny: I like Orie's comment.
… can we close the issue and raise a simpler one.
Brent Zundel: suggested you ask Tony.
Dmitri Zagidulin: the current text also is problematic.
… in OpenBadges 3 we make extensive use of issuer as an object.
… also useful if two issuers are jointly issuing a diploma.
… 'compound issuers'.
Manu Sporny: what is the problem since today we allow it to be an object.
Orie Steele: Does not look like that was scribed..
Manu Sporny: what is the concrete change you are requesting.
Dmitri Zagidulin: add examples to the VC spec that have issuer as an object.
… add common fields of name, image, web site to v2 context.
Dave Longley: See https://www.w3.org/TR/vc-data-model/#example-usage-of-issuer-expanded-property.
Dmitri Zagidulin: open an issue to discuss compound issuers.
Manu Sporny: we have an example in the spec of a compound issuer.
Kristina Yasuda: there is a multi-issuer issuer by gabe too: https://github.com/w3c/vc-data-model/issues/932.
Dmitri Zagidulin: please add image and name to this.
Orie Steele: my favorite field to add to the
issuerblock is a postal address and email address..
Dmitri Zagidulin: +1 for the latter.
Manu Sporny: should image be under the issuer or as a top level property that can be used anywhere.
Ivan Herman: I dont think we should come up with another vocabulary for person.
Dmitri Zagidulin: sure, use schema.org.
Please leave this open.
Get Outlook for Androidhttps://aka.ms/AAb9ysg
From: Manu Sporny @.> Sent: Wednesday, October 19, 2022 5:44:10 PM To: w3c/vc-data-model @.> Cc: Anthony Nadalin @.>; Mention @.> Subject: Re: [w3c/vc-data-model] Implementation Issues and under specification (#709)
We discussed this on the call today. It was suggested that we split this issue into two more focused issues as @OR13https://github.com/OR13 has pointed out here #709 (comment)https://github.com/w3c/vc-data-model/issues/709#issuecomment-1218401700 .
— Reply to this email directly, view it on GitHubhttps://github.com/w3c/vc-data-model/issues/709#issuecomment-1284220288, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AB4R4YZYCML36WINULIVUWDWEAJMVANCNFSM4IJXDTCQ. You are receiving this because you were mentioned.Message ID: @.***>
The issue was discussed in a meeting on 2023-01-11
- no resolutions were taken
View the transcript
3.3. Implementation Issues and under specification (issue vc-data-model#709)
See github issue vc-data-model#709.
Brent Zundel: Implementation issues. Lost track of what this means. Update the title..
… What is the shape of the document and VC? Related to the issue Orie has raised..
… Will be partially addressed based on Orie's issue..
… Any comments?.
… Will change the title to something more useful..
Manu Sporny: This is also related to the previous issue. It's the same question. It's a duplicate..
Brent Zundel: Tony has requested this to remain open..
There were updates related to this in data integrity, see:
- https://w3c.github.io/vc-data-integrity/#retrieve-verification-method
We decided to move this issue to vc-jwt, I believe this is already solved for in data integrity.
@brentzundel @Sakurann can we close this now?
The issue was discussed in a meeting on 2023-04-05
- no resolutions were taken
View the transcript
3.1. Underspecification of issuer object format and document obtained if issuer id is dereferenced (issue vc-data-model#709)
See github issue vc-data-model#709.
Brent Zundel: Underspecification of issuer object format and document obtained if issuer id is dereferenced.
… If you say that an issuer ID should be dereferenceable and processed, we don't say what that should look like.
… Anyone wish to be assigned?
Dmitri Zagidulin: +1 Orie.
Orie Steele: Added a link to the verification method. May not belong to the data model but rather data integrity.
Dmitri Zagidulin: outside the context of securing integrity, there is no requirement to resolve an issuer id.
Joe Andrieu: +1 to dmitriz' comment.
Ivan Herman: I'm a little bit surprised because the previous iteration of this WG decided in 2019 to consider this as closed.
… The issue remained open and is now back in front of the WG.
Michael Prorock: +1.
Manu Sporny: -1 no, that's not what issuer was intended to be used for... we're changing the definition of issuer... I expect those issues to be closed if they were raised on the data integrity spec.
Michael Jones: Agree with Orie. To Ivan's point about whether it is being reopened, developers have told us that the spec as written is not actionable, that you have to have outside knowledge of how to retrieve the keys, which means you are not interoperable.
… Pleased that we're considering this issue. I would consider being assigned this issue.
Orie Steele: its not possible to "test" without defining this... but perhaps those tests only apply to the "security suites" where "verification" can actually be tested.
Brent Zundel: Would you accept opening and assigning to yourself?
Michael Jones: Not this week.
Manu Sporny: it is possible to test verification w/o "how to dereference issuer" being defined.