Consider use of "Problem Details" in case of errors

[peacekeeper]

At the moment, the specification defines various errors that can be returned by the DID Resolution and DID URL Dereferencing functions:
https://w3c.github.io/did-resolution/#errors

During the 29 Aug 2024 DID WG meeting, it has been suggested that the "Problem Details" specification (RFC9457) could be used here as well.

[pchampin]

This was discussed during the did meeting on 23 January 2025.

View the transcript

w3c/did-resolution#87

markus_sabadello: This has been addressed -- exists. We have resolution and dereferencing result. Pending closed.

manu: Good idea to settle on Problem Details. Handled in other specs and works well. Nice if the DID Resolution spec so there was consistency across the specs (DI, DID, others)/.

ivan: Formerly -- if have a DID error, inherits the CID error, so that covers it.

Wip: Argument to put it in the spec. Any takers to put it in?

manu: I'll volunteer.

---

[peacekeeper]

The thing about this issue is that we have some language in the CID spec on how to return errors (using RFC9457), and we also have language in the DID Resolution spec on how to return errors.

We also have concrete lists of errors in the CID spec (e.g. INVALID_CONTROLLED_IDENTIFIER_DOCUMENT_ID, and we also have concrete lists of errors in the DID spec (e.g. invalidDid) and in DID extensions.

Theoretically they could both be returned as part of DID Resolution Metadata, e.g. something like this:

{
  "didDocument": null,
  "didDocumentMetadata": { },
  "didResolutionMetadata": {
    "error": "invalidDid",
    "problemDetails": {
      "type": "https://w3id.org/security#INVALID_CONTROLLED_IDENTIFIER_DOCUMENT_ID",
      "title": "The resolved DID is invalid.",
      "detail: "Parse error of the resolved DID at character 3, expected ':'."
    }
  }
}

But maybe we want to align a bit more than that, i.e. only have a single way of returning (and registering) errors, shared between CID and DID.

[ankurdotb]

+1 to this, it will be hugely useful

Would error and problemDetails.type become redundant though? I assume problemDetails.type, since the RFC asks it to be a URL, will need to return the specific error section title of the DID Resolution spec, e.g., for invalidDid, the problemDetails.type will be https://www.w3.org/TR/did-resolution/#invaliddid (actual version rather than TR in the middle of the URL)?

[wip-abramson]

I am taking a look at addressing this along with #136. Wondering where we landed on:

But maybe we want to align a bit more than that, i.e. only have a single way of returning (and registering) errors, shared between CID and DID.

If we were to only have a single way following the problem detail approach, I think using the error property would make sense. I would be in favor of this approach.

Also, @ankurdotb I think we would follow the CID approach - https://www.w3.org/TR/cid-1.0/#processing-errors - and use the https://w3id.org/security# as the base URL.

Finally, as I understand Problem Details, when the Resolver is called over HTTP these errors would be returned separately, or instead of a DID resolution result. Is that correct?

From the CID spec:

When exposing these errors through an HTTP interface, implementers SHOULD use [RFC9457] to encode the error data structure

Or would this kind of response still be a valid application of problem details.

{
  "didDocument": null,
  "didDocumentMetadata": { },
  "didResolutionMetadata": {
    "error": {
      "type": "https://w3id.org/security#INVALID_DID",
      "title": "The resolved DID is invalid.",
      "detail: "Parse error of the resolved DID at character 3, expected ':'."
    }
  }
}

[peacekeeper]

If we change the "error" metadata property to an object, it will break compatibility with DID 1.0, which says:

error - The error code from the resolution process. This property is REQUIRED when there is an error in the resolution process. The value of this property MUST be a single keyword ASCII string.

Some errors like "invalidDid" and "notFound" are also defined by DID 1.0.

What's more important, keeping compatbility with DID 1.0, or aligning fully with CID 1.0? Or we just return error in both ways, as I showed in my earlier example above...?

[wip-abramson]

Good point @peacekeeper. I think compatibility with DID 1.0 is more important, I like your proposal to support both approaches.

So for something like invalidDid which is already defined. Would we additionally define a problem details type of INVALID_DID.

Also, are we saying that errors should always define both:

• A single keyword e.g. invalidDidDocument
• A problem details type: INVALID_DID_DOCUMENT (and title?)

[peacekeeper]

support both approaches

Yes I think that's what I'm proposing, even though it does create some redundancy. We could define that the value of "error" and "problemDetails.type" are always the same, except for capitalization and the base error URL, i.e. like in your example

(error) invalidDidDocument = (problemDetails.type) https://w3id.org/security#INVALID_DID_DOCUMENT

[wip-abramson]

Yep, that makes sense.

Less sure now if we would use the base error URL as https://w3id.org/security That takes you to the VC Data Integrity security vocabulary. We may need/want to define our own vocab, if there isnt one already.

[w3cbot]

This was discussed during the #did meeting on 17 April 2025.

View the transcript

DID Resolution: Consider use of "Problem Details" in case of errors

<ottomorac> w3c/did-resolution#87

ottomorac: on this PR, we said initially that it's a good idea to settle on some problem details,
… there was some agreement to put it in the spec
… not sure if Manu had a chance

manu: no, I've not had any time, and forgot completely about it. it's on the queue

ottomorac: ok, if people agree with the issue, we can just move on

Wip: I thought I'd take this on, Manu.
… the issue is adding Problem Details to define errors
… the DID spec just has a generic 'error' property and string name
… as I looked into the issue, -- should we be supporting BOTH the 'error' property from the 1.0 spec, AND the details approach from the CID spec
… for backwards compat

manu: I might be confused.. the Problem Details thing is on the DID Resolution spec
… and we're not bound to any class of changes there, since it's new
… we're also defining a vocab for resolution, right Markus?

<Wip> thats true actually

manu: I know that, Ivan, somewhere on the internet, there's an issue about needing a vocab for DIDs
… anyways, the Problem Details enums go into one of those two
… but neither one of them are in theory normative
… so we just need to figure out which vocab doc (DID or DID Resolution)
… the Security vocab might have some very generic problem types we might want to reuse?... looking..

<ivan> I think Manu refers to this: w3c/did#884

manu: stuff like 'invalid controller' etc
… so maybe we'll reuse some terms from Security vocab. and some things are very DID-Resolution-specific, that we'll define in its vocab
… does that give you a clear path forward?

Wip: kind of, I want to hear what Markus has to say

markus_sabadello: in DID Resolution, we have a JSON-LD context, we don't have a vocab
… I agree that the Problem Details should be in the DID Resolution vocab, we'll add it there. and agree we'll look through Security vocab and see what we can reuse
… only issue is -- we have already defined a few error codes in DID Core 1.0
… so we're somewhat bound by that
… like 'invalid did' and 'not found'
… and they're capitalized in a different way than in the Problem Details and CID spec
… so that's the only remaining question - how do we align/reconcile

<Wip> +1 that is where I am confused too

ivan: manu, you opened the floodgates
… there are several things here. yes, first of all, we need a proper vocab for DID Core,
… and I raised an issue several weeks ago on this
… we have the tools inherited from the VC WG to do that, so it just must be done
… as a side question -- in VC, what we agreed upon is that the vocab definition itself, which is an HTML file, a TTL file, and a JSON-LD file for vocabs, are non-normative
… the normative definition must be in the spec
… DID Resolution -- there are two things to be answered
… first, I think it was an issue discussed last week, do we really to use JSON-LD in the DID Resolution spec, or not?
… because if we do, then of course we need a vocabulary, just like DID
… if we don't need to use JSON-LD in the Resolution spec, then it's moot
… the second question is -- provided we want to do JSON-LD in the Resolution Spec, it becomes an editorial question whether we do one big vocab that includes both DID and DID Resolution (so it's easier to maintain), or whether we want to separate the two
… noting that the DID vocab per se (the one I made experimentally) is very small, since DID Core defines only ONE item, it takes the other terms from elsewhere
… re JSON-LD and DID Resolution, my personal belief is that it's unnecessary / uninteresting, we don't need it

<Wip> https://www.w3.org/TR/did-1.0/#did-resolution-metadata

Wip: great, this is less complicated than I thought

<Wip> https://w3c.github.io/did-resolution/#errors

Wip: we do want to take the 3 error codes from DID 1.0
… I thought there were many more
… so, one approach is -- we change all the error codes to be in the Problem Details approach, like the CID spec
… another option is, we continue to support the 'error' property in the result, and ALSO add a 'problem details' property, which is what Markus proposed
… so, looking for directions from the group

<Zakim> manu, you wanted to note we don't need to use JSON-LD for DID Resolution responses.

Wip: so, like for Invalid DID, we keep the error string, and ALSO define a problem details object for it

manu: going back to what Ivan said, I agree with everything he said
… we don't need a vocab for DID Resolution, and we don't need to use JSON-LD at all in the API or responses.
… I don't remember if we have a use case for DID Resolution vocab?
… in any case, I think we only need to define a DID core vocab. and it'll have only one entry
… and that's where we'll put the problem detail definitions
… and because it's non-normative, we can just do that, and be ok

markus_sabadello: I added some thoughts on the JSON and JSON-LD question, in the issue that ivan created
… I would prefer to continue to use JSON-LD for the resolution result
… i don't want to repeat the comments there, I'll paste the link to the issue

ottomorac: moving on to the other topic

---

[wip-abramson]

I am still unsure on the direction for this issue following the discussion in the previous call.

The main question I would like clarity on before proposing a PR is if we are wanting to maintain the previously defined error codes for DID Resolution (https://w3c.github.io/did-resolution/#errors). Three of which were defined in DID Core 1.0 (https://www.w3.org/TR/did-1.0/#did-resolution-metadata).

Or do we want to replace those with a problem details definition and only support problem details for DID resolution moving forward. This would require existing resolver implementations to update their code, but since this is the 1.0 specification I think I agree with @msporny that this is reasonable and within the scope of our charter. Despite three error codes being defined in DID core 1.0.

I feel like issues #136 and #140 are blocked by this issue. We should first decide as a group how we want to define errors for DID Resolution.

[peacekeeper]

Previously I thought we could have both in parallel, but after the last call I now also think that it's best to use only Problem Details. Re-use those error codes defined in Controlled Identifiers, and add new ones that we need for DIDs. I agree it's acceptable to have to update existing resolver implementations.