W3C DID Resolution & Dereferencing

3. Native DID Resolution & Dereferencing

W3C DID Resolution v1 (/1.0/identifiers/*)

Complies strictly with the W3C Candidate Recommendation Draft (1 Oct 2026).

GET /1.0/identifiers/did:web:identity.foundation HTTP/1.1
Host: did.is
Accept: application/did-resolution

Content Negotiation Matrix

Requested Accept Header	HTTP Status	Response Content-Type	Payload Structure
application/did-resolution or application/ld+json;profile="https://w3id.org/did-resolution"	200 OK	application/did-resolution	Full envelope: { "@context", "didDocument", "didResolutionMetadata", "didDocumentMetadata" }
application/did, application/json, */*, or omitted	200 OK	application/did	Raw DID Document JSON only.
Any unsupported media type	406 Not Acceptable	application/problem+json	RFC 9457 REPRESENTATION_NOT_SUPPORTED.
Identifier is deactivated	410 Gone	application/did-resolution	Full envelope with didDocumentMetadata.deactivated: true.

Percent-Encoding Rules

Identifiers in URL paths must be decoded exactly once.

• Standard: /1.0/identifiers/did:web:identity.foundation
• Port numbers: In did:web:example.com:8443, the : must be encoded as %3A: /1.0/identifiers/did:web:example.com%3A8443
• Pre-encoded paths: If the path begins with did%3A (e.g. did%3Aweb%3Aidentity.foundation), the daemon decodes it once.

---

DID.is Enriched Resolution (/v1/resolve/*)

Returns the complete cryptographic dossier behind the identifier:

GET /v1/resolve/did:web:identity.foundation HTTP/1.1
Host: did.is

Response Envelope Structure

{
  "did": "did:web:identity.foundation",
  "method": "web",
  "didDocument": { ... },
  "didResolutionMetadata": {
    "contentType": "application/did",
    "retrieved": "2026-10-01T12:00:00Z",
    "durationMs": 182
  },
  "didDocumentMetadata": { ... },
  "verdict": {
    "outcome": "RESOLVED",
    "headline": "Cryptographically controlled via Ed25519, origin-bound to identity.foundation.",
    "statements": [
      "Document matches identifier rules.",
      "Published Ed25519 public keys lie on valid curve points.",
      "Bidirectional DIF domain linkage credential confirmed."
    ]
  },
  "dimensions": [
    {
      "id": "integrity",
      "label": "Document Integrity",
      "state": "ESTABLISHED",
      "statement": "The document is intact and really belongs to this identifier.",
      "proves": "The document matches its identifier or hash chain.",
      "doesNotProve": "Control of underlying servers."
    },
    {
      "id": "keys",
      "label": "Key Material",
      "state": "ESTABLISHED",
      "statement": "Signing keys are well-formed and lie on valid curve points.",
      "proves": "Cryptographic key well-formedness.",
      "doesNotProve": "Real-world identity of the holder."
    },
    {
      "id": "control",
      "label": "Update Authority",
      "state": "NOT_ESTABLISHED",
      "statement": "Whoever runs the hosting can change it — no key is needed.",
      "proves": "Update mechanism rules.",
      "doesNotProve": "DNS or web host security."
    },
    {
      "id": "origin",
      "label": "Origin Binding",
      "state": "ESTABLISHED",
      "statement": "It is linked to its website in both directions.",
      "proves": "Bidirectional DIF domain configuration.",
      "doesNotProve": "Government corporate registration."
    },
    {
      "id": "transport",
      "label": "Transport Security",
      "state": "ESTABLISHED",
      "statement": "Handshake validated leaf certificate against WebPKI roots.",
      "proves": "Leaf certificate validity, SAN, and expiry.",
      "doesNotProve": "Host operational reliability."
    },
    {
      "id": "history",
      "label": "Verifiable History",
      "state": "NOT_ESTABLISHED",
      "statement": "Past versions cannot be proven on did:web.",
      "proves": "Immutable log state.",
      "doesNotProve": "Real-world conduct."
    },
    {
      "id": "organization",
      "label": "Real-World Identity",
      "state": "NOT_ESTABLISHED",
      "statement": "Who is behind it in the real world is not confirmed.",
      "proves": "Fixed: Always NOT_ESTABLISHED.",
      "doesNotProve": "Any corporate identity."
    }
  ],
  "evidence": {
    "source": { "kind": "HTTPS", "url": "https://identity.foundation/.well-known/did.json", "bytes": 1482 },
    "keys": [ { "id": "...#key-1", "status": "VALID_KEY", "curve": "Ed25519" } ],
    "domainBinding": { "status": "VERIFIED", "origin": "https://identity.foundation" },
    "tls": { "host": "identity.foundation", "daysUntilExpiry": 64, "hostnameInSan": true }
  },
  "graph": { "nodes": [ ... ], "edges": [ ... ] },
  "trace": [ ... ]
}

---

DID URL Dereferencing (/v1/dereference/*)

Dereferences individual fragments, service endpoints, and historical parameters:

# 1. Dereference a specific verification method fragment (#key-1 -> %23key-1)
curl -s "https://did.is/api/v1/dereference/did:web:identity.foundation%23key-1" | jq .contentStream

# 2. Dereference a service endpoint with relative path joins
curl -s "https://did.is/api/v1/dereference/did:web:example.com?service=agent&relativeRef=chat"

Note: DID URL path dereferencing (did:web:example.com/path) is deliberately unsupported and returns HTTP 501 FEATURE_NOT_SUPPORTED.

---

Historical Point-in-Time Resolution (did:webvh)

did:webvh (Verifiable History) maintains an immutable, signed SHA-256 log (did.jsonl). You can resolve any historical state deterministically:

# Resolve version by versionId
curl -s "https://did.is/api/v1/resolve/did:webvh:1234...?versionId=1-QmHash..."

# Resolve state as of a specific UTC timestamp
curl -s "https://did.is/api/v1/resolve/did:webvh:1234...?versionTime=2026-05-01T00:00:00Z"

# Resolve state by sequential version index
curl -s "https://did.is/api/v1/resolve/did:webvh:1234...?versionNumber=3"

---