Guidance for registry creation

[mnot]

I don't see much information / guidance for groups that want to create a registry; it seems like this would be very helpful in avoiding common pitfalls and not having n different ways to do things (which can be very confusing for registry users, even experienced ones).

The IETF has guidance that might be worth mining for ideas.

[fantasai]

Seems like a good idea, but probably more appropriate for /Guide than the Process...

[chaals]

This would seem to be "please document the outcome of w3c/process#168", no?

I propose closing this as a duplicate.

[dwsinger]

We need a guide document for registries, both ex-nihil creation, and migration of proto-registries

[frivoal]

The overall pull request for registries (w3c/process#335) has been merged. Further fine tweaking is still expected, but this is probably a reasonable time to start thinking about the /Guide part of this story.

[dwsinger]

We should transfer this to the people responsible for the Guide (team). How?

[nigelmegitt]

For info, TTWG began looking at creating boilerplate for registries to avoid re-inventing the wheel each time. Discussion in progress at w3c/ttwg#241.

[TallTed]

@nigelmegitt —

The Verifiable Credentials WG and the Credentials CG have gone down this reinvention road a few times, even in the short time that W3C has officially supported Registries, and I'm sure we will be delighted to take advantage of your boilerplate when ready, to improve what we've got or create something better next time.

Chairs, Editors, and other Participants who have worked on our Registries may have useful feedback during your own wheel reinvention efforts. I encourage you to reach out.

[nigelmegitt]

I encourage you to reach out.

Thanks for the suggestion @TallTed , done so to Chairs initially, at https://lists.w3.org/Archives/Member/chairs/2023JanMar/0041.html

[nigelmegitt]

The Verifiable Credentials WG and the Credentials CG have gone down this reinvention road a few times

@TallTed pointers to those Registries (specifically their Registry Definitions) would be very helpful, either here or on the TTWG discussion.

[TallTed]

@nigelmegitt

I should have included the DID WG... See https://github.com/w3c/did-spec-registries/

I'm having a bit of a brain fog, and can't quickly locate the VCWG or CCG registries I was thinking of, but there are a number of others under W3C — see https://github.com/search?q=org%3Aw3c+registry&type=all

[nigelmegitt]

I just ran into an interesting process-related question related to inclusion of boilerplate registry definition by reference (see w3c/ttwg#241 (reply in thread)): what type of Technical Report can be normatively referenced from a Registry Track document? Must it be a Registry Track document itself?

The use case here is that we publish one document with our baseline registry definition, in terms of custodianship, change process and the two registry entry fields key and status so that we can then include those requirements of the registry definition by reference rather than duplication.

[dwsinger]

I'm fairly sure we shouldn't have restrictive rules on what can be referenced. I suppose that there could be inappropriate references but I can't think of an example. But clearly registries must be able to reference specs (e.g. to be able to say "the value of this field MUST be a valid X as defined in recommendation Y").

I'm sorry, I don't understand your second paragraph!

[nigelmegitt]

Sorry, second paragraph was obtuse, here's another run at it.

We're working on a WG approved boilerplate registry definition, authored with the intent to reuse it whenever we want to publish a new registry. It defines the custodianship, change process, etc. It's not a real registry definition in itself, it just contains text we want to use normatively later. That's the use case.

Clearly if we want to change a registry definition then it has to go through an approvals process, so changing the referenced document would imply that we have to get all the referencing documents re-reviewed too. From that point of view reuse by duplication might make more sense. Ideas and thoughts about better/more elegant mechanisms welcome!

[dwsinger]

We don't normally re-approve referencing documents when we make a normative change to a basis document. Being aware of the dependencies when we approve a change is, of course, best practice (e.g. "hang on, that would break this other document that references this one"). Re-use by duplication might be safer, but I don't see an a priori reason not to do what you suggest, having a common framework for all TTML registries.

[nigelmegitt]

Further discussion of the practicalities of including Registries in Rec track documents at https://lists.w3.org/Archives/Public/spec-prod/2023OctDec/0003.html

In particular, the process rules for updating registry definitions seem to be at best unclear and at worst inappropriate in the current Process. I will raise a separate issue about this.

[frivoal]

This issue is largely overlapping with #247. Maybe they're duplicate of each other, or maybe that one is a subset of this one. In any case, like that one, I think this one could/should be moved to the /Guide repository