We Publish a Document That Names a Standard It Does Not Currently Match

The defect described below is ours, it is live, and we found it while writing this page.

What the document is for

Resolving an identifier returns a document. That document answers one question a verifier actually needs: which public keys may act for this identifier, and for what.

Signing keys, keys for encryption, keys permitted to update the identifier itself. A verifier reads it, finds the key that signed a credential, and checks the signature.

Everything about portable identity rests on that lookup returning something a stranger's software can parse without special-casing you.

Why the format is the whole point

The document is the interoperability surface. A credential can be perfect and useless if the document naming its issuer's key cannot be read by standard tooling.

So the specification is strict about small things: what a key property is called, and how the key material is encoded. Those look like pedantry until somebody else's resolver has to read your output without a bespoke adapter.

What ours currently emits, checked rather than described

Two things do not conform, and we verified both against the live network while writing this.

The resolver returns a key property that is not in the specification. Our document declares a key type from a named W3C suite, then carries the key material in a property that suite does not define. The suite requires a specific multibase property; we emit a hex one.

And the conversion to the standard shape produces a value a strict resolver cannot decode. The suite requires the key to be encoded with a two-byte prefix identifying the algorithm, so a correct value decodes to thirty-four bytes. Ours base58-encodes the raw thirty-two-byte key with no prefix.

Those produce different strings. Software following the specification decodes ours, finds thirty-two bytes where it expects thirty-four with an algorithm header, and fails to load the key.

Why we are publishing this rather than fixing it quietly

Because the gap is not really about encoding. It is that our identifier method is registered in the W3C DID Method Registry, and we say so on several surfaces.

A registry entry reserves a name and points at a published specification. It is not approval, not endorsement and not conformance testing, and we have written that carefully everywhere it appears. But it does carry an implication that the documents we serve match the specifications they name, and right now they do not.

That is the same failure this whole site keeps documenting in other people's material: something has been given a name it does not currently earn. Finding it on our one registered artefact is uncomfortable, which is exactly why it goes on the page rather than into a backlog.

What it does and does not break

It does not break our own products. Our software reads its own documents, and the signature checking works, which is why this survived.

It breaks the case the method exists for: a stranger's standards-compliant resolver reading our document without special-casing us. That is the entire argument for using an open identifier standard rather than an internal key registry, so the defect lands squarely on the value proposition.

And the fix is small. Two places, a two-byte prefix, and a property name. It is a shipping task rather than a design problem, which is the honest scale of it.

The test that would have caught it, and would catch it again

Round-trip a key-derived identifier. Those identifiers are already the correctly-prefixed form by construction, so an implementation that handles one correctly cannot make this mistake, and one that does not will fail immediately.

We did not have that test. A conformance claim without a conformance test is a claim about intentions, and this is what that looks like in practice.

What to ask any project with its own identifier method

"Show me a resolved document, and let me decode the key myself." It takes a minute and it is the only check that settles this.

"Has any resolver other than yours read it successfully?" Reading your own output proves the loop, not the standard.

"What conformance tests do you run, and where are the results?" For us today: none, and that is how this happened.

"Registered or conformant?" They get used interchangeably. Ours is registered, and as of this page not conformant in the way described above.

Where this leaves a decision

If you need documents that third-party tooling reads today without adaptation, we do not meet that right now, and the specific reason is written above rather than left for your engineer to discover.

If you are evaluating anyway, the useful signal is not that the defect exists, since most implementations have had one. It is that we found it, published it with the exact values, and treated it as a shipping task with a named test rather than as something to be quiet about.