`<elementSpec>` allows a direct child `<valList>`, as well as `<valList>` inside `<content>`

[martindholmes]

Arising from today's ATOP meeting with @sydb and @HelenaSabel:

It is possible to put a <valList> as a direct child of <elementSpec>, in which case the current Stylesheets make its <valItem>s the possible values for its content; or you can put a <valList> inside the <content> element, to get the same result. The former is problematic because it's not clear how the child <valList> could or should combine with a sibling <content> element.

[martindholmes]

Personally I think the solution is to disallow <valList> as a direct child of <elementSpec>, and insist on its being a child of <content>, in which case the way it is combined with other children of <content> can be correctly constrained; there are workable scenarios (e.g. where <valList> is in alternation with something else such as <elementRef>), and scenarios where the result is a broken RELAXNG file (such as when <valList> is in <sequence> with an <elementRef>).

[sydb]

I think @martindholmes’ suggested solution (no longer allow <valList> as a direct child of <elementSpec>) is quite reasonable. It is a backward-incompatible change, and thus would require deprecation. It would also be reasonable to allow them (<valList> children of <elementSpec>), but only in alternation with <content>. That is, the main problem is an <elementSpec> that has both <valList> and <content> as children. But that is also a backward-incompatible change that would require deprecation.

So all in all, I think I lean towards @martindholmes’ solution a bit more than this “keep it but only allow it (<valList> child of <elementSpec>) OR <content> child of <elementSpec>” solution.

Here is a collection of test files and results; the result files (*.rnc) have only the single definition of interest. They indicate that the Stylesheets work when <valList> is a descendant of <content>, but not when it is a child of <elementSpec>. @martindholmes — in your tests a single elementSpec/valList worked, yes? What is the difference?

TEI_issue_2876_sydb_tests.zip

[sydb]

2026-04-10 Council meeting says to deprecate the use of <valList> as a direct child of <elementSpec>.

[martindholmes]

@sydb @HelenaSabel I don't see any way to formally deprecate the use of an element as part of a content model, because the <elementRef> element does not have @validUntil (and almost certainly the Stylesheets would have no handling for it). Therefore I propose we follow the approach for "No longer recommended" from https://tei-c.org/documentation/tcw27/, and add a <remarks> element which explains that <valList> will no longer be a valid child of <elementSpec> on a specific date; and we then add @validUntil on that <remarks> attribute so that the coming change is visible on the spec page, and we are reminded in time to carry out the change and remove the <remarks>.

[martindholmes]

See PR #2886.