Repository navigation
Break in normative chain for schemas #1566
Description
The (normative) §6.1.5.2.1 on container.xml says:
The contents of this file MUST be valid to the schema in § E.2.1 Schema for container.xml after removing all elements and attributes from other namespaces (including all attributes and contents of such elements).
§ E.2.1 says:
The schema for container.xml files is available at https://github.com/w3c/epubcheck/tree/master/src/main/resources/com/adobe/epubcheck/schema/30/ocf-container-30.nvdl.
I do not think it is acceptable that the schema file (which is normative per the first quote above) is stored on a repository that is not under the control of the WG. I believe the normative schema should be stored on the WG's page.
The same issue arises for the Media Overlay schema.
Activity
mattgarrish commentedon Mar 13, 2021
It might be more useful to remove the schema references entirely. We don't reference a schema for the package document, for example, and no one has complained as we have a human-readable content model definition in the specification that can be reviewed.
Media overlays already defines its content model in the specification, just like the package document does.
The container.xml definition has always been pretty lousy, however, as we minimally define it and then force authors to read a schema to figure out the actual constraints. If we add a similar human-readable definition for the container.xml file like we have the others, all we'd need to say, for example, is that the file must conform to that definition.
iherman commentedon Mar 14, 2021
An intermediate solution, followed by many working groups: the WG does publish the xml schemas somewhere (I guess simply in the WG's repository, possibly minting a cleaner W3C URI that is redirected to it), but the schemas are not normative, just there to help implementers.
This is exactly what we did for publication manifests...
mattgarrish commentedon Mar 14, 2021
We've discussed this in the past and there's been no interest in maintaining the schemas in this group separately from epubcheck. Is that going to change?
mattgarrish commentedon Mar 14, 2021
For reference, the following schemas are all part of validating epub (and were maintained by the IDPF WG in the past):
It doesn't make sense to only keep two schemas from all these others that go into validating epub. But if we go this route we're seemingly taking on the chore of maintaining a good chunk of epubcheck again, which is what we were doing in the past. That in turn led to confusion as the epubcheck schemas continued to be updated while the WG ones were frozen to what they were at the end of the revision.
There's no perfect solution here, but given the work of maintaining all the schemas, limiting ourselves to the human-readable definitions is arguably a more productive use of WG time.
iherman commentedon Mar 15, 2021
Probably not all of those have an equal importance. My gut feeling is that the schemas that formally back up the EPUB-specific XML dialects (package, metadata, media overlay) are important enough to be, in some sense, "part" of the spec, and hence should be part of the W3C WG's job. The XHTML/SVG dialects to handle, e.g., epub:type feels different to me.
But I do not have the history, so I prefer to let @TzviyaSiegman @rdeltour @GarthConboy @bduga @danielweck to chime in and I would yield to them on this.
In the meantime, the text will have to be changed anyway, turning the reference to the schemas into notes and not part of the normative text. (I will propose a PR for this, but I am not sure it will be today.)
rdeltour commentedon Mar 15, 2021
Just a thought: given that the EPUBCheck website will be available on w3.org and it is built from EPUBCheck's source repository, it will be easy enough to publish the up-to-date EPUBCheck schemas there. For instance at https://www.w3.org/publishing/epubcheck/schemas/, which can then be informatively referenced from the spec?
iherman commentedon Mar 15, 2021
It is a bit more complicated, actually. Looking at the current text, §E schemas contains a reference to 5 schemas:
All of these are referred to normatively. (3) and (4) are normatively referring to existing recommendations, (1), (2), and (5) are currently at epubcheck. If we want to be consistent, we have two options:
An additional point: the (currently normative) references to the enc and sig schemas are to the XML Security RELAX NG Schemas Note. Emphasis on “Note”. It may be o.k. to refer to those normatively nevertheless (see Normative References), but we will have to check in case we go with alternative (2).
I am mildly more in favor of (1), but I am not sure either.
mattgarrish commentedon Mar 15, 2021
I'd still propose that we change the normative requirements so that the content remain valid to the constraints of the specification instead of the schemas, and add the missing definitions. The latter is overdue.
I'm fine with informative schemas. At the end of the day, the specification is the authoritative source, not the schemas, so having both be normative is confusing in any case.
I just don't want to take ownership over them again as the duplication of work with epubcheck doesn't fill me with joy. 😄
Would it make sense to begin a 3.3 branch in epubcheck where we can update the schema-related issues prior to REC @rdeltour ?
rdeltour commentedon Mar 15, 2021
Sounds good to me!
iherman commentedon Mar 15, 2021
I read this to mean that you are in favor of (2), ie, that there would not be normative dependencies on the schemas? (That would be my favorite.)
I am happy to attempt to do a PR in this direction.
😄
mattgarrish commentedon Mar 15, 2021
Ya, I'm getting confused! I meant to write informative "schemas" in that comment. I believe that's closer to 1, right?
iherman commentedon Mar 15, 2021
Let the PR (coming...) speak for itself! :-)
iherman commentedon Mar 15, 2021
See #1573.
@rdeltour, if you have a set of nice (and short) URL-s for the schema files through
https://www.w3.org/publishing/epubcheck, I am happy to change those references, too.iherman commentedon Mar 19, 2021
The issue was discussed in a meeting on 2021-03-18
List of resolutions:
View the transcript
2. Normative Schemas
See github issue #1566.
See github pull request #1573.
Dave Cramer: the quick summary is that epub has historically had some normative schemas
… i think it would be a good idea to change to say that the spec is normative, and that any references to spec are informative only
Matt Garrish: that's part of it
… Ivan particularly didn't like that we were referencing across to epubcheck repo
… basically the PR that we have open now makes that schema section informative, and adds some description boxes to things we hadn't previously defined
Dave Cramer: this makes the distinction between spec and epubcheck clearer, which seems good for everyone