Registries in TTWG Specifications

[nigelmegitt]

Timed Text lends itself to metadata applications, and those in turn benefit from having enumerated values, classification schemes etc. For TTML2 and DAPT we might usefully use the new "Registry Track" mechanism, but to do so, we need to make some decisions about how it might work.

TTML2 includes a registry for the ttm:role attribute and w3c/ttml2#1248 relates to improving the management of its values. DAPT has w3c/dapt#83 open, for example, that could benefit from changes to the ttm:role attribute being easier to make, or from a different, separate registry.

If we could have a boilerplate registry definition for TTWG and reuse it, that would save discussion time later.

This discussion is intended to begin that process.

Registry Track

Process: https://www.w3.org/2021/Process-20211102/#registries
(Preserved history: https://www.w3.org/wiki/Registries )

Summary of the requirements:

A Registry = registry definition + registry table(s) + referencing specification(s)

MUST requirements:

• define scope and purpose of each table
• define the fields of each table and their constraints
• define the policy for changes
• define method and criteria for proposing, approving and incorporating changes
• identify the custodian of each table

I think that Rec track documents can contain both the registry definition and the registry tables. Certainly that’s one of the options envisaged in the historical wiki and it’s alluded to in Process §6.5.2, via having a “registry section”.

Strawman proposal for TTWG Policy for changes

Assumptions:

1. Each row in a Registry Table is called an Entry.
2. At some point we will want a placeholder Entry in a Registry Table without knowing the full details ("provisional"), and will want to set it in stone later ("final").
3. Deleting an Entry after it's been in use in the wild is deeply unfriendly.
4. Reusing an Entry after it's been in use in the wild is deeply unfriendly.
5. TTWG's specifications and Registries might outlast TTWG itself, but the public tt email reflector will remain operational
6. GitHub might not always be the version control system being used, but there always will be some version control system ("VCS").

Proposal:

• All Entries have a field to indicate it they are Final or Provisional
• Provisional Entries can be changed or deleted after being published
• Final Entries cannot be changed after being published
• Final Entries can be deprecated but not deleted
• Previously deleted unique identifiers in Final Entries are reserved indefinitely
• Previously deleted unique identifiers in Provisional Entries may be reused later
• The Custodian of the Registry is the TTWG, or in the event that the TTWG is not operational, the Team.
• Change proposals: made by opening a VCS issue on the Registry Table’s VCS repository OR by sending an email request to the WG’s public email address. WG must be able to identify from the request:
  • the Registry Table.
  • The Entries being proposed for addition.
  • The Entries being proposed for deletion or deprecation.
  • The details of the change being requested for each Entry
  • The motivation behind the change proposal
  • Any other supporting information, such as usage identified in the field
  • The proposer is free to open a VCS Pull Request (or equivalent) with the proposed changes in it, and if doing so MUST open a corresponding VCS issue and MUST link the Pull Request to the Issue.
• Change proposal approval depends on the Custodian:
  • If TTWG is Custodian: approval is via a Chair declaring consensus to merge an open Pull Request, following the WG’s Decision Policy. If the proposer has not opened the pull request then another WG member must do so for the proposal to be reviewed.
  • If the Team is Custodian, the Team MUST seek wide review of the proposal and offer a review period of at least 4 weeks, before assessing from the responses received if there is consensus amongst the respondents.

[himorin]

One point, if we mention about the Team (as Custodian, in the event), alternate to the WG's public email address for change proposals needs to be specified?

[nigelmegitt]

I assume that the public email address will continue to exist and operate even if the WG has stopped work. Is that not correct? What alternative email address could we use in that case?

[nigelmegitt]

I've added the assumption, but can change/remove it if it is wrong.

[himorin]

In admin panel of public list for closed WG, I've found a text as following, so I thought post will not be circulated...

Note: This list has been deactivated. The archive remains intact, and you may still edit the subscriber lists below, but the list may not be used unless it is reactivated. If you need to reactivate this list, please send a request to sysreq.

[nigelmegitt]

Opened w3c/process#699 about the lack of default fallback in the Process.

[nigelmegitt]

Opened #244 to track that process issue, for expediency in referencing the issue from the boilerplate text.

[nigelmegitt]

How can we configure Respec for Registry track documents?

[gkatsev]

Seems like there isn't a lot of documentation regarding registries in respec, sleuthing in the code reveals that specStatus should be set to RY https://github.com/w3c/respec/blob/7f7ac9942064afc15b4c6c4efeefce4f9c5664f2/src/w3c/templates/sotd.js#L180

[nigelmegitt]

Where should we put the boilerplate text? I'd suggest in this ttwg repo

[himorin]

+1

we can configure multiple streamlined publication to one repository, each specified with path. So there should be no conflict per support tooling side.

[nigelmegitt]

It occurred to me that we may want to use the registry definition text in the boilerplate by reference instead of by copying, in which case we should create a specific repo for it and publish the document as a ... hmm, what class of document would it be, a Registry track doc? Not sure. Presumably a WG Note wouldn't be normative enough.

[himorin]

Per the Publishing Registries section in the Process, Candidate Registry Snapshot is required to receive AC review similar to rec-track, so I suppose that the Process assumes similar document development formality level as rec-track for Registry. So, I believe something in a level of rec-track should be referenced for that purpose, but not WG Note (Statement should be fine??).

I believe this point is a good question to be raised into the Process discussion...

[gkatsev]

• Deleting an Entry after it's been in use in the wild is deeply unfriendly.

• Reusing an Entry after it's been in use in the wild is deeply unfriendly.

Strong support for this. Ideally, we don't want to actually delete anything but instead only deprecate and mark things as no longer used so that items wouldn't get re-used at a later date.

[gkatsev]

In the call there was mention of having a placeholder entry, where not all the info is available yet, but we still wanted it to be out there. @himorin then mentioned that registries will still be published to /TR, so, maybe the direction here is similar to specs, we can merge stuff to an editor's draft which is published on github/elsewhere and then only gets published to /TR once it's available.

[nigelmegitt]

The publication requirements for Registries are a lot lower than for Rec track docs, so I was envisaging that we would publish early and often, rather than having a pipeline. For example, it would be good if we could set up auto publication on pull request merge to the ED.

But I agree in principle, a pipeline approach with changes in a draft could work. It would just mean that folk have more versions of the document to check. I could be persuaded either way.

[gkatsev]

I'm not sure my suggestion is necessarily better.

One alternative is to have a status associated with each entry. It'll go hand-in-hand with my proposal for deleted entries (#241 (comment)).

[nigelmegitt]

Yes, that'd work. Status would go:

Provisional -> Final -> Deprecated

?

[gkatsev]

Yeah, something like that.

[nigelmegitt]

I've written some detail about the status transitions that are permitted, and how keys can or cannot be reused, in #243.

[mikedo]

I assume this is a candidate to be ported? https://www.w3.org/TR/ttml-profile-registry/

[himorin]

This seems for me the entire document (published as NOTE) is for MIME type registration, including profile registry part which is used as an optional parameter 'profile' to MIME type.
But, I am quite not sure why this is fine with Group NOTE, since registration process requires

Draft a proposal for the Media Type registration as a normative part of your specification

[nigelmegitt]

The normative part is the reference to it from the Rec, I believe.

[nigelmegitt]

Thanks for raising this @mikedo . I did not expect to port the TTML Profile Registry but we certainly could, if there's a reason to. The document already includes text describing the update process: is there a good reason to port it to a new process?

[nigelmegitt]

There probably are reasonably good reasons to port it to a new process, since we've thought a bit harder about the lifecycle of registry entries, and the custodianship.

[nigelmegitt]

Examples of other Registry approaches

[nigelmegitt]

W3C Alternative and Augmented Communication (AAC) Symbol Registry at https://raw.githack.com/w3c/aac-registry/main/snapshot.html

[chrisn]

A couple of recently created registries from Media WG:

• WebCodecs Codec Registry: https://w3c.github.io/webcodecs/codec_registry.html
• WebCodecs VideoFrame Metadata Registry https://w3c.github.io/webcodecs/video_frame_metadata_registry.html

Looking at your proposed policy, I wonder if Media WG should revisit requirements for reuse and deletion of entries...

[nigelmegitt]

I agree @chrisn , and have opened w3c/webcodecs#644 highlighting that those registries don't actually meet the Process requirements for W3C registries.

[mikedo]

Just consistency. Happy where it is and I am not volunteering.

[nigelmegitt]

Consistency is a pretty strong reason. Also I think the Profile Registry could possibly benefit from tightening up the "how to propose changes" text to match the Registry track requirements, and the external perception of publishing as a W3C Registry may well be stronger than the current WG Note.

Also, the TTML Profiles Registry is a good test case: at least as a thought experiment, we should ask ourselves: "if we were to apply the boilerplate approach to the TTML Profiles Registry, would it cause any problems?"

[nigelmegitt]

The TTML Profiles Registry "Registration Entry Requirements and Update Process" is effectively the Registry Definition.

It includes some must and should rules about each entry in the Registry, and defines the following process:

An update to this registry is an addition, change or deletion of an entry. Any person can request an update to this registry by email notice to the chairman of the Timed Text Working Group who will place it on an upcoming meeting agenda and notify the requestor. Consideration and disposition of the request is by consensus of the W3C Timed Text Working Group. The Chair will then notify the requestor of the outcome and update the registry accordingly. Although profiles can be deleted, there is no intent to re-use deleted profile values. That is, the intent is that profile entries are "stable".

Comparing this to the straw man with which I began this discussion:

• It doesn't have the concept of Final vs Provisional
• It says values can be deleted but reuse is not the intent, so it gives hints rather than hard and fast rules about what can or can't happen to old values
• Change requests are by email to the Chair of TTWG, not to the public reflector
• The basic decision-making process, i.e. consensus of the TTWG, is the same
• There's no fallback mechanism in case TTWG cannot handle the request

This suggests that we could transfer to a Registry Track document, hopefully at the same URL, with something like the proposed boilerplate text, without losing much if anything. It looks to me like it would probably be an improvement.

@mikedo appreciate your non-volunteering! I see that you and I are both listed as Editors.

[nigelmegitt]

I'm working on the boilerplate text as per #242 - it's incomplete, but I've opened a draft pull request #243 just so folk can play along at home if they want.

[nigelmegitt]

I won't do anything more on this at least until 20th Feb now.

[nigelmegitt]

Pull request #243 open for review now, out of draft state.

[mikedo]

This registry is cited by ISO and perhaps other SDOs. Be careful that you are actually solving a problem rather than exercising "completeness".

[nigelmegitt]

As described at #241 (reply in thread) I think there are subtle problems as it stands now that we had not fully thought through. I would not propose a change to the URL, and I believe it is within our remit to modify the change process in the document without having to resubmit for external review.

By the way @mikedo the format of this discussion page allows you to comment in reply to specific threads within the discussion, if you type in the relevant "Write a reply" box beneath the comment, rather than the "Write a comment" box at the bottom of the page, which starts a new thread.

[mikedo]

@nigelmegitt Yes, a new discussion to reconsider undertaking this "administrative refactoring" was intentional. Arguably, this comment does not even belong in this issue about "Registries in TTWG Specifications" at all. My concern is that this group needs to consider the impact to references from outside TTWG and W3C.

[nigelmegitt]

Agreed @mikedo, we need to consider that impact. I mentioned the threading because the comment begins "This registry" but from context, I think you meant the TTWG Profiles Registry specifically rather than the generic W3C Registry approach that is the subject of this discussion page. Apologies if I misunderstood.

[egekorkan]

I talked with @nigelmegitt on the Breakout day a couple of weeks ago and after a first analysis, I must say that I really like the work you have done. The WoT WG will extend their registry analysis with what we find here and in the boilerplate. It is being tracked by w3c/wot#1188 where you can also find the link to the current analysis.

Thank you!