Clarify restrictions on identifiers used in DID documents.

[msporny]

This PR is an attempt to address issue #337 by clarifying specific existing (and presumed) restrictions on DID Document identifiers (such as parameters and fragment identifiers).

---

Preview | Diff

[iherman]

I wonder why the preview did not automatically run. @msporny any idea?

[msporny]

I wonder why the preview did not automatically run. @msporny any idea?

Yes, the PR Preview App isn't installed for this repo. Perhaps it was desynchronized when we renamed the repo? For some reason, I don't have admin privileges on this repo, so I can't install it.

You might be able to install it by going here: https://github.com/apps/pr-preview

... and installing it on this repo specifically. I think you need to have admin privileges on the repo.

PS: Looks like Echidna auto-publishing had been disabled for our FPWD and then never turned back on. I have re-enabled it.

[iherman]

@msporny it is configured for the repository the same way (in fact, pre-preview is installed automatically for all w3c repositories). The .pr-preview file in the repo looks exactly the same as it does for, say, the vc-data-model repo.

I ping hereby @deniak , he may know what is happening...

[iherman]

Actually... it works again on another repo! I have no idea why it has not worked for this one. It may have been a temporary glitch.

@deniak sorry for the noise!

[msporny]

Actually... it works again on another PR! I have no idea why it has not worked for this one. It may have been a temporary glitch.

Hmm, the only thing I changed was re-enabling Echinda publishing (which is now failing for different reasons):

• Add new spec: Controlled Identifiers v1.0 browser-specs#1747
• Add new spec: Decentralized Identifiers v1.1 browser-specs#1748

The other thing that's confusing is that the "install" process says it's not enabled for this repo, but perhaps that's because I don't have management permissions on this repo?

[iherman]

Actually... it works again on another PR! I have no idea why it has not worked for this one. It may have been a temporary glitch.

Hmm, the only thing I changed was re-enabling Echinda publishing (which is now failing for different reasons):

It is an intellectual illness to try to understand everything... :-)

[deniak]

The issue is not related to Echidna but to respec. There is a problem with the cross references but I don't know respec enough to find what is the problem.

  [INFO] Build respec document "index.html" (gh)…
    $ respec -s "http://localhost:3000/index.html?gitRevision=b11f1a37660f0f2dbfea60bdd1a55a7cf141120c" -o "index.html.built.html" --verbose -t 20 -e
      [INFO] [Timeout: 20000ms] Processing resource: http://localhost:3000/index.html?gitRevision=b11f1a37660f0f2dbfea60bdd1a55a7cf141120c ...
      [INFO] [Timeout: 20000ms] Launching browser
      [INFO] [Timeout: 19743ms] Navigating to http://localhost:3000/index.html?gitRevision=b11f1a37660f0f2dbfea60bdd1a55a7cf141120c
      [INFO] [Timeout: 17397ms] Navigation complete.
      [INFO] [Timeout: 17344ms] Using ReSpec v35.3.0
      [INFO] [Timeout: 17344ms] Processing ReSpec document...
  Error: ROR] Couldn't find "authenticate" in this document or other cited documents: [cid], [infra], [rfc3986], [vc-data-integrity], and [web-platform].
         Count: 2
        Plugin: core/xref
          Hint: [See search matches for "authenticate"](https://respec.org/xref/?term=authenticate&types=_CONCEPT_) or [Learn about this error](https://respec.org/docs/#error-term-not-found).
  Error: ROR] Couldn't find "controller" in this document or other cited documents: [cid], [did-resolution], [infra], [rfc3986], [vc-data-integrity], and [web-platform].
         Count: 1
        Plugin: core/xref
          Hint: [See search matches for "controller"](https://respec.org/xref/?term=controller&types=_CONCEPT_) or [Learn about this error](https://respec.org/docs/#error-term-not-found).
  Error: ROR] Couldn't find "authenticate" in this document or other cited documents: [cid], [did-resolution], [did-spec-registries], [infra], [rfc3986], [rfc7231], [vc-data-integrity], [vc-data-model], and [web-platform].
         Count: 3
        Plugin: core/xref
          Hint: [See search matches for "authenticate"](https://respec.org/xref/?term=authenticate&types=_CONCEPT_) or [Learn about this error](https://respec.org/docs/#error-term-not-found).
  Error: ROR] Couldn't find "controlled identifier document" in this document or other cited documents: [cid], [infra], [rfc3986], [vc-data-integrity], and [web-platform].
         Count: 1
        Plugin: core/xref
          Hint: [See search matches for "controlled identifier document"](https://respec.org/xref/?term=controlled+identifier+document&types=_CONCEPT_) or [Learn about this error](https://respec.org/docs/#error-term-not-found).
  Error: ROR] Couldn't find "verification relationships" in this document or other cited documents: [cid], [infra], [rfc3986], [vc-data-integrity], and [web-platform].
         Count: 1
        Plugin: core/xref
          Hint: [See search matches for "verification relationships"](https://respec.org/xref/?term=verification+relationships&types=_CONCEPT_) or [Learn about this error](https://respec.org/docs/#error-term-not-found).
  Error: ROR] Couldn't find "verification relationship" in this document or other cited documents: [cid], [infra], [rfc3986], [vc-data-integrity], and [web-platform].
         Count: 1
        Plugin: core/xref
          Hint: [See search matches for "verification relationship"](https://respec.org/xref/?term=verification+relationship&types=_CONCEPT_) or [Learn about this error](https://respec.org/docs/#error-term-not-found).
  Error: ROR] Couldn't find "controller" in this document or other cited documents: [cid], [infra], [rfc3986], [vc-data-integrity], and [web-platform].
         Count: 11
        Plugin: core/xref
          Hint: [See search matches for "controller"](https://respec.org/xref/?term=controller&types=_CONCEPT_) or [Learn about this error](https://respec.org/docs/#error-term-not-found).
  Error: ROR] Couldn't find "controllers" in this document or other cited documents: [cid], [infra], [rfc3986], [vc-data-integrity], and [web-platform].
         Count: 1
        Plugin: core/xref
          Hint: [See search matches for "controllers"](https://respec.org/xref/?term=controllers&types=_CONCEPT_) or [Learn about this error](https://respec.org/docs/#error-term-not-found).
      [INFO] [Timeout: 16157ms] Processed document.
      [INFO] [Timeout: 15148ms] Done.
      [FATAL] Error: Errors found during processing.
          at run (file:///home/runner/work/_actions/w3c/spec-prod/v2/node_modules/.pnpm/respec@35.3.0_typescript@5.4.5/node_modules/respec/tools/respec2html.js:285:11)
          at async file:///home/runner/work/_actions/w3c/spec-prod/v2/node_modules/.pnpm/respec@35.3.0_typescript@5.4.5/node_modules/respec/tools/respec2html.js:232:5
    Command `respec -s "http://localhost:3000/index.html?gitRevision=b11f1a37660f0f2dbfea60bdd1a55a7cf141120c" -o "index.html.built.html" --verbose -t 20 -e` failed with exit code: 1.
  Error: Process completed with exit code 1.

[msporny]

@deniak wrote:

There is a problem with the cross references but I don't know respec enough to find what is the problem.

Yes, the problem is that the CID spec isn't being indexed in webref, probably because it's not listed in browser-specs. I've raised these two PRs in an attempt to fix the issue:

• Add new spec: Controlled Identifiers v1.0 browser-specs#1747
• Add new spec: Decentralized Identifiers v1.1 browser-specs#1748

@iherman wrote:

It is an intellectual illness to try to understand everything... :-)

I hope to one day be cured of this illness... at least, as it relates to tracking down ReSpec build failures... :P

[msporny]

Editorial, multiple reviews, changes requested and made, no objections, merging.

[pchampin]

This was discussed during the did meeting on 03 April 2025.

View the transcript

w3c/did#886

<ottomorac> Clarify restrictions on identifiers used in DID documents. #886

ottomorac: Same sort of situation -- Ted had some changes that have been merged.

manu: This is asking when parameters should be dropped.
… Is a DID document with an ID in it, can you put query parameters or fragment identifiers in the ID?
… This states clearly not.
… We also provide non-normative guidance, saying if you are going to have a long-lived canonical identifier, you should probably not use a query parameter, unless you really know what's going on there.
… The query parameter is probably not something you want to store, just the base DID.
… Fragment identifiers, you probably want to use, because it may refer to a validation method.
… If you do use a fragment identifier, make sure it's unique over the lifetime of the document.
… If you use key1, key2, key1, key2... over years, it can change the way the document is handled.
… This text goes over that at a high level and addresses issue 337.

<denkeni> +1 to make it clear in did spec

ottomorac: This one makes sense too.

TallTed: I'll take a quick look at it, but expect it'll be fine.

manu: There's a triple-bracket syntax for references.
… I think you made the right change. ReSpec substitutes the specification for the name in the square brackets.
… You have to know what it expands to.

ottomorac: I think we're nearly ready on it, maybe get final approval from Ted and then wrap it up.

---