(Editorial) systematically adding an anchor to each property

[iherman]

At the moment, there is no way to have hyperlinks to properties that are defined in the VCDM specification, e.g., validFrom or credentialSchema. More specifically, the "formal" specification of these terms are done through a

<dl>
  <dt><var>validFrom</var></dt>
  ...

construct; I believe the <dt> must have an @id property following some clear naming scheme (e.g., dfn-validFrom). Even better, maybe using a <dfn> would be better; it may allow the VDCM spec to be incorporated into the xref toolkit of other W3C specifications.

Why? I believe it is not a good idea that, e.g., the credentialSubject is defined both in the VCDM spec and in the vocabulary specification (e.g., at https://www.w3.org/2018/credentials//#credentialSchema). What should happen, in my view, is that the vocabulary specification should refer to the VCDM specification's normative description whenever this makes sense, with only a few words in the vocabulary specification. But the these anchors are the first necessary steps to do so.

(To make it short: the vocabulary specification should be DRY...)

---

• P.S.1. Because I would have to do the updates of the vocabulary definition I am happy to do this in a separate PR on the spec, but only if, in principle, we have an agreement to do this. Hence my auto-assignment to this issue.
• P.S.2. The same editorial principle should be used on all our specs. Not only the data integrity, but all our specs that define new terms, e.g., class instances that are referred to from a VC.

cc @msporny

[msporny]

Yes, agreed on this approach.

I'm less sure of the use of <dfn> in the main spec; I've tried to only use <dfn> for "terminology associated with prose" and not "literal variable names in code and their associated normative statements". I realize that those two classes of information are very close, but they're not directly overlapping. I remember there being some sort of markup issues w/ older version of ReSpec.

That said, we should experiment and see if we cane make <dfn> work everywhere... and if that fails (for any reason), we can fall back to just asserting id values by hand in the HTML (yes, I know, not ideal, but that can be the fallback).

[iherman]

Ok. I would let you experiment with the <dfn> and, once you have decided which one to use I am happy to take over from you filling in the id-s (and linking from the vocabulary).

[Sakurann]

should take decisions in #1103 into account.

[iherman]

The issue was discussed in a meeting on 2023-06-14

• no resolutions were taken

View the transcript

2.2. (Editorial) systematically adding an anchor to each property (issue vc-data-model#1080)

See github issue vc-data-model#1080.

Kristina Yasuda: add anchor to each property.

Dave Longley: +1 after CR.

Kristina Yasuda: ok, lets mark after CR.

Ivan Herman: in a sense its bound to the discussion yesterday on 1103.
… if we want to elevate the vocabulary to normative, it will require editing.
… and then we would need to move text around.
… for me to do this, I need anchors.
… so this blocks the normative issues with the vocabulary and context.

Michael Prorock: +1 ivan - may have impacts on normative.

Kristina Yasuda: do you have an issue number?

Orie Steele: You don't need anchor tags to reserve URLs, it's common for anchors to not reserve. Agree that proper way to do this is to anchor, we're not doing that already, if we want to make progress on other items, people will need the time to focus on other items. Adding anchor tags on everything feels like less important than other PRs.

Ivan Herman: When we move to CR, then the documents have to go through all kinds of publication checking and the link checker will shout at us if we use links that don't resolve.

Kristina Yasuda: we can do it right before CR.

[msporny]

@iherman is this a duplicate of #1077? Could we close #1077?

[iherman]

Not a duplicate but indeed very close. Solving #1077 depends, in my view, on the actions asked for, and discussed, in this issue. But as I described the intention of #1077 in the header of this issue, it is probably fine to close that one.

[msporny]

Not a duplicate but indeed very close. Solving #1077 depends, in my view, on the actions asked for, and discussed, in this issue. But as I described the intention of #1077 in the header of this issue, it is probably fine to close that one.

Acknowledged, marking #1077 as pending close, citing your text above as the reason.

[iherman]

This can be close if and when #1209 is merged.