Standardize error responses with RFC9457ProblemDetails

[erdemonal11]

Hi, While reviewing the OpenAPI spec, I noticed the error responses (e.g., 404, 501) only have a description and lack a content schema. This leaves the structure of the error body undefined for client implementers.

The spec already includes the RFC9457ProblemDetails schema, which is perfect for this purpose. I propose updating all 4xx and 5xx error responses to reference this schema.

For example, the 404 response could be:

"404":
  description: DID or DID URL not found.
  content:
    application/problem+json:
      schema:
        $ref: "#/components/schemas/RFC9457ProblemDetails"

This change would make the API's error handling consistent and more predictable.

Thanks.

[peacekeeper]

@erdemonal11 This makes sense to me.. Do you perhaps want to try and write a Pull Request which addresses this?

[erdemonal11]

@peacekeeper I will write a pull request for this.

[w3cbot]

This was discussed during the #did meeting on 16 October 2025.

View the transcript

w3c/did-resolution#212

ottomorac: This is related to standardising error responses

<ottomorac> PR updates the OpenAPI specification to provide a consistent error response structure, related to issue 212: w3c/did-resolution#212 Markus had some comments on the proposed change.

ottomorac: Markus has responded and suggested discussion this in the group

<ottomorac> w3c/did-resolution#215

manu: We are dealing with this in the VCALM group

<manu> https://github.com/w3c-ccg/vcalm/blob/28f2a1a2cb71befeee9b5eb7ee48bb89e368232c/components/ProblemDetails.yml#L15

manu: We have standardised on problem details as the error object
… I think it is a good idea. We should standardize on this. We want to use problem details across the VC and DID ecosystem
… This has worked really well across implementations
… I am not sure what the current mechanism we are using
… We might want to define this more generally across W3C specs, but dont need to do that yet

markus_sabadello: We have already adopted the problem details in DID resolution
… This question is to do with if there is an error, do we return the DID resolution result containing the problem details in the metadata
… Or do we return only the problem details

manu: Thats great, its a good question. In the VCAPI group the verify credential call returns the verified credential
… We also had a concept of returning warnings and errors
… There are times when you might want to return warnings and results
… E.g. we had to use a cache beyond the timeout
… The result would include multiple things. The result. A set of warnings. A set of errors
… I am not sure if this applies for the DID resolver

markus_sabadello: I agree with all that. There are situations when you might return a DID document along with some problems
… The PR says, that in case of an error they will return just the problems
… I will respond on the issue and summarise the pros and cons we just discussed

---

[w3cbot]

This was discussed during the #did meeting on 11 November 2025.

View the transcript

w3c/did-resolution#212

wip: I think there is already a PR for this

joeandrieu: in that PR it seems that the involved parties have come to agreement

wip: great. Then we can remove the "discuss" label

joeandrieu: are we going to merge it?

wip: I'm going to ask Markus

---