Relative DID URLs

[FabioPinheiro]

trafficstars

I'm back you this question again. (Can't find previous discussions)

In 3.2.2 Relative DID URLs its mention how relative DID URLs look like that how it should be used. Examples are given

But then they are incompatible with the rest of the specs...

Each library implement these on different ways there are incompatibilities. It's been a pain trying to be interruptible. I cannot even open issues on the libraries because the issue comes from the specification.

In the 5.2 Verification Methods

The value of the id property for a verification method MUST be a string that conforms to the rules in Section 3.2 DID URL Syntax.

In the 5.2.2 Referring to Verification Methods

if the value is a URL string, the verification method has been included by reference and its properties will need to be retrieved from elsewhere in the DID document or from another DID document. This is done by dereferencing the URL and searching the resulting resource for a verification method map with an id property whose value matches the URL.

In 5.2.2 Referring to Verification Methods

This is done by dereferencing the URL and searching the resulting resource for a verification method map with an id property whose value matches the URL.

[msporny]

@FabioPinheiro what change would you like to see in the specification? Can you propose some concrete text?

Based on my read of https://www.w3.org/TR/did-1.0/#relative-did-urls ... and 5.2, you coerce any relative value using the rules in section 3.2.2. IOW, I don't see what the issue is, can you specify exactly what problem it is that you are experiencing?

[FabioPinheiro]

believe there is another ticket and two PRs +- related with this. I need to build the current version of the document and read again.

But basically I believe that in section 5.2 instead of The value of the id property for a verification method MUST be a string that conforms to the rules in Section 3.2 DID URL Syntax." it should aloud for relative did urls. Because the relative did urls is NOT a specific part of the Syntax since it does not follow the rules defined of the DID URLs.

[FabioPinheiro]

BTW one of the PRs I was taking is here https://github.com/w3c/did-resolution/issues/130

[peacekeeper]

@FabioPinheiro do you agree that in DID Resolution this has been fixed by https://github.com/w3c/did-resolution/pull/125 ?

Then if I understand correctly, you are saying that here in DID Core we should also clarify that the value of id properties can be relative DID URLs?

[FabioPinheiro]

yes

In terms of examples, there is already one added by https://github.com/w3c/did/issues/860 (PR https://github.com/w3c/did/pull/874) before I open a issue.

My problem is that the specification in 5.2 "The value of the id property for a verification method MUST be a string that conforms to the rules in Section 3.2 DID URL Syntax." is in contradiction. Because the DID URL Syntax doesn't account for Relative DID URL for my understanding.

IMO (and I'm having some difficulties of having the current state of the document at the moment) we should specify/rename DID URL to Full DID URL and generalize the name DID URL to be either full or relative DID URLs. And then revisit the whole document to figure out if it should be using Full DID URL or a DID URL.

[wip-abramson]

@FabioPinheiro I think I also thought along these lines, hence the PR #874.

But, I do think the spec text is accurate. Section 3.2 DID URL Syntax, includes Section 3.2.1 Relative DID URLs

IMO (and I'm having some difficulties of having the current state of the document at the moment) we should specify/rename DID URL to Full DID URL and generalize the name DID URL to be either full or relative DID URLs. And then revisit the whole document to figure out if it should be using Full DID URL or a DID URL.

As I understand it, anywhere in a DID Document there is a DID URL, their can either be a full DID URL or a relative DID URL. And relative DID URLs can be trivially transformed into full DID URLs following the approach defined in https://www.w3.org/TR/did/upcoming/#relative-did-urls

Does that help, or do you still think your proposed change is necessary?

[msporny]

We can raise a PR to refer to the DID Resolution spec for the algorithm for dereferencing.

[w3cbot]

This was discussed during the #did meeting on 15 May 2025.

View the transcript

w3c/did#880

wip: issue openned by Fabio Pinheiro...

wip: I am not sure if the spec needs changes...

markus_sabadello: I think we did address some of this in the did-resoultion spec, with the de-ferencing and others....

markus_sabadello: the did-resolution spec should reference the section where relative did urls are mentioned in did-core....

manu: yes agree.... one thing we could in did-core is to point to the part of the did-resolution spec that points to relative did urls

wip: ok....

---

[peacekeeper]

I think this was mostly addressed by https://github.com/w3c/did-resolution/pull/125 and https://github.com/w3c/did/pull/874.

I also think we do use the terms "DID URL", "relative DID URL" and "absolute DID URL" (not "full") appropriately in most places, but I think I also agree with the comment https://github.com/w3c/did/issues/880#issuecomment-2792590177 about verificationMethod.id.

@FabioPinheiro could we address this by changing

The value of the id property for a verification method MUST be a string that conforms to the rules in Section 3.2 DID URL Syntax.

to

The value of the id property for a verification method MUST be a string that conforms to the rules in Section 3.2 DID URL Syntax or 3.2.2 Relative DID URLs.

?

[w3cbot]

This was discussed during the #did meeting on 22 May 2025.

View the transcript

880 - Relative DID URLs

<ottomorac> w3c/did#880

ottomorac: Issue raised by Fabio Pinheiro, does this change based on the special topic call?

manu: think Markus' suggestion is right and should address the issue

markus_sabadello: doesn't have anything to do with special topic call. Its just when we use DID URL vs relative DID URL. Fabio who created the issue is right. We should clarify this verificationMethod logic a bit more - it can also be a relative DID URL

<manu> s/ markus_sabadello doesn't/markus_sabadello: doesn't/

---

[FabioPinheiro]

Sorry I'm been super busy with other projects. @peacekeeper I was going to say yes that would be great. But no. Although its much better

This will allow how people is already using:

{
  "verificationMethod":[
    {
      "id": "did:example:123456789abcdefghi#keys-1",
      "type": "Ed25519VerificationKey2020", 
      "controller": "...",
      ...
    }
  ]
  "keyAgreement": ["did:example:123456789abcdefghi#keys-1"],
  "authentication": ["did:example:123456789abcdefghi#keys-1"],
}

That sentence is about the verificationMethod property. I believe that this property should be the only verification method properties that should NOT allow the Relative DID URL.

I don't want to allow this:

{
  "verificationMethod":[
    "did:example:123456789abcdefghi#keys-1",
    "did:example:123456789abcdefghi#keys-1",
    "did:example:123456789abcdefghi#keys-1",
    "did:example:123456789abcdefghi#keys-1",
    {
      "id": "did:example:123456789abcdefghi#keys-1",
      "type": "Ed25519VerificationKey2020", 
      "controller": "...",
      ...
    }
  ]
  "keyAgreement": ["did:example:123456789abcdefghi#keys-1"],
  "authentication": ["did:example:123456789abcdefghi#keys-1"],
}

I mean no one will create a loop in the verificationMethod property. But it would be nice for me to write nicer type safe code and still follow the specs.

@peacekeeper If you could edit the table "DID Document properties" instead would be better https://www.w3.org/TR/did-1.0/#did-document-properties

instead of

A set of either Verification Method maps that conform to the rules in Verification Method properties) or strings that conform to the rules in 3.2 DID URL Syntax.

edit to

A set of either Verification Method maps that conform to the rules in Verification Method properties) or strings that conform to the rules in 3.2 DID URL Syntax or 3.2.2 Relative DID URLs.

[FabioPinheiro]

Note that 3.2 DID URL Syntax and 3.2.2 Relative DID URLs is not for the same use case.

I can have a 3.2 DID URL that points to another DID's key. But the Relative DID URL only can points the a key in the same did document.

[msporny]

@FabioPinheiro wrote:

If you could edit the table "DID Document properties" instead would be better https://www.w3.org/TR/did-1.0/#did-document-properties

To be clear, that text does not exist in the DID v1.1 specification anymore and we are not allowed to change the DID v1.0 specification (unless there is a catastrophic error, which this isn't, that document is frozen for the rest of time per W3C Process).

What we can do is change the DID v1.1 specification under our maintenance mode... however, the current text says this for the properties that @FabioPinheiro is pointing out (from https://www.w3.org/TR/did-1.1/#core-properties):

A set of data where each element is either a string which conforms to rules defined in Section 3.1 DID Syntax, or a map that conforms to the rules for verification methods defined in Section 5.2 Verification Methods.

If you go to Section 5.2 Verification Methods, it says:

A set of either Verification Method maps that conform to the rules in Verification Method properties) or strings that conform to the rules in 3.2 DID URL Syntax.

... and then if you go and read Section 3.2 DID URL Syntax, it has a subsection that talks about relative URLs being allowed:

https://www.w3.org/TR/did-1.1/#relative-did-urls

So, I think we're fine here from a normative perspective (nothing needs to change). That said, I can see how having to jump all over the spec can be confusing and that we want to be explicit about this. I'll try to raise a PR that makes this more explicit in the current specification.

[msporny]

PR #893 has been raised to address this issue. This issue will be closed once PR #893 has been merged.

[msporny]

PR #893 has been merged; closing.