INTERNAL_ERROR not defined in W3C DID vocabulary

[djscruggs]

Summary

The HTTPS Binding spec references INTERNAL_ERROR as a valid DID resolution error type, but the URI https://www.w3.org/ns/did#INTERNAL_ERROR is not defined in the W3C DID vocabulary document at https://www.w3.org/ns/did.

Impact

Implementations that return RFC 9457-style error objects with "type": "https://www.w3.org/ns/did#INTERNAL_ERROR" are using an undefined URI, which breaks the linked data contract.

Suggested fix

Add INTERNAL_ERROR to the vocabulary document alongside the other defined error types (INVALID_DID, NOT_FOUND, METHOD_NOT_SUPPORTED, etc.).

Context

Found while implementing the HTTPS Binding in digitalbazaar/did-resolver.

[peacekeeper]

@djscruggs I don't think INTERNAL_ERROR or other error codes need to be in a vocabulary, because these codes appear as values of the "error" metadata property. Metadata is not JSON-LD. This was discussed in the WG a while ago, and it was decided that for metadata we don't need the semantic richness provided by RDF / JSON-LD vocabularies and contexts.

One place where we list the error codes is the following, we actually need to update this regarding the casing, e.g. invalidDid -> INVALID_DID:
https://www.w3.org/TR/did-extensions-resolution/#error

Does this make sense? Or do you think the error codes need to be in vocabularies?

Or have you maybe found a document where specifically the INTERNAL_ERROR code is missing?

[djscruggs]

@peacekeeper honestly I'm in over my head with this one. @msporny suggested I file this because it touches on some other work I'm doing. That said, he may have forgotten the WG discussion and conclusions. I've asked him to take a look at this but he is overseas at the moment. Please keep this open until he weighs in.

[msporny]

@peacekeeper wrote:

@djscruggs I don't think INTERNAL_ERROR or other error codes need to be in a vocabulary, because these codes appear as values of the "error" metadata property. Metadata is not JSON-LD. This was discussed in the WG a while ago, and it was decided that for metadata we don't need the semantic richness provided by RDF / JSON-LD vocabularies and contexts.

Ah, right, thanks for the reminder @peacekeeper. Yes, agree that metadata is not JSON-LD. That said, the error URLs used in the spec do point to the DID vocabulary (IIRC), and that is where someone lands if they put the URL in. While it's not absolutely necessary, it would be nice if anyone putting the URL into a browser lands on some human readable documentation about the error.

I think that's what this request is for: Can we put some human readable text at the end of that URL?

We could have the URLs in the DID Resolution spec point elsewhere if we didn't want to add them to the vocabulary. It also doesn't harm anything to define them (and not necessarily use them in the JSON-LD Context.

One place where we list the error codes is the following, we actually need to update this regarding the casing, e.g. invalidDid -> INVALID_DID: https://www.w3.org/TR/did-extensions-resolution/#error

Hmm, yes, we should fix that.

Does this make sense? Or do you think the error codes need to be in vocabularies?

It would be nice if dereferencing the ERROR code URLs would result in human-readable text that could point people to the vocabulary and then the specification.

[djscruggs]

It would be nice if dereferencing the ERROR code URLs would result in human-readable text that could point people to the vocabulary and then the specification

Yes, speaking as someone working on this for the first time, I found the urls very confusing. I expected something like the Mozilla documentation e.g. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/500

[wip-abramson]

I think that's what this request is for: Can we put some human readable text at the end of that URL?

This makes sense to me.

So the action is to add all DID Resolution errors into the DID vocabulary. Which I guess is here - https://github.com/w3c/did/tree/main/vocab?

Can we transfer this issue across to https://github.com/w3c/did?

[swcurran]

@pchampin / @msporny -- do one of you have the power to transfer this PR? I tried and am unable to do so.

Per the previous comment, that is the desired next step for this issue.

Thanks

[wip-abramson]

I used my powers to transfer this