Resolver Conformance (myum.net)

This page defines the minimum conformance for a UMID resolver at:

• myum.net/{UMID}

The standards/spec/docs site is separate:

• universalmanifest.net

This page is written to be implementation-grade: adopters should be able to implement a conforming resolver using only what is published here.

Resolver conformance levels

To claim “resolver conformance”, an implementation MUST satisfy the requirements below.

Required endpoints

1) Health

GET /health

MUST:

• return 200
• include Cache-Control: no-store

2) Well-known descriptor

GET /.well-known/myum-resolver.json

MUST:

• return 200
• include Cache-Control: no-store
• describe how UMIDs are encoded in the path (including the b64u: escape hatch if supported)

Resolve contract

GET /{UMID_PATH}

MUST support:

• GET and HEAD (read-only)
• OPTIONS (for CORS preflight)

MUST return one of:

• 200 with a manifest payload (JSON or JSON-LD), or
• 307 redirect to a canonical URL, or
• 404 unknown UMID, or
• 410 revoked UMID (if revocation policy is supported)

UMID parsing

If your UMIDs might include / (e.g., DID URLs or HTTPS URLs), you MUST provide a forward-compatible escape hatch.

Recommended rule:

• If the first path segment starts with b64u:, decode the remainder as base64url UTF‑8 UMID bytes.
• Otherwise treat the segment as a URL-decoded UMID.

Required headers (for 200 and 307)

For successful resolutions (200 and 307), the resolver MUST include:

• Access-Control-Allow-Origin (for browser tooling)
• Cache-Control (short cache recommended; see below)
• X-UM-Resolver-Contract (a string version so adopters can reason about changes)

If returning a payload (200), the resolver SHOULD include:

• ETag (so clients can revalidate via If-None-Match)

If redirecting (307), the resolver MUST include:

• Location

Caching requirements

Resolvers SHOULD default to conservative HTTP caching (short TTL).

Important:

• Consumers MUST enforce the manifest TTL (expiresAt) for “use”, regardless of HTTP caching.

Error semantics

Errors MUST be deterministic and machine-parseable.

Recommended shape:

{ "error": "not_found", "umid": "..." }

What is out of scope here

This conformance page does not require:

• write APIs (PUT/POST) for resolver storage
• DID key resolution (verification material may be out-of-band)
• private/authenticated resolution (access control is a separate profile)