Universal DID Native Addressing (UDNA) defines a lightweight, extensible addressing scheme that makes Decentralized Identifiers (DIDs) native to resource location and service discovery on the Web. UDNA extends DID from identity resolution to resource addressing, providing a uniform udna:// URI scheme that encodes a DID and a resource path, enabling secure, cryptographically verifiable interactions across decentralized systems. This specification builds on W3C Recommendations ([[DID-CORE]], [[VC-DATA-MODEL]]) and the DIDComm v2 messaging protocol ([[DIDCOMM]]). It is an incubation deliverable of the UDNA W3C Community Group and does not represent consensus of the broader W3C Membership.

UDNA completes the addressing stack for decentralized identity: where DNS maps names to IP addresses, and DIDs map identifiers to DID Documents, UDNA maps identity to resources.

This document is a Community Group Draft produced by the W3C Community Group for DID Native Addressing. It is not a W3C Standard nor on the W3C Standards Track. Publication by the W3C does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This specification is being developed to explore the intersection of decentralized identifiers, native addressing, and universal service discovery. The goal is to mature the proposal toward a future W3C Working Group deliverable. The CG welcomes issues and pull requests on GitHub. Before contributing, please review the W3C Community Contributor License Agreement.

The CG has received early reviews from implementers of Solid, DIDComm, and Hyperledger Aries, and expects to conduct multiple interoperability events during 2026.

Introduction

The Web's addressing model is built on URLs that bind authority to domain names, which in turn rely on centralized DNS and certificate authorities. While this has enabled massive growth, it introduces identity silos, privacy leaks, and intermediary dependency. Decentralized Identifiers (DIDs) offer self-sovereign, cryptographically verifiable identities, but they lack a native addressing scheme to directly locate resources, APIs, or services tied to a DID.

UDNA fills this gap. UDNA extends DID from identity resolution to resource addressing. By introducing the udna:// URI scheme and a deterministic resolution mechanism, UDNA allows any entity with a DID to publish service endpoints, resources, and sub-paths that can be resolved in a secure, privacy-preserving way. Conceptually:

• DNS → maps names to IP addresses
• DIDs → map identifiers to DID Documents
• UDNA → maps identity to resources

UDNA leverages [[DID-CORE]] for identity, [[DIDCOMM]] for secure messaging, and [[VC-DATA-MODEL]] for authorization policies.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [[RFC2119]] [[RFC8174]] when, and only when, they appear in all capitals, as shown here.

Terminology

This section defines the terms used throughout this specification.

UDNA Address

A URI conforming to the udna scheme, composed of a DID component, an optional service segment, and a resource path. Formally specified in .

DID Resolution

The process defined in [[DID-CORE]] by which a DID string is dereferenced to obtain a DID Document containing public keys and service endpoints.

Native Addressing

An addressing model where the identifier of an entity (a DID) is an integral part of the resource locator, enabling direct, verifiable interactions without external naming authorities.

Service Endpoint

A network address defined within a DID Document under the service array property, expressed as a URI string, a set of URI strings, or a DIDComm endpoint object.

UDNARoot Service

The default service entry used by UDNA resolution when no explicit service segment is present. Identified by type: "UDNARoot" or the fragment identifier #udna-root in the DID Document. A DID Document MUST contain at most one UDNARoot service entry.

ResolutionResult

A structured object returned on successful resolution, containing the constructed target URL, the resolved DID Document, metadata, and cryptographic verification materials. Defined in .

ResolutionError

A structured error object returned when resolution fails. Defined in .

Processing Model

The normative sequence of steps a resolver MUST execute to transform a UDNA address into a ResolutionResult or ResolutionError. Defined in .

UDNA URI Scheme

udna-URI   = "udna://" did-string [ "/" service-id ] path [ "?" query ] [ "#" fragment ]
did-string = scheme ":" method-specific-id
             ; a valid DID per [[DID-CORE]]
service-id = *( unreserved / pct-encoded )
path       = *( "/" segment )
query      = *( pchar / "/" / "?" )
fragment   = *( pchar / "/" / "?" )
        

udna://did:example:123456/service/api/resource?version=1#section
        

Processing Model

This section defines the normative processing steps that a [=UDNA Resolver=] MUST execute. It is separated from the data model to enable independent evolution of processing logic and output structures.

Resolution Result Data Model

Conformant [=UDNA Resolvers=] MUST return resolution results conforming to the following structure. The data model extends DID Resolution metadata ([[DID-CORE]]) with UDNA-specific fields.

{
  "@context": "https://w3c-cg.github.io/udna/contexts/udna-v1.jsonld",
  "type": "UDNAResolutionResult",
  "targetUrl": "https://api.example.com/udna/app/profile#me",
  "didDocument": {
    "@context": "https://www.w3.org/ns/did/v1",
    "id": "did:web:example.com",
    "service": [ ... ]
  },
  "didDocumentMetadata": {
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-06-01T00:00:00Z",
    "deactivated": false
  },
  "service": {
    "id": "#udna-root",
    "type": "UDNARoot",
    "serviceEndpoint": "https://api.example.com/udna"
  },
  "verificationMethods": [
    {
      "id": "did:web:example.com#keys-1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:web:example.com",
      "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ]
}
        

Error Handling

When resolution fails, a conformant [=UDNA Resolver=] MUST return a [=ResolutionError=] object using the following structure:

{
  "error": "serviceNotFound",
  "errorDescription": "No matching service entry found for 'api'",
  "did": "did:web:example.com",
  "serviceSegment": "api"
}
        

Content Negotiation

When UDNA resolution produces an HTTP-based targetUrl, clients MAY use standard HTTP content negotiation ([[RFC9110]], Section 12) when interacting with the resolved endpoint. This section defines content types relevant to UDNA interactions.

Services exposed via UDNA SHOULD support the following media types:

• application/json — Generic JSON responses for RESTful service interactions.
• application/ld+json — JSON-LD formatted responses for linked data interactions, including credential verification.
• application/didcomm-envelope+json — DIDComm v2 encrypted envelopes when the resolved endpoint is a DIDComm service ([[DIDCOMM]]).

Clients MAY include an Accept header to indicate preferred content types. Services SHOULD respond with an appropriate Content-Type header and SHOULD return HTTP status 406 Not Acceptable if unable to satisfy the client's content type preferences.

Resolver API Interface

To promote interoperability across implementations, a conformant [=UDNA Resolver=] MUST expose at minimum the following function signature:

function resolve(udnaURI: string): Promise<ResolutionResult | ResolutionError>;
    

Implementations MAY additionally provide:

• Synchronous variant — resolveSync(udnaURI): ResolutionResult | ResolutionError for environments where asynchronous resolution is not required.
• Batch resolution — resolveBatch(udnaURIs: string[]): Promise<(ResolutionResult | ResolutionError)[]> for resolving multiple UDNA addresses in a single operation.
• Watch/unwatch — watch(udnaURI, callback): Subscription for observing resolution changes over time.

The canonical reference implementation in JavaScript is available at github.com/w3c-cg/udna.

Gateway Model

UDNA resolution can be exposed through an HTTP gateway, enabling clients that do not implement native UDNA resolution to dereference UDNA addresses via standard HTTP requests. This pattern is similar to IPFS gateways and Solid pod access patterns.

A conformant [=UDNA Gateway=] MUST satisfy the following normative constraint:

GW-1: Gateways MUST NOT modify the semantics of the resolved targetUrl. The path, query, and fragment components from the original UDNA address MUST be preserved in the final constructed URL without alteration or filtering.

The canonical gateway resolution pattern is:

GET https://udna-gateway.example/resolve?uri=udna://did:web:example.com/app/profile

→ 302 Redirect to: https://api.example.com/udna/app/profile
    

Gateways serve as a progressive adoption path, allowing existing Web infrastructure to participate in UDNA resolution without native protocol support. The full gateway behavior is defined in a separate extension specification ("Gateway Forwarding").

Security and Privacy Considerations

UDNA inherits the security properties of the underlying DID methods and DIDComm. The following considerations apply specifically to the UDNA addressing layer.

Extensibility and Versioning

UDNA follows a minimal core + extension model. Core behavior is defined by this specification; optional capabilities are registered via the udna-ext query parameter (?udna-ext=https://…). The following extensions are known at the time of publication:

Batch Operations

Enables resolving multiple [=UDNA Address=]es in a single roundtrip, reducing resolution overhead in high-frequency use cases.

Gateway Forwarding

Defines behavior for relays and gateways that bridge UDNA resolution to legacy HTTP URLs, enabling progressive adoption in existing infrastructure.

Resource Integrity

Allows embedding cryptographic integrity hashes (e.g., SHA-256) for content-addressed resources referenced via a [=UDNA Address=].

Versioning of the core scheme is indicated via the udna-version query parameter. The default value for this specification is 1.0. Future versions MUST be backward-compatible at the resolution layer unless a breaking version increment is declared.

Relationship with Other Web Standards

UDNA is not intended to replace the following protocols but to unify them under a common addressing layer that respects decentralized identity. Implementations MAY embed UDNA support as a complementary naming and discovery mechanism.

Incubation Roadmap and Next Steps

The UDNA Community Group is actively incubating this specification. The following are current priorities for the 2026 incubation cycle:

• Interoperability test suite — automated validation of the test vectors against multi-language resolver implementations targeting JavaScript (Node.js), Rust, and Python reference libraries.
• DID method profiling — concrete guidelines for did:web, did:key, and did:tdw to correctly expose UDNA service endpoints in their DID Documents.
• Security review — formal analysis of the resolution algorithm, including potential endpoint confusion and injection attack vectors.
• Integration pilots — live integration tests with Solid pod servers and Matrix homeservers to validate real-world addressing patterns and performance.
• Browser integration exploration — initial design for how browsers might handle udna:// links, including gateway fallback and extension-based resolution. See .
• JSON-LD context publication — finalize and publish the UDNA JSON-LD context at its canonical URL.