SSRQ-Schema

Dieses Repository beinhaltet Quellcode und sonstige Dateien im Zusammenhang mit dem XML-Schema der Sammlung der Schweizerischen Rechtsquellen.

• SSRQ-Schema
  • Initiale Zielsetzung der Entwicklung
  • Dokumentation
    • Versionierung
    • Was ist wo?
      • src/docs
      • src/schema
    • Technisches Setup
      • Verwendete Software / Technologien
      • Einrichtung / Anforderungen an die Umgebung
    • Anpassung
      • Anpassung von Übersetzungen
      • Anpassung von Inhaltstypen
      • Anpassung von Attributwerten
      • Anpassung / Erstellung von Tests
      • Links zwischen Bestandteilen des Schemas und der (übrigen) Dokuseite
    • Schema erzeugen
      • Erzeugung einer neuen Version und Upload
      • Erzeugung der Dokumentation
        • Befehle
        • Datei- / Ordnerstruktur
  • Autor:innen
  • Lizenzierung

Initiale Zielsetzung der Entwicklung

1. Aktualisierung und Anpassung des bestehenden Schemas an Neuentwicklungen TEI-Guidelines
2. Aufarbeitung von Rück-/Misständen
3. Eindeutige Versionierung (Daten entsprechen einem Schema einer bestimmten Version)
4. Testbarkeit
5. Erzeugung einer Web-Dokumentation aus dem Schema heraus (ersetzt die Dokumentation im Wiki)
6. Erarbeitung von XSLT-Skripten (o.ä.) zur Migration zwischen Datenständen
7. Öffentlicher Zugriff auf vormals interne Dokumentation

Dokumentation

Versionierung

Die Versionierung des Schemas erfolgt gemäß Semantic Versioning. Dies erlaubt die eindeutige Zuordnung eines bestimmten Datenmodells zu einer bestimmten Version. Die Grundregel lautet:

MAJOR.MINOR.PATCH

Die Versionsnummer wird als Tag in der Git-History hinterlegt und ist zudem in der Datei pyproject.toml in der Tabelle ssrq.schema.meta hinterlegt. Die kompilierten Versionen des Schemas folgen dem Muster tei-ssrq-schema-version.(rng|odd) und verwenden die in dieser Projektkonfiguration hinterlegte Versionnumer.

Was ist wo?

Das Repository ist wiefolgt aufgeteilt:

ssrq-schema/
├─ .github/
├─ src/
│  ├─ docs/
│  ├─ schema/
│  │  ├─ commons/
│  │  ├─ elements/
│  │  ├─ examples/
│  │  ├─ main.odd.xml
├─ utils/
│  ├─ commons/
│  ├─ docs/
│  ├─ schema/
├─ .gitignore
├─ .gitmodules
├─ CITATION.cff
├─ LICENSE
├─ mkdocs.yml
├─ poetry.lock
├─ pyproject.toml
├─ README.md
├─ Taskfile

1. src: hier befinden sich die Quelldateien des Schemas sowie Teile der Dokumentation (.md), die nicht Teil des ODDs sind
2. tests: der Name sagt es
3. build: dieser Ordner wird dynamisch generiert und steht nicht unter Versionskontrolle; hier befinden sich die kompilierten Schemadateien sowie die HTML-Doku

src/docs

Siehe Erzeugung der Dokumentation.

src/schema

• der Unterordner elements enthält die Schema-Deklarationen je Element; pro spezifizierten Element wird eine Datei nach dem Muster name.odd.xml erstellt – sofern verschiedene Spezifikationen für unt. Typen (Einleitung, Transkripte, etc.) festgelegt werden, wird der Typ mit -type an den Namen angehängt
• der Unterordner commons enthält Spezifikationen, die von verschiedenen Teilen des Schemas wiederverwendet werden
  • classes.odd.xml: Klassendefinitionen
  • constrains.odd.xml: globale Schematron-Regeln
  • content.odd.xml: Inhaltstypen
  • datatypes.odd.xml: Datentypen, die als Inhalt für Attribute oder Elemente verwendet werden
  • modules.odd.xml: SSRQ-spezifische Module in Ergänzung der TEI
  • patterns.odd.xml: sog. Patterns, die als Inhaltsmodelle an verschiedenen Stellen verwendet werden – bspw. das Muster für Personen-IDs
• konkrete Schemadeklrationen werden auf der obersten Ebene festgelegt; die benötigten Bestandteile werden hier eingebunden

Technisches Setup

Verwendete Software / Technologien

• jing
• mkdocs
• poetry
• pre-commit
• pydantic
• pytest
• saxonche
• TEI ODD
• TEI Stylesheets

Einrichtung / Anforderungen an die Umgebung

Das Repository wird regulär über git clone ausgecheckt. Für die vollständige Funktionalität müssen dann noch die Git-Submodule initialisiert werden:

git submodule update --init --recursive

Für die Kompilierung des Schemas sowie die Ausführung der Tests ist es erforderlich, dass eine JAVA-Laufzeitumgebung sowie Python in Version 3.11 auf dem System installiert ist. Ferner ist es erforderlich, dass der Python-Paketmanager poetry installiert ist.

Alle weiteren Abhängigkeiten können dann über folgenden Befehl install werden

sh ./Taskfile install

Wiederholt ausgeführte Aufgaben (bspw. Ausführung der Tests) sind im sog. Taskfile gebündelt. Für die einfachere Benutzung empfiehlt es sich in der lokalen Shell-Konfigurationen einen Alias für das Taskfile nach dem Schema alias run=./Taskfile einzurichten, dann lassen sich die diversen Aufgaben nach folgendem Muster ausführen:

run test

Weitere Parameter (bspw. -s um print-Statement immer anzuzeigen) können einfach übergeben werden:

run test -s

Anpassung

Anpassung von Übersetzungen

Das Schema ist in vier verschiedene Sprachen übersetzt: de, fr (sowie z.T. en und it)

Beschreibungen von Elementen werden i.d.R. in Deutsch, Englisch und Franzözisch verfasst. Die Spezifikation eines Element (siehe /src/elements) sollte immer ein Element <desc/> je Sprache enthalten. Für das Element <cell/> sieht das bspw. so aus:

<desc xml:lang="de" versionDate="2023-03-03">Auszeichnung von Tabellenzellen.</desc>
<desc xml:lang="en" versionDate="2023-03-03">Table cell mark-up.</desc>
<desc xml:lang="fr" versionDate="2023-03-03">Balisage des cellules de tableau.</desc>

Neben der Sprache sollte das Attribut @versionDate verwendet werden.

Beschreibungen von Attributwerten werden in der z.T. in der digitalen Edition verwendet und müssen in diesen Fällen immer in allen vier Sprachen angelegt werden. Dies kann folgendermaßen aussehen:

<valItem ident="Sack">
    <desc xml:lang="de" versionDate="2023-03-17">Sack</desc>
    <desc xml:lang="de" type="plural" versionDate="2023-03-17">Säcke</desc>
    <desc xml:lang="fr" versionDate="2023-03-17">sac</desc>
    <desc xml:lang="fr" type="plural" versionDate="2023-03-17">sacs</desc>
    <desc xml:lang="en" versionDate="2023-03-17">bag</desc>
    <desc xml:lang="en" type="plural" versionDate="2023-03-17">bags</desc>
    <desc xml:lang="it" versionDate="2023-03-17">sacchetto,</desc>
    <desc xml:lang="it" type="plural" versionDate="2023-03-17">sacchetti</desc>
</valItem>

Anpassung von Inhaltstypen

ToDo

Anpassung von Attributwerten

Todo

Anpassung / Erstellung von Tests

Die im Schema festgelegten Regeln werden automatisch mit pytest überprüft. Hierfür müssen Testfälle definiert werden. Tests werden im Unterordner test erstellt. Es wird zwischen Tests, die allgemeine Bedingungen des Schema prüfen, und elementspezifischen Tests unterschieden. Allgemeine Tests befinden sich gemeinsam mit den Konfigurationsdateien (conftest.py) auf der obersten Ebene. Elementspezifische Tests befinden sich in test/element. Nach Möglichkeit sollten immer mehrere Fälle je Test überprüft werden -- siehe hierzu Parametrizing fixtures and test functions.

Im Testfile eines Elements müssen zunächst die benötigten Module importiert werden.

import pytest
from ssrq_cli.validate.xml import RNGJingValidator

from main import Schema

from ..conftest import SimpleTEIWriter

Anschließend können die Tests erstellt werden. Hierbei wird zwischen Tests zum Prüfen von RELAXNG- und Schematron-Regeln unterschieden (siehe bspw. test_idno.py). Die Testdefinition ist dabei weitestgehend an der Triple-A-Rule (Arrange-Act-Assert) orientiert und folgt typischerweise folgendem Muster:

# ARRANGE
@pytest.mark.parametrize(
    "name, markup, result",
    [
        (
            "valid-text",
            "<text xmlns='http://www.tei-c.org/ns/1.0'><body><div><p>foo</p></div></body></text>",
            True,
        ),
        (
            "valid-text",
            "<text xmlns='http://www.tei-c.org/ns/1.0'><body><div><p>bar</p></div></body><back><div><p>foo</p></div></back></text>",
            True,
        ),
        (
            "invalid-text-with-back-only",
            "<text xmlns='http://www.tei-c.org/ns/1.0'><back><div><p>foo</p></div></back></text>",
            False,
        ),
        (
            "invalid-text-with-attribute",
            "<text type='foobar' xmlns='http://www.tei-c.org/ns/1.0'><body><div><p>hallo welt!</p></div></body></text>",
            False,
        ),
        (
            "invalid-text-with-group",
            "<text xmlns='http://www.tei-c.org/ns/1.0'><group><body><div><p>hallo welt!</p></div></body></group></text>",
            False,
        ),
    ],
)
def test_text(
    element_schema: dict[str, str],
    writer: SimpleTEIWriter,
    name: str,
    markup: str,
    result: bool,
):
    validator = RNGJingValidator()
    writer.write(name, markup)

    # ACT & ASSERT innerhalb der generischen Funktion `test_element_with_rng`
    test_element_with_rng("text", name, markup, result, False)

Sollen nur die Tests eines Elements ausgeführt werden, dann kann dazu folgender Befehl verwendet werden:

run test tests/src/schema/elements/test_cell.py

Links zwischen Bestandteilen des Schemas und der (übrigen) Dokuseite

Aus dem Schema wird statisch eine Dokumentationsseite erzeugt (siehe oben). Einige Bestandteile dieser Seite liegen statisch als .md-Dateien vor. Verknüpfungen zwischen Schema und diesen Einzeldateien (oder umgekehrt) können über direkten Verweis auf die jeweilige Datei vorgenommen werden.

Aus dem Schema heraus:

<ref target="print.md"

Oder aus einer Markdown-Datei auf ein Element:

Der Tag [TEI][tei.de.md]

Die relative Pfaden (von a zu b) werden während des Build-Prozesses automatisch aufgelöst und müssen nicht händisch nachgeführt werden.

Schema erzeugen

Erzeugung einer neuen Version und Upload

Die Version eines Schemas ist je Inhaltstyp in der Datei pyproject.toml festgelegt. Sieh hierzu den Abschnitt Versionierung. Der Befehl

run compile

erzeugt die jeweiligen Schemadateien. Je Inhaltstyp werden eine .odd sowie eine .rng im Ordner /dist gespeichert.

Erzeugung der Dokumentation

Die Dokumentation für das Schema zur Validierung der Transkriptionen der ‚Stücke‘ (der Quelldokumente) wird aus dem ODD selbst erzeugt. Mithilfe des Dokumentations-Frameworks mkdocs wird eine statische HTML-Seite erzeugt. Diese beinhaltet sowohl die Dokumentation der einzelnen Tags als auch erläuternde Texte zu philologischen Grundlagenentscheidungen.

Befehle

• run serve-docs: Erzeugt die Dokumentation und startet zugleich einen Webserver (gedacht für die lokale Entwicklung)
• run build-docs: Generiert die statische Dokumentationsseite. Das Ergebnis wird im Ordner /site abgelegt.

Datei- / Ordnerstruktur

Die Quelldateien für die Dokumentation sind einerseits die einzelnen Elementdefinitionen, diese befinden sich /src/elements und andererseits spezifische Dateien für die Dokuseite:

• mkdocs.yml: Konfigurationsdatei für mkdocs; enthält ebenso Übersetzungen für die Navigation
• utils/docs/odd2md.py: Python-Skript zur Umwandlung der ODD-Datei in einzelne Markdown-Dateien je Element (Quelle ist ein kompiliertes ODD)
• utils/docs/doc_hooks.py: Hook (‚Event-Skript‘), welches von mkdocs beim Start aufgerufen wird – der Hook bindet wiederum odd2md.py ein
• src/docs: grundlegende Quelldateien für die Dokuseite
  • index.md: Startseite (das Kürzel .de oder .fr verweist auf die jeweilige Sprachversion)
  • assets: CSS, Bilddateien usw.
  • base: Markdowndateien mit statischen Beschreibungstexten (bspw. Datierungsrichtlinien)
  • elements: leerer Ordner, in welchen die Markdowndateien je Element temporär gespeichert werden
  • translations: Übersetzungen für Bestandteile des UIs / des Inhalts

Autor:innen

• Bastian Politycki – Swiss Law Sources
• Christian Sonder – Swiss Law Sources
• Pascale Sutter – Swiss Law Sources

Lizenzierung

Siehe LICENSE.