schema/README.md

   1 # Schemas for Validating ODF Files
   2
   3 Schemas that can be used for validating ODF files
   4
   5 subdirs:
   6
   7 - `mathml2`: W3C MathML 2.0 XML Schema (needed for Math embedded objects)
   8 - `odf1.0`, `odf1.1`, `odf1.2`: official OASIS RelaxNG schemas
   9 - `odf1.3`: current OASIS draft ODF 1.3 RelaxNG schema
  10 - `libreoffice`: draft ODF schema, with additional LO extensions
  11
  12 The extension schema in `libreoffice/` is used by all unit tests if
  13 `--with-export-validation` is given, which is the default.
  14
  15 Notably this means that if you add a new feature to the ODF filters and you add
  16 the required unit test for the new feature, then most likely the test will fail
  17 with a complaint from the validator; in this case the schema needs to be
  18 updated to contain the new elements and attributes.
  19
  20 The extension schema uses the `RelaxNG` "`include`" feature to refer to the ODF
  21 schema; this means that it only contains those parts of the schema that
  22 actually need to be changed - this works well in many cases because the ODF
  23 schema is quite well structured with many named patterns, but unfortunately
  24 there are a few places where that isn't the case and large chunks needed to be
  25 copied to override them.
  26
  27 In the easy case, to add an attribute you just want to search for the
  28 corresponding element, which will have a "`foo-attlist`" named pattern, and then
  29 add another attribute like this:
  30
  31   <rng:define name="draw-enhanced-geometry-attlist" combine="interleave">
  32     <rng:optional>
  33       <rng:attribute name="drawooo:sub-view-size">
  34         <rng:ref name="string"/>
  35       </rng:attribute>
  36     </rng:optional>
  37   </rng:define>
  38
  39 Currently only the features that are actually exported in the unit tests have
  40 been added to the schema; there is still some work to do here to add
  41 everything; the crashtesting script also does ODF validation of all files and
  42 now also uses the custom schema.
  43
  44 Unfortunately it turned out that there are a lot of extensions already for
  45 which no proposal exists [1], and in many cases not even an entry on the Wiki
  46 [2], so clearly something like this extension schema is needed.
  47
  48 [1] `git grep TODO schema/libreoffice`
  49
  50 [2] <https://wiki.documentfoundation.org/Development/ODF_Implementer_Notes/List_of_LibreOffice_ODF_Extensions>