Our Documentation Shows a Credential Format Our Live Issuer Does Not Serve. Here Is the Command That Proves It.

The gap on this page is ours, we found it by checking our own wire format against our own documentation, and it is still open.

Two credential families, and why it matters which one you get

A verifiable credential can be serialised in more than one way, and the choice determines which libraries can read it.

One family is the linked-data path. Every field name points at a shared vocabulary through a @context, so name is not just the string "name" but a term with a defined meaning that two systems can agree on without a prior conversation. The signature covers a canonical form of that structure.

The other family wraps the credential in a signed token. Compact, familiar to anyone who has handled a JSON Web Token, and read by a completely different set of libraries.

A verifier built for one cannot parse the other. Not "with some work". The parsing, the signature checking and the field lookup are all different.

The trap in the linked-data path

The @context is a URL, and that has consequences people meet at the worst moment.

Something has to resolve it. Either the processor fetches it at verification time, which puts a network dependency inside a security check, or it ships with a cached copy, which means a context change breaks verification until every cache is updated.

And getting the property name wrong is fatal rather than cosmetic. A processor looking for @context and finding context does not warn you. It fails to interpret the document.

Why this page exists

Because the failure mode here is silent and expensive. Nobody discovers a format mismatch by reading. They discover it when a parser returns nothing on data that looks correct.

The general rule is worth more than our particular case: read the wire, not the documentation. For any vendor, the metadata endpoint is one request and it settles the question that a week of specification reading does not.

What to ask any credential vendor

"What format does your live issuer actually serve?" Ask for the metadata URL rather than the answer, then fetch it yourself. Ours is above.

"Does your documentation match it?" Ours does not, currently, and we would rather tell you than have you find out.

"If you use the linked-data path, is the context fetched or cached?" Fetched puts a network dependency in a security check. Cached means a context change is a coordinated upgrade.

"Which libraries can verify what you issue?" The honest answer names them. The evasive answer says "standards-based".

Where this leaves a decision

If your stack is built for linked-data credentials, we do not serve them today, and our documentation showing them is a defect on our side rather than an option on yours.

If your stack handles signed tokens, that is what our issuer serves right now, you can confirm the format in one request before talking to anyone here, and the ability to check a vendor claim without asking the vendor is the property worth insisting on generally.