Standardize error responses per id (#212)

[erdemonal11]

Fixes #212

This pull request updates the OpenAPI specification to provide a consistent error response structure, as discussed in the issue.

It adds a content block referencing RFC9457ProblemDetails to all 4xx and 5xx error responses.

[peacekeeper]

@erdemonal11 I know I agreed with your idea in my comment https://github.com/w3c/did-resolution/issues/212#issuecomment-3386218963, but now after reviewing the PR, I am wondering if this change is really the right thing to do.

My interpretation of the current spec text is that in case of an error, a resolver would still return a full ResolutionResult (which can contain a RFC9457ProblemDetails), rather than returning only the RFC9457ProblemDetails.

But maybe we should discuss this in the WG.

In other words, I think the question is whether the error response content should look like this:

{
    "didDocument": null,
    "didResolutionMetadata": {
        "error": {
            "type": "NOT_FOUND",
            "title": "The DID or DID document was not found.",
            "detail": "No resolve result for did:method:BDrEcHc8Tb4Lb2VyQZWEDE"
        }
    },
    "didDocumentMetadata": {}
}

Or like this:

{
    "type": "NOT_FOUND",
    "title": "The DID or DID document was not found.",
    "detail": "No resolve result for did:method:BDrEcHc8Tb4Lb2VyQZWEDE"
}

[peacekeeper]

@erdemonal11 We discussed this in the DID WG meeting yesterday: https://www.w3.org/2025/10/16-did-minutes.html#d627

In this meeting, we thought that it's better to leave things as-is. In other words, in case of an error, we include the RFC9457ProblemDetails as part of the DID resolution metadata, rather than returning only the RFC9457ProblemDetails itself.

Would this be fine with you, or do you see any problems with this?

[erdemonal11]

@peacekeeper It is fine for me I checked and I don't see any problems.

[peacekeeper]

@peacekeeper It is fine for me I checked and I don't see any problems.

Thank you, in this case should we close this PR here?

Alternatively you could update the PR so the 4xx and 5xx responses reference ResolutionResult or DereferencingResult, instead of RFC9457ProblemDetails.

[erdemonal11]

@peacekeeper The error responses now reference ResolutionResult and DereferencingResult as decided, so the technical changes should be complete.

[w3cbot]

This was discussed during the #did meeting on 04 December 2025.

View the transcript

w3c/did-resolution#215

ottomorac: this one has no review yet

<JoeAndrieu> Alternative language from "the metadata ... or from the did method" to something about "from the did resolver, as defined by the did method"

ottomorac: probably one for Markus, but maybe others have feeedback?

<swcurran> swcurran: The DID Method defines the metadata, and JoeAndrieu noted that the DID Resolver implements and could be compromised.

---

[wip-abramson]

This has 1 approval, looks like it could be merged. Can I just override the IPR bot here?