Add usage guidance related to the id property.

[msporny]

This PR addresses issue #946 by describing what the id property is used for, some example values for it, and whether or not it should be optional.

---

Preview | Diff

[melvincarvalho]

While the current text in the pull request suggests using HTTP URLs as identifiers (e.g., https://id.example/123), I would like to argue that using hash URIs with a fragment identifier is a more appropriate approach for identifying a person, place, or thing.

The W3C has addressed this topic in a TAG resolution called HR14 (Hash In URI). The resolution suggests that HTTP URIs without fragment identifiers should be used for documents, while hash URIs with fragment identifiers should be used for identifying resources other than documents, such as people, places, or things. You can find more information about this resolution in the following W3C document: https://www.w3.org/2001/tag/doc/hash-in-uri

The main rationale behind using hash URIs with fragment identifiers is that it allows for better separation between the document that describes the resource and the resource itself. This approach helps in avoiding confusion and allows for more precise statements about the resource.

Considering this, I suggest updating the example in the pull request to include a hash URI with a fragment identifier for identifying a person, place, or thing, such as https://example.com/people#alice. This way, the identifier clearly points to a non-document resource, in line with the W3C HR14 resolution.

Here's a revised version of the text:

Globally unique identifiers are useful so that others can express statements about the same thing. This specification defines the optional id property for such identifiers. Using the id property allows for the expression of statements about specific things in the verifiable credential and is set by an issuer when creating objects in a verifiable credential or a holder when creating objects in a verifiable presentation. Examples of ids include UUIDs (urn:uuid:0c07c1ce-57cb-41af-bef2-1b932b986873), HTTP URLs with fragment identifiers (https://example.com/people#alice), and DIDs (did:example:1234abcd).

[TallTed]

@melvincarvalho — I am somewhat concerned that the referenced W3C document has internal links to "This version" and "Latest Version", both in www.w3.org/TR/, but both 404. I also see that the Status of this Document is that it was "published as a Public Working Draft" in 2009 and hasn't been updated since. This significantly lowers my inclination to follow its guidance.

[melvincarvalho]

Thank you, @TallTed, for your feedback. I understand your reservations given the accessibility issues with the referenced W3C document and its dated status. The 404 links have now been fixed. I believe the essence of the TAG resolution encapsulates remains relevant, particularly in the context of our work here.

The resolution outlines a distinction between identifiers for documents versus non-document resources, a principle that I believe could contribute to the clarity and accuracy of our identifiers. While the document itself may no longer be maintained, the principles it outlines remain sound and adopted in various contemporary practices.

That said, I would encourage aligning with the TAG finding, particularly the use of hash URIs with fragment identifiers for non-document resources, despite the age of the document. After all, the longevity of these principles attests to their utility and relevance.

[TallTed]

@melvincarvalho — Please note that while the linked document now has different (working) "This version" and "Latest Version" targets, neither is accurate. Note that the Abstract says, "This draft finding is being prepared in response to TAG issue #60." (That would certainly have been better noted in the SotD.)

Going to that TAG issue, I find that while it links to the above document, it also says that (emphasis mine), "Current work is: Repurposing the Hash Sign for the New Web; W3C Working Draft: Putative TAG Finding 28 February 2011" which is two years more recent, but still outdated.

The first exterior link found in both as an example, in Addressing Into Multimedia Streams -- CNN, is http://www.cnn.com/video/#/video/tech/2008/02/19/vo.aus.sea.spider.ap which was probably accurate in 2011, but it is not today, as that link gets redirected to the fragmentless https://www.cnn.com/videos/tech/2008/02/19/vo.aus.sea.spider.ap (which is also now a 404).

I submit that the DRAFT TAG finding should be more carefully considered and potentially updated, given the changes in the wild.

[melvincarvalho]

@TallTed , your comments seem to divert from the core issue at hand. It's crucial to focus on the present topic and not get lost in the minutiae of details from documents. I respectfully suggest that you update your understanding with the reading materials before making assertions. This will ensure we're all on the same page, and that our discussions are productive and relevant. Let's work together to address the important issues at hand rather than getting sidetracked.

[TallTed]

Suggested change

	MAY be omitted. Not all use cases require the usage of the <code>id</code>
	MAY be omitted. Some use cases do not require use of the <code>id</code>

[TallTed]

Minor tweaks requested above. I'm not against @melvincarvalho's suggested paragraph revision, but my tweaks to the existing paragraph should also be applied to his paragraph, if it's merged into the text.

[decentralgabe]

generally agree, though I don't see much of an issue with local uniqueness under an issuer as a namespace. better than it was, so approving.

[OR13]

This is an improvement over the existing text, but I don't see why keeping id optional while requiring JSON-LD is an improvement over JSON Web Tokens.

Because JSON-LD is automatically assigning non globally unique id values (blank node identifiers) when a globally unique one is omitted.... which is worse, than requiring a unique id value.

[brentzundel]

Suggested change

	MAY be omitted. Not all use cases require the usage of the <code>id</code>
	MAY be omitted. Some use cases require omitting the <code>id</code>

[msporny]

@decentralgabe wrote:

generally agree, though I don't see much of an issue with local uniqueness under an issuer as a namespace.

If the issuer namespace is global, then local uniqueness is global uniqueness.

If the issuer namespace can conflict with another issuer's namespace, such as, the namespace is literally the empty string... then, the issue is id conflicts if random identifiers in a sufficiently large namespace aren't utilized.

[msporny]

This is an improvement over the existing text, but I don't see why keeping id optional while requiring JSON-LD is an improvement over JSON Web Tokens.

It's an improvement because when id is optional, and not specified, then the internal identifier utilized is scoped to the document (it has document-scoped semantics). JWT, and JSON, leaves the semantics for identifiers undefined while at the same time some libraries suggest equivalence if the contents of an object are byte-wise the same as in another document.

IOW, the identifier story for JSON-LD (and RDF) for unlabeled nodes is a well understood and well defined thing... it is completely undefined for JSON and JWT.

Because JSON-LD is automatically assigning non globally unique id values (blank node identifiers) when a globally unique one is omitted.... which is worse, than requiring a unique id value.

You've stated that something is worse without supporting why it is worse with a well-reasoned argument. Why is it worse?

[msporny]

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

[melvincarvalho]

While I am not raising any objections at this moment, I am concerned that the topic about the distinction between documents and things might have been overlooked amidst other discussions. It's worth noting that the TAG has promptly addressed the broken link issue.

Refer: https://lists.w3.org/Archives/Public/www-tag/2023May/0001.html

Although I could make further corrections based on @TallTed's suggestions, the core content of the document remains unchanged. I interact with developers daily who often confuse between things and documents on the web. Examples in REC track work may inadvertently solidify this misunderstanding, leading developers to believe that pointers and contents are interchangeable. This could potentially act as a significant barrier to semantic interoperability, and might be worth reconsidering in future if the goal is to produce REC quality examples.

[TallTed]

@melvincarvalho — This confusion/belief "that pointers and contents are interchangeable" is long-running and is frequently referred to as HTTPRange14. Programmers should understand the difference, as they work with memory pointers and the values found there, but somehow the introduction of HTTP tends to twist many minds.

[melvincarvalho]

@TallTed well said! Ends.