Schema

TEI schemas for project documents.

This repo contains the schema and annotated template files to be used to enter new data while a proper form is prepared.

Project members can find more documentation as part of the project guidelines.

Contents

• The main ODD specification is tei-betamesaheft.xml. This entails a customization of version 3.5.0 of the TEI Guidelines. Files created by the team in the framework of this project must be valid against this TEI customisation.
• tei-betamesaheft-expanded.odd is a derived ODD (that uses tei-betamesaheft.xml as its source) and it is meant to validate the expanded files generated in the app as well as files generated by other related projects.
• Both RELAXNG schemas, tei-betamesaheft.rng andtei-betamesaheft-expanded.rng are automatically generated from these ODDs through the TEIGarage API.
• The main ODD specification is validated on CI. Also, the RELAXNG schemas are continuously updated on CI.

Build requirements

For creating a XAR file with the schemas:

• ant version: 1.10.7

Build instructions

Run

ant

or

ant xar

Generating Schema files locally

While the workflow is automated to run on CI, should you wish to process the ODDs locally, there are different alternatives.

Generating the Schema files with oXygen

If you have the XML editor oXygen, you can configure a transformation scenario (Ctrl + Shift + C). If the ODD files have the .odd extension (instead of .xml), oXygen already offers an associated scenario to this extension that converts the ODD to RELAXNG, so you only need to select this option.

From a file with the .xml extension, you need to create a new scenario, or even easier, modify one of the TEI existing scenarios to create the the ODD to RELAXNG one. To do so:

1. Press Ctrl + Shift + C to open the Configure transformation scenario(s) window.
2. Select one of ANT scenarios that appear, e.g. TEI P5 DOCX.
3. Then click on Edit and a dialogue will offer you to create a copy instead and edit that copy. Accept.
4. In the window that opens, you can change the name of the scenario (to ODD to RELAXNG for example).
5. Update the build configuration. You can leave all the default options as they are, except for:
   • In the field Build file paste the following path: ${frameworksDir}/tei/xml/tei/stylesheet/relaxng/build-to.xml
   • Click on the Output tab and change in the field Open (at least) the extension of the output file. You can also define here the output folder (as default, oXygen creates a out folder but you can change that behaviour by having in the field Open the following path: ${cfd}/${cfn}.rng).

Generating the Schema files with the TEI toolkit

There are different options:

• You can upload your ODDs to the running instance of TEIGarage: https://teigarage.tei-c.org/
• You can upload your ODDs to Roma: https://roma.tei-c.org/
• You can download the TEI Stylesheets and use them locally: https://github.com/TEIC/Stylesheets

Generating the Schema files following the same process as on CI

Requirements

• Java 11
• Jing ((Debian package or .jar). If you install the debian package, it is recommended to install as well the libraries libbatik-java and libavalon-framework-jav.
• xmllint
• Saxon HE (version 11.0 or greater)
• SchXslt
• In addition, we need two additional XSLT scripts developed by the TEI Council:
  • odd2odd.xsl
  • extract-schematron.xsl

Validation

• The ODD files are validated against the tei_odds RELAXNG schema.
• To carry out the validation we use jing.E.g.:

jing tei_odds.rng tei-betamesaheft.xml

• To validate the ODDs against the schematron constraints of the tei_odds customization, we first extract the schematron constraints from the RELAXNG file using SAXON and the extract-schematron.xsl stylesheet:

java -jar saxon-he-xx.x.jar -s:tei_odds.rng -xsl:extract-schematron.xslt -o:tei_odds.sch

• Then we use SchXslt for the validation of each ODD file. E.g.:

java -jar schxslt-cli.jar -d tei-betamesaheft.xml -s tei_odds.sch -o report-main.xml

ODD Compilation

• For creating the RELAXNG schemas, we first need a compiled version of the ODDs. To do so, we can either use the TEIGarage API, or the XSLT transformation odd2odd.xsl (for the expanded version, we only have this second option and it needs that the main ODD, tei-betamesaheft.xml has been compiled first and saved under the name tei-betamesaheft_compiled.xml):

curl -X 'POST' \
             'https://teigarage.tei-c.org/ege-webservice/Conversions/ODD%3Atext%3Axml/ODDC%3Atext%3Axml' \
             -H 'Content-Type: multipart/form-data' \
             -F '[email protected];type=text/xml' > tei-betamesaheft_compiled.xml

java -jar saxon-he-xx.x.jar -s:tei-betamesaheft-expanded.xml -xsl:odd2odd.xsl -o:tei-betamesaheft-expanded_compiled.xml

Schema generation

For the generation of the RELAXNG schemas we use the TEIGarage API uploading the compiled versions of the ODDs.

                'https://teigarage.tei-c.org/ege-webservice/Conversions/ODD%3Atext%3Axml/ODDC%3Atext%3Axml/relaxng%3Aapplication%3Axml-relaxng/' \
                -H 'Content-Type: multipart/form-data' \
                -F 'fileToConvert=@tei-betamesaheft_compiled.xml;type=text/xml' > tei-betamesaheft.rng

Since at the moment TEIGarage cannot resolve local sources, we delete the @source attribute with sed in the derived ODD (the expanded version).

sed -i 's/ source="tei-betamesaheft_compiled.xml"//' tei-betamesaheft-expanded_compiled.xml 

After this change we can use TEIGarage for the RELAXNG transformation.

We check that the generated schemas are well-formed with xmllint. E.g.:

xmllint --noout tei-betamesaheft.rng 

Working with the Schema files

Your XML editor will recognize the <?xml-model?> instruction on the top of the XMLs files.

Your ODD files should be associated to the the tei_odds customisation:

<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_odds.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_odds.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>

The project files should be associated to the RELAXNG files of this repository:

<?xml version="1.0" encoding="UTF-8"?><?xml-model href="https://raw.githubusercontent.com/BetaMasaheft/Schema/master/tei-betamesaheft.rng" 
schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="https://raw.githubusercontent.com/BetaMasaheft/Schema/master/tei-betamesaheft.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>

A .xar package can be installed in eXist-db to make the RELAXNG schema files available via import statements.