w3c
Should we use JSON or JSON-LD for the resolution spec?
This is related to https://github.com/w3c/did-resolution/pull/135, also discussed on our call. The fundamental question is whether we want to use JSON-LD (as opposed to JSON) in the resolution spec.
The main value of JSON-LD (IMHO) is that it provides a mechanism for decentralized evolution and usage of vocabularies. That is the strength of JSON-LD, and indeed of the underlying RDF model. Different domains can define their own vocabularies (syntax as well as usage and semantics), and all these vocabularies can be mixed in the same place without any worry of terminology clash. But there is a price: JSON-LD is complicated, complex, and it has to be handled with care.
Hence the question: do we really want to use JSON-LD for the DID Resolution spec? Do we expect external vocabularies to be mixed with the core resolution terms or not? If not, then it might be perfectly fine to just use pure JSON, and there is no need for context files, worry about vocabulary URL-s, and whatnot.
I cannot answer this question; the WG must do that. I am just raising it.
(Note that we do use JSON-LD in DID Core, that decision has been made. My question is only for the resolution spec.)
If the decision is to indeed use JSON-LD, you may also want to look at https://github.com/w3c/did/issues/884.
@iherman Thank you for this summary, here are some thoughts:
It may sound weird, but to me the relationship between a "DID document" and a "DID resolution result" is a bit like the relationship between a VC and a VP. The VP wraps a VC, and the VP is something dynamic that you use in an interaction, whereas the VC is more static. In a similar way, a DID document is more static, whereas a DID resolution result is something dynamic when you interact with a resolver, and the DID resolution result wraps the DID document.
So I think we could ask the same question, why did the VC WG decide to use JSON-LD rather than just plain JSON for VPs? VPs typically don't need the richness of RDF and mixed vocabularies, just like DID resolution results typically don't need that richness. Actually now that I think of it, there are some metadata properties in DID resolution results that appear across different DID methods, so we might potentially benefit from reusing vocabularies for metadata properties in certain cases.
Another aspect are proofs. I imagine that VPs probably chose JSON-LD so that they could re-use the same Data Integrity proof mechanisms as VCs. I think this argument can also be made about DID resolution results. While it's not very common to have proofs on a DID resolution result, it's certainly possible in some scenarios, so there could be value in being able to add proofs to DID documents and to DID resolution results in a coherent way.
In any case, I don't feel strongly about this topic, so either way is fine for me.
Another aspect are proofs. I imagine that VPs probably chose JSON-LD so that they could re-use the same Data Integrity proof mechanisms as VCs.
I was not part of the VC WG when this decision was made, but that would have been my tentative answer to your question. Also: as a JSON structure, a VP contains one or several VC-s; it may become awkward to say that a VP is not LD but some sub-structure is. (It is easier to declare, in a context file, that a sub-structure of a JSON-LD document is a "plain" JSON: that is why the JSON-LD WG introduced the json data type.)
I think this argument can also be made about DID resolution results. While it's not very common to have proofs on a DID resolution result, it's certainly possible in some scenarios, so there could be value in being able to add proofs to DID documents and to DID resolution results in a coherent way.
I cannot judge that, not having enough experience and knowledge to decide whether that is a realistic scenario. But, if I understand it well, the idea is to issue a VC whose subject is a DID resolution result. Though awkward, this could be done by somehow saying that the subject is a specific JSON structure...
the idea is to issue a VC whose subject is a DID resolution result
No that's not quite what I meant. Data Integrity proofs can be used to secure any kind of JSON-LD/RDF data, not just VCs. You can add a Data Integrity proof to a DID document, and to a DID resolution result, without doing anything with VCs.
This was discussed during the did meeting on 03 April 2025.
View the transcript
w3c/did-resolution#137
ottomorac: Ivan and Markus provided input here. Any other input?
manu: I think we should use JSON. I don't think there's a strong argument for JSON-LD in the resolution spec.
… Ivan did raise it, but we would object to using JSON-LD for the API calls, but the data is JSON-LD. I don't think there's a strong argument for JSON-LD in the API.
… I'll note that the reason we're saying this is that this is exactly what we did in the VC API.
ottomorac: ok, makes sense.
This was discussed during the #did meeting on 24 April 2025.
View the transcript
Should we use JSON or JSON-LD for the resolution spec?
<ottomorac> w3c/
ottomorac: Briefly touched on this in the APAC call. manu voiced wanting to just use JSON
manu: Yep, since them markus_sabadello has mentioned that a benefit of using JSONLD means you could fully digitally sign the response that came back.
… Resolvers could sign all their responses
… I found this compelling as an argument
… Wondering if we could through data integrity still use JSON and use JCS based signatures instead
… We could optionally express this response using JSONLD
… Meaning we could keep it JSON, Use data integrity with JCS to sign the responses. And not flat our require JSONLD processors
… Trying to find a way to define DID resolution responses in JSON
… We almost certainly will have a context. If we do that, we should probably change the context from v1 to v1rc1
… We have found people will ship v1 to production so the group can't easily change the context
… This creates confusion
… Lets use v1rc1 for all examples in the spec to contain some of these issues
ivan: Not sure I understand manu. First, I raised this issue a while ago. I think what manu said about using JCS is fine. We can and should use it. That should not be enough of an argument to turn it into JSONLD every time
… Not sure I understand how the context file comes into the picture. If using JSON there is no context
manu: ivan using the context file is about trying to find a middle ground. So people that dont like jcs or rdfc can both be happy
… It would be nice if we could digitally sign the responses from the resolver. If we use data integrity and jcs we dont have to go to rdf
… This doesnt mean that DID resolvers cant also use a different data integrity mechanism
… We don't want to cut ourselves off from future usecases. We say please include the context. Here it is
… If we do that, then I think we leave all options open
markus_sabadello: We don't currently talk about signing resolution responses in the spec. But it has come up in the discussion
… Commenting on manu, if we use jcs then there is no graph canonicalization. However, I thought if you use data integrity with jcs you would still only do that with jSONLD document.
… didnt realise you could do that with plain JSON
<dmitriz> @markus - that's the cool thing about JCS canon -- you can use it without @context! :)
In verifiable presentations you use JSONLD. VPs contain VCs which are JSONLD. In my mind DID document and resolution results work ion a simlar way
ivan: What manu is saying, if we introduce a context then we are using JSONLD. We have to define formally a vocab. Adding complexity. Implementers will see that a context is necessary. Some will complain that they dont want to use JSONLD etc etc
… For applications like VC, there are good arguments why JSONLD is useful
… For something else, like resolution, the resolution data that you use is not combined with other data
… if you are not combining, then rdf is not necessary
<Zakim> manu, you wanted to comment on including signing.
manu: agree with ivan. With DID resolution I am not sure if this is true
<smccown> JSONLD is really useful. However, from a security perspective, the "linked" parts never seem to be covered by signatures.
manu: I am just trying to keep the door open
<JoeAndrieu9> once we start signing it becomes an open system unless we restrict the signing to a specific algorithm
manu: we might want to include signing in the DID resolution spec. It keeps coming up
… We should say it is possible to sign these things
@iherman @msporny To follow up on today's discussion, I'd be interested in your thoughts:
-
Can Data Integrity really be used to secure non-LD JSON documents? I understand that it could theoretically be done (using JCS), but I have never really heard about anyone doing that or seen any examples.
-
Why do Verifiable Presentations (VPs) use JSON-LD? It's clear why VCs use JSON-LD, but why VPs?
- Can Data Integrity really be used to secure non-LD JSON documents? I understand that it could theoretically be done (using JCS), but I have never really heard about anyone doing that or seen any examples.
Yes, it can, it's the very first example in the DI spec:
https://w3c.github.io/vc-data-integrity/#example-a-simple-json-data-document
... and there are two cryptosuites that can use JCS:
https://w3c.github.io/vc-di-ecdsa/#ecdsa-jcs-2019 https://w3c.github.io/vc-di-eddsa/#eddsa-jcs-2022
As for real world examples, did:webvh uses ecdsa-jcs-2019 to digitally sign cryptographic logs and some of the ActivityPub'ers are using it to sign ActivityPub objects.
- Why do Verifiable Presentations (VPs) use JSON-LD? It's clear why VCs use JSON-LD, but why VPs?
Because we want to be able to present things other than VCs using VPs. Concretely, we want to present ZCAPs using a VP, but haven't standardized that yet... and there are potential use cases where you want to present raw data blobs, signed using your DID, but which are not VCs. IOWs, a Verifiable Presentation need not be only about a VC (open world).
- Why do Verifiable Presentations (VPs) use JSON-LD? It's clear why VCs use JSON-LD, but why VPs?
Because we want to be able to present things other than VCs using VPs. Concretely, we want to present ZCAPs using a VP, but haven't standardized that yet... and there are potential use cases where you want to present raw data blobs, signed using your DID, but which are not VCs. IOWs, a Verifiable Presentation need not be only about a VC (open world).
Additionally: ~JSON-LD~ RDF is all about combining data coming from different sources and vocabularies. A VP may want to combine several VC-s coming from different issuers, and the danger of term clashes are increased if plain JSON is used.
It feels a bit strange to me to have an "outer" JSON structure with a nested "inner" JSON-LD structure, and that both could contain Data Integrity proofs.
E.g. I guess it would look like this:
{
"didDocument": {
"@context": "https://www.w3.org/ns/did/v1.1",
"id": "did:example:123456789",
"alsoKnownAs": ["https://example.com/"],
"authentication": [
{
"id": "did:example:123456789#keys-1",
"type": "Ed25519VerificationKey2018",
"controller": "did:example:123456789",
"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
}
],
"proof": {
}
},
"didResolutionMetadata": {
"contentType": "application/did"
},
"didDocumentMetadata": {
"created": "2019-03-23T06:35:22Z",
"updated": "2023-08-10T13:40:06Z",
"equivalentId": [
"did:example:abcdefghi"
]
},
"proof": {
}
}
In the inner proof, you could use either JCS or RDFC-1.0, whereas in the outer proof, you could use only JCS. It feels inconsistent.
Another inconsistency would be that we have a DID document property alsoKnownAs and a DID document metadata property equivalentId. In the above example, alsoKnownAs would be "real linked data", whereas equivalentId would be "just a JSON property". Also see https://github.com/w3c/did-resolution/issues/115.
If we decide to make the change to plain JSON, we'd also need different media types; so far we have been using application/ld+json;profile="https://w3id.org/did-resolution" and application/ld+json;profile="https://w3id.org/did-url-dereferencing"
It feels a bit strange to me to have an "outer" JSON structure with a nested "inner" JSON-LD structure, and that both could contain Data Integrity proofs.
Hmm, it doesn't feel strange to me, but I do understand how it could also feel disharmonious. I do think this comes down to how people think about JSON-LD.
My perspective is that the intent of JSON-LD was to provide the ability to use as much of linked data as made sense for the particular use case (and no more). Only later did the "must be compatible with RDF" and "polyglots are bad" come along during the standardization of the technology, which then started to be interpreted as "JSON-LD is synonymous with mandatory JSON-LD/RDF processing" that many of its detractors (and even some of its fans!) seem to be keen on repeating.
So, in my interpretation, it's perfectly reasonable to have a JSON payload protected with an outer proof that is DI using JCS, with variations of JWT, COSE, and DI using RDFC inside as a subtree within the outer JSON payload. Those that choose to process as JSON-LD can choose to do so, and those that want to just stick to JSON can choose to do that instead. We would want some language about the semantics being equivalent no matter what you choose to do and that you MUST NOT break JSON-LD processing for those that choose to do it.
Alternatively, forcing alignment of the outer structure with whatever is in the nested inner structure feels more rigid with the only benefit being that implementations would be forced to align on using JSON-LD, using RDFC, and thus would have less implementation burden (which does have its benefits), but at the cost of annoying the people that want to use DIDs but don't want to be forced to use JSON-LD. I think, as I have been consistently arguing over the past decade, that we should make concessions for that community if we can do so without causing harm to the overall solution. The cost of doing that is implementation burden.
I may not agree with all the details on the history of JSON-LD with Manu 😉, I do agree with the general conclusion...
Okay thanks for explanations, fine with me to change to non-LD JSON :)
Any suggestions for media type? E.g.
application/json;profile="https://w3id.org/did-resolution"application/did-resolution+json
Also, should we just use the same media type for a DID Resolution Result and for a DID URL Dereferencing Result, or different ones? E.g.
application/json;profile="https://w3id.org/did-url-dereferencing"application/did-url-dereferencing+json
It seems that the mood of the day is not to use +json any more…
The media type for DID is now application/did and that indicates that we should probably use application/did-resolution and application/did-url-dereferencing.
It seems that the mood of the day is not to use +json any more…
If it is expected that alternative encodings could be defined in the future (CBOR comes to mind), and since we are not in the complicated case where we would like to express more than 2 "layers" (contrast to +ld+json), I would not necessarily rule that out...
I would advise against application/json;profile="https://w3id.org/did-url-dereferencing", notably because URI in profiles are known to have some issue w3c/json-ld-syntax#436
I think it's fine (and appropriate) to use application/thing+json, application/thing+cbor, application/thing+other-structured-suffix; just not two structured suffixes, so no application/thing+json+cbor.
If there comes another day when we wish we could use something like +foo+bar, we could then instead define a new structured suffix like +foo-bar (or +bar-foo).
This was discussed during the #did meeting on 15 May 2025.
View the transcript
Should we use JSON or JSON-LD for the resolution spec?
<Wip> w3c/
wip: wonder where we are on this...
manu: I think consensus was to use JSON for the responses....
manu: unusure about the resolution vocabulary part...
markus_sabadello: Yes i think I remember that was the agreement...
<Zakim> manu, you wanted to have an opinion about suffixes.
markus_sabadello: think the error codes should have any bearing on it...
manu: yes for the media type we should use a + sign
manu: plus signs create complexity....
manu: we should probably avoid those
manu: regarding the error codes having any bearing.... for now suggest we just put the error codes in the did vocab...
wip: any takers?
markus_sabadello: yes I will take it...
Addressed by https://github.com/w3c/did-resolution/pull/152, marking as pending-close.