Language clarification "A DID document is a representation of information describing a DID subject."

[wip-abramson]

I came across this language in the terminology - https://w3c.github.io/did-resolution/#dfn-representations

A DID document is a representation of information describing a DID subject.

It felt odd and potentially confusing to me.

Does a DID document describe a DID subject? It provides a means for authentic interactions with the DID subject, but it doesn't or shouldn't provide descriptive statements about the subject, e.g. eyes: blue.

I think we had this discussion in the Controller Identifier Document.

Whose abstract states

A controlled identifier document contains cryptographic material and lists service endpoints for the purposes of verifying cryptographic proofs from, and interacting with, the controller of an identifier. - https://w3c.github.io/cid/#abstract

I also note that the CID spec terminology section defines subject as

An entity, such as a person, group, organization, physical thing, digital thing, or logical thing that is referred to by the value of an id property in a controlled identifier document. Subjects identified in a controlled identifier document are also used as a subjects in other contexts, such as during authentication or in verifiable credentials. - https://w3c.github.io/cid/#dfn-subjects

Wheras, the DID spec defines a DID subject as

The entity identified by a DID and described by a DID document. Anything can be a DID subject: person, group, organization, physical thing, digital thing, logical thing, etc. - https://w3c.github.io/did/#dfn-did-subjects

Thoughts? Should we clean up this language?

[wip-abramson]

I realise this may have been better raised against DID core, or at least it applies to both specs.

[jandrieu]

Does a DID document describe a DID subject?

This is a longstanding debate. The open-world folks like treating the DID Document as JSON-LD in which the structure of the DID document makes it "about" the subject referred to by the ID.

However, I find that to be a problematic over-use of the open-world data model, which, because of HttpRange14, is unable to directly make statements about identifiers: all statements are taken to be about the referent of the identifier rather than the identifier itself.

It's my opinion that the DID document is NOT about the subject, but rather about the identifier. It describes verification methods associated with various verification relationships for that identifier.

It is layer violation, IMO, to put information about the subject in the DID document. Verifiable Credentials were created to carry attestations about subjects, with appropriate mechanisms for revocation, authority, and, privacy. DID Documents don't.

Yes, if you squint hard enough, you can convince yourself that statements about the identifier for a subject can be taken as a statement about the subject, but it is literally one step removed. You don't need to know anything about the subject to create and use a DID Document.

In fact, you NEED to use the DID document to establish cryptographic assurances that given VCs apply to a candidate subject. That is how you associate attributes with a subject. Simply sticking properties in a DID document presumes that the VDR and/or controller is an appropriate authority for that arbitrary statement and there is no way to evaluate that generally for any given DID.

[jandrieu]

FWIW, I think the CID spec has better language (which has some buy-in from the community):

A controlled identifier document contains cryptographic material and lists service endpoints for the purposes of verifying cryptographic proofs from, and interacting with, the controller of an identifier.

https://w3c.github.io/cid/

[dlongley]

I'm happy for us to use text from the CID spec to help resolve issues here.

I generally don't think it's a good idea to add statements about the DID subject other than those used to enable interactions with it or to verify related proofs.

But note that it's still my view that the statements in a DID document are statements about the DID subject, not "about the identifier", e.g., "The DID subject, identified by did:example:123, has verification method X" or "The DID subject, identified by did:example:456, has service Y".

An identifier is just a string of characters, for example: urn:abcdefg. You cannot "interact with" an identifier. A sensible statement "about an identifier" would be "it has the characters abc in it" or "it is a URL".

In summary, I think I'm more or less on the same page as @jandrieu around where we ought to recommend certain information be expressed (in a DID document vs. in a VC, for example). However, I don't agree with the specific framing on making statements about identifiers that are, in my view, really about the referent. Practically speaking, I don't know that this matters -- and we can instead just focus on helping people understand what should go where and what the rationale for that approach is (from a privacy perspective, etc.).

I think telling a person that the statements are "about an identifier" or "about its referent" will have insignificant impact as to whether they put PII like "eyes: blue" (@wip-abramson's example) into a DID document. "Don't put PII like 'eyes: blue' in a DID document" is a much better way to convey this.

[wip-abramson]

I am more aligned with @jandrieu on this.

In fact, you NEED to use the DID document to establish cryptographic assurances that given VCs apply to a candidate subject. That is how you associate attributes with a subject. Simply sticking properties in a DID document presumes that the VDR and/or controller is an appropriate authority for that arbitrary statement and there is no way to evaluate that generally for any given DID.

I think there is value in recognizing the separation between the virtual digital entity identified by a DID whose interactions can be cryptographically verified and the imperfectly perceived subject - or identity - of this identifier that emerges over time through repeat interactions.

I think DIDs allow you to instantiate these virtual digital entities that you can verifiably interact through and with, however, I do not think I am the the subject of the DIDs that I create to represent me in different contexts. Rather the subject is however this identifier is understood by those that interact with it.

Anyway, not sure if what I added is helpful. Or if I just confused myself.

I appreciate your comment @dlongley

Practically speaking, I don't know that this matters -- and we can instead just focus on helping people understand what should go where and what the rationale for that approach is (from a privacy perspective, etc.).

My preference would still be to avoid statements like this A DID document is a representation of information describing a DID subject. Adopting the CID spec definition for subject would be one way to address this. I think it is a better definition anyway.

There is already a section in privacy considerations that covers not putting PII in the DID Document - https://www.w3.org/TR/did/upcoming/#did-subject-classification.

[w3cbot]

This was discussed during the #did meeting on 19 June 2025.

View the transcript

Language clarification "A DID document is a representation of information describing a DID subject." #912

<ottomorac> w3c/did-resolution#113

Wip: Yes this sentence was not striking of what a did-document is. To me a did identifies a did-document... and then we have the verification relationships in the did-document

<Zakim> JoeAndrieu, you wanted to say this has been a long standing disagreement

JoeAndrieu: I have always disagreed with Manu and Dave on this point
… When a DID document was treated as JSONLD you can't make a statment about the identifier
… THe identifier transmutes the statement to be about the subject
… Now that we are not in JSONLD we do not have this constraint.
… This illusion that this DID document is somehow about the subject
… I think it is really important that we should make it clear that you should not be putting statements about the subject in the DID document
… I would like to clarify this in the spec

ottomorac: I saw a proposal to try pull in working from the CID spec

JoeAndrieu: Wasn't clear what language we should add

---

[peacekeeper]

This issue is about the "representation" terminology entry, which currently says this:

representation
As defined for HTTP by [RFC7231]: "information that is intended to reflect a past, current, or desired state of a given resource, in a format that can be readily communicated via the protocol, and that consists of a set of representation metadata and a potentially unbounded stream of representation data." A DID document is a representation of information describing a DID subject. See Decentralized Identifiers (DIDs) v1.0.

Does anyone have a concrete suggestion how to change this sentence?

A DID document is a representation of information describing a DID subject.

How about:

A DID document is a representation of information which allows trustable interactions associated with a DID subject.

?

[TallTed]

Perhaps include something like --

Other description data about the DID subject SHOULD NOT be included in the DID document; rather, the DID document SHOULD include links to external documents, optimally Verifiable Credentials, which MAY contain such description data.

(I don't immediately know whether this section is normative or not, so the language above might need some RFC2119 changes.)

[TallTed]

Instead of --

A DID document is a representation of information which allows trustable interactions associated with a DID subject.

-- perhaps avoid the always troublesome "trust" with --

A DID document is a representation of information which enables cryptographically verifiable interactions with a DID subject.