search

w3c / controller-document

Controller Documents
https://w3c.github.io/controller-document/
Other
5 stars 7 forks source link

Make Terminology section normative #91

Closed selfissued closed 2 months ago

selfissued commented 2 months ago

That the Terminology is normative is a matter of fact. It would be strange and confusing for us to say otherwise in the specification.

Per my comment at , the fact that the Terminology is normative is independent of whether we choose to test statements in the specification that don't contain "MUST".

Fixes #46

Cc: @jyasskin

Preview | Diff

iherman commented 2 months ago

We have a family of recommendations, and consistency among those matters. If the terminology section is normative in this specification, it should be in all others and, conversely, if they are not normative in others, then I am opposed to make an exception in this specification.

I note that we do have a discrepancy already, which we should address. Indeed, the terminology section in VCDM is normative, whereas the same section in DI is non-normative. (I did not check all the specs in the family.)

Personally, I'd probably prefer to have normative terminology sections everywhere, but that should be a WG decision.

selfissued commented 2 months ago

Terminology is normative in VCDM and VC-JOSE-COSE. VC-DATA-INTEGRITY is the odd man out in this regard.

dlongley commented 2 months ago

Note that VC 1.1 terminology used to be non-normative:

https://www.w3.org/TR/vc-data-model/#terminology

I'm not sure when / where that got changed in 2.0, it might be a mistake.

EDIT: This PR made the VCDM change: https://github.com/w3c/vc-data-model/pull/1357

iherman commented 2 months ago

The issue was discussed in a meeting on 2024-09-04

View the transcript #### 2.1. Make Terminology section normative (pr controller-document#91) _See github pull request [controller-document#91](https://github.com/w3c/controller-document/pull/91)._ **Brent Zundel:** most things should be on the PR. … 91 is about making the Terminology Section being normative raised by Mike Jones. **Manu Sporny:** this is a regular request from Jeffrey Yasskin. … the idea is that if it's not normative, something bad happens. … it's a philosophical question. … our group says there must be MUST, SHOULD style language. … traditionally, we don't have that in terminology sections. … so we haven't marked them as normative as it does not effect tests. … doing so has no effect, so I don't think we should do it. … given it lacks RFC style language. **Brent Zundel:** one, manu's right, we've never marked out terminology section as normative. … on the other hand, if it changes nothing other than makes some other people happy, maybe we just do it. **Ivan Herman:** consistency is important as manu has said. … I always found more natural for this section to be normative. … but on the other hand the group can decide. … but I also agree with brent that doing is harmless and removes contention. **Michael Jones:** as I said in the issue, there are two different things. … if it's normative, it's a matter of fact. … it being normative doesn't require there being RFC language. > *Ivan Herman:* +1 to selfissued. **Michael Jones:** there's a normative statement..."the entity identified by the id property in the controller document"--that's normative. … I'm not OK saying that something false can be in the document. … we already use a normative terminology on JOSE/COSE. **Manu Sporny:** I'll repeat again, this will have zero effect. … this will not effect anything. not tests. not implementations. none of that, so it's unnecessary. … but if people really want to do this, we can, but it will have no effect. **Brent Zundel:** I'm not interested in a philosophical debate. … it seems like a simple course of action. > *Dave Longley:* +1 ok with the change. **Brent Zundel:** those who don't care can continue not caring. > *Ivan Herman:* +1 to brent. **Brent Zundel:** I think we can merge this since it will be harmless. **Ivan Herman:** just emphasizing that we need to be consistent. **Brent Zundel:** selfissued, can you make the necessary PRs. **Michael Jones:** yes. **Brent Zundel:** any formal objections?
msporny commented 2 months ago

Due to a number of previous merges, this PR now has merge conflicts.

I have manually implemented the PR in this commit 568f38706f24973402a2fc72cb1c5263a3213b1e, making the Terminology section normative.

Closing this PR as it has been applied via commit 568f38706f24973402a2fc72cb1c5263a3213b1e.