Did Core

Skill based on W3C DID Core (did-core repo), generated 2026-02-24.

Decentralized Identifiers (DIDs) are URIs that point to DID documents, enabling verifiable, decentralized identity. This skill covers the DID Core data model, syntax, core properties, verification methods, services, serialization (representations), and the requirements for DID methods and resolution.

Core References

Features

Best Practices

Generation Info

• Source: sources/did-core
• Git SHA: 9a4d0c491bb5745a9718ca7f8e6fceb5dbacb483
• Generated: 2026-02-24

Documentation was read from the W3C DID Core repository. Primary spec source: index.html (Decentralized Identifiers v1.1). Supporting vocabulary: vocab/vocabulary.yml. No dedicated docs/ folder; the spec is the single authoritative document in the repo root.

DID Resolution and DID URL Dereferencing

DID resolution turns a DID and resolution options into a DID document (plus metadata). DID URL dereferencing turns a DID URL and options into a resource (e.g. the document, a fragment, or an external resource). Use this when implementing or choosing resolvers and when dereferencing DID URLs to keys or services.

DID resolution

• Input: DID + resolution options (e.g. version, accept).
• Output: DID document in a conforming representation + metadata (e.g. resolution metadata, document metadata).
• Process: Defined in the DID Resolution specification; the resolver uses the Read operation of the applicable DID method and verifies authenticity of the response.

Implementations need a resolver (or resolver driver) for each DID method they support. Universal resolvers may delegate to method-specific drivers.

DID URL dereferencing

• Input: DID URL + dereference options.
• Output: A resource—e.g. the full DID document, a secondary resource (e.g. verification method) identified by the fragment, or an external resource.
• Process: Resolution is used to obtain the DID document for the DID in the DID URL; then the dereferencer applies fragment/path/query semantics to return the appropriate resource. Details are in the DID Resolution spec.

Example: did:example:123#keys-1 → resolve did:example:123 → return the verification method with id equal to that DID URL (or fragment keys-1 within the document).

Choosing DID resolvers

When selecting or recommending a DID resolver:

• Prefer resolvers that follow the DID Resolution specification and return conforming DID documents and metadata.
• Consider trust: resolution may involve networks (e.g. DLT) or third-party endpoints; ensure the resolver’s trust model and integrity guarantees match the use case.
• Consider privacy: resolution can leak which DIDs an application is interested in; use privacy-preserving or local resolution where required.
• For production, prefer resolvers that support the DID methods you use and that document security, availability, and update behavior.

Key points

• Resolution returns a DID document (and metadata); dereferencing returns a resource that may be the document, a part of it, or an external resource.
• Fragment semantics should be consistent across representations so that the same DID URL yields the same logical resource regardless of representation (e.g. JSON vs CBOR).
• DID method specs define how resolution (Read) works for that method; use method-specific drivers or universal resolvers that integrate them.

<!-- Source references:

• https://www.w3.org/TR/did-core/#terminology (DID resolution, DID URL dereferencing)
• https://www.w3.org/TR/did-core/#choosing-did-resolvers
• https://www.w3.org/TR/did-resolution/
• sources/did-core/index.html

-->

DID and DID URL Syntax

Decentralized Identifiers (DIDs) and DID URLs follow URI-like syntax. Use this when parsing, validating, or constructing DIDs and DID URLs programmatically.

DID syntax (ABNF)

Generic DID scheme (RFC 3986–compliant):

did                = "did:" method-name ":" method-specific-id
method-name        = 1*method-char
method-char        = %x61-7A / DIGIT
method-specific-id = *( *idchar ":" ) 1*idchar
idchar             = ALPHA / DIGIT / "." / "-" / "_" / pct-encoded
pct-encoded        = "%" HEXDIG HEXDIG

• Scheme: did:
• Method name: lowercase letters and digits (e.g. example, key, ethr).
• Method-specific id: unique per method; colons allowed inside; no ? or # for subject/controller identifiers.

Example: did:example:123456789abcdefghi.

DID URL syntax (ABNF)

DID URL = DID + optional path, query, and fragment:

did-url = did path-abempty [ "?" query ] [ "#" fragment ]

Path, query, and fragment follow RFC 3986. Semicolon (;) is reserved; avoid using it in DID URLs.

Path, query, fragment

• DID path: same as URI path (e.g. did:example:123456/path). Semantics are method- or application-specific.
• DID query: same as URI query (e.g. did:example:123456?versionId=1). No generic normalization; avoid equivalence checks when multiple query parameters exist.
• DID fragment: references a resource inside the DID document or an external resource (e.g. did:example:123#public-key-1, did:example:123#service-5). Fragment semantics should be consistent across representations.

Relative DID URLs

A relative DID URL in a DID document is any URL value that does not start with did:<method-name>:<method-specific-id>. Resolve it using RFC 3986 Section 5 (Reference Resolution) with the document’s DID as the base URI (scheme did, authority method-name:method-specific-id).

Use relative URLs to reference verification methods or services without repeating the full DID (saves space and keeps documents stable when the DID is fixed).

{
  "@context": "https://www.w3.org/ns/did/v1.1",
  "id": "did:example:123456789abcdefghi",
  "verificationMethod": [{
    "id": "did:example:123456789abcdefghi#key-1",
    "type": "Multikey",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyMultibase": "z6Mkm..."
  }],
  "authentication": ["#key-1"]
}

#key-1 resolves to did:example:123456789abcdefghi#key-1.

Key points

• Subject and controller identifiers must be DIDs only (no query or fragment).
• Verification method and service id values follow DID URL syntax (fragments allowed).
• Method-specific-id may contain colons; meaning is method-specific.
• For long-lived canonical identifiers, avoid query parameters to simplify resolution and reduce attack surface; keep fragment identifiers unique within a DID document.

<!-- Source references:

• https://www.w3.org/TR/did-core/ (DID Syntax, DID URL Syntax, Path, Query, Fragment, Relative DID URLs)
• sources/did-core/index.html

-->