Update DID URL Dereferencing Section with Deterministic Path Handling

[swcurran]

NOTE: This PR is still in draft, as I need to clean up the internal section links, the definitions and references, anchors and links, and getting a consistent ReSpec style. I’m putting in the PR now to get feedback on the general ideas and approach vs. on the ReSpec nitty-gritty. As this is discussed, I’ll continue with the cleanup.

A rendered version of the PR can be seen here: https://swcurran.github.io/did-resolution/.

Addresses issues: #218, #209, #201, #200, #181, #156

This pull request significantly revises and expands the content of the DID URL Dereferencing section to clarify how DID URL components — specifically the path, query parameters, and fragment — are to be interpreted during dereferencing. The update draws an explicit analogy to HTTP URL handling, helping implementers relate familiar URL resolution behavior to DID URLs, while also clearly defining where DID-specific semantics differ. Most notably, this change introduces deterministic and interoperable handling of the DID URL path, which was previously undefined in the specification. The additions establish a clear default behavior using the new FileService service type, while allowing for custom behavior via method-specific or DID extension service types. The result is a specification that is easier to implement, more extensible, and more aligned with the expectations of developers familiar with web infrastructure.

This update is (intended to be) backwards compatible:

• No existing required behavior has been changed or invalidated.
  • Techniques defined and used by Cosmos for Linked Resources and Cheqd for DID Linked Resources are untouched in their use of fragments and query parameters, respectively. The main focus here is on formalizing DID URL path handling.
• The FileService model supports DID Documents already using serviceEndpoint mappings that align with intuitive path-based routing.
• While the wording is updated, the handling of fragments and query parameters is (intended to be) unchanged.

Summary of changes:

• Removed the outdated "DID Parameters" section (now deprecated and unreferenced), and defining the Query Parameters defined in this spec to the “DID Resolution Query Parameters and Service Types” section.
• Replaced the previous "DID URL Dereferencing Algorithm" and "Examples" subsections with new normative and structured content.
• Added new structured subsections to the DID URL Dereferencing section:
  • DID URL Components: Path, Query Parameters, and Fragments — defines interpretation rules for each component, with HTTP comparisons.
  • DID URL Dereferencing Algorithm — provides normative steps for resolving a DID URL to a resource via service mappings.
  • DID Resolution Query Parameters and Service Types — defines recognized query parameters (e.g., service) and registered service types (e.g., FileService).
    • This brings together into “mini-specifications” all of the query parameter and service types defined by the DID Resolution spec. The previous “DID Parameters” content is moved to this section.
  • Examples — includes multiple concrete cases showing default and custom behaviors, including a fictitious FictitiousVerifiedFileService.

---

Preview | Diff