XML Schema Definition des signal.xml-Dateiformats

Hier entsteht eine XSD-Datei des Dateiformats signal.xml - work in progress! Zweck dieser Datei ist vor allem die Validierung von Vorlagen im Signals-Verzeichnis. Einige formal zulässige, aber in Signalvorlagen nicht sinnvolle Elemente und Attribute sind deshalb in dieser Datei bewusst nicht definiert, damit sie bei toolgestützten Validierungen angemeckert werden.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
    <xs:annotation>
        <xs:documentation xml:lang="de">XML Schema Definition für das signal.xml-Datenformat des Zugsimulators Zusi 3 von Carsten Hölscher. Mit diesem Dateiformat werden Vorlagen für Signaleinbauten definiert. Elemente und Attribute, die als veraltet gelten und von der Referenzimplementation (Zusi3DEditor.exe) zwar noch gelesen werden können, aber nicht mehr geschrieben werden, sind nicht alle in diesem Schema enthalten.  Die Definitionen unterhalb des Signal-Elements sind gleichzeitig auch Bestandteil des st3-Dateiformats. Deshalb gibt es einige Elemente und Attribute, die in einer signal.xml-Datei vom Zusi-3D-Editor zwar als formal zulässig akzeptiert werden, aber nur im Kontext einer st3-Datei sinnvoll sind. Solche in signal.xml-Vorlagen nicht sinnvollen Bestandteile sind darum in dieser xsd bewusst nicht definiert. Allgemeine Hinweise zu Zusi-XML-Datenformaten: Bei Attributen existiert für jeden Typ ein Standardwert, der verwendet wird, wenn das Attribut nicht vorhanden ist. Es folgt daraus, dass das Attribut auch beim Schreiben weggelassen werden kann, wenn sein Wert dem Standardwert entspricht. Zusi macht das konsequent so. Der Standardwert ist - bei Ganzzahlen (integer, integer 64 bit, integer enum, bool) der Wert 0. - bei Gleitkommazahlen (single) der Wert 0.0. - bei Zeichenketten (string) die leere Zeichenkette. - bei Farben (D3DColor) die Farbe R=G=B=A=0. - bei Datums-/Zeitangaben (date,time) der 30. Dezember 1899, 00:00:00. Dateipfade (Datei Dateiname="...") sind entweder - Pfade relativ zum Zusi-Datenverzeichnis (Signals\Deutschland\Signal.ls3), wobei ein führender Backslash erlaubt ist und ignoriert wird, oder - wenn sie keinen Backslash enthalten, Dateien im selben Verzeichnis wie die Datei, in der der Pfad steht. Insbesondere können Dateien, die auf einem anderen Laufwerk als das Zusi-Datenverzeichnis liegen, nicht referenziert werden. Programmseitig generierte XML-Dateien, die UTF-8-kodiert sind, sollten eine Byte Order Mark (0xEF,0xBB,0xBF) am Anfang enthalten, damit Texteditoren sie zuverlässig als UTF-8 erkennen.</xs:documentation>
    </xs:annotation>
    <xs:element name="Zusi">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="Info"/>
                <xs:element ref="Signal"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="Info">
        <xs:complexType>
            <xs:annotation>
                <xs:documentation xml:lang="de">DateiTyp muss bei signal.xml-Dateien immer 'Signal' sein. MinVersion und Version müssen im aktuellen Dateiformat immer 'A.1' sein. Das ältere A.0-Dateiformat ist nicht Gegenstand dieser xsd-Datei. A.0 wird seit April 2007 von den Zusi-Editoren nicht mehr neu geschrieben und sollte deshalb nicht mehr in freier Wildbahn vorkommen.    Wie in allen anderen Zusi-XML-Formaten sind auch im Info-Element von signal.xml folgende Attribute zulässig. Da es allerdings keinen Editor für signal.xml gibt, werden die Inhalte nirgendwo angezeigt:    Beschreibung ist eine Freitext-Beschreibung des Objekts, die von Editoren ggfs. dem Benutzer angezeigt werden kann. Mehrere Zeilen werden mit Semikolon getrennt. DateiKategorie ist eine frei vergebene Kategorisierung der Datei. Das Attribut wird derzeit normalerweise nicht genutzt. Für einheitliche Vorgaben zur Kategorisierung ist zukünftig die bei Zusi 3 mitgelieferte Datei _Setup/categories.txt vorgesehen. EinsatzAb und EinsatzBis können dem Benutzer Hinweise geben, in welcher Epoche das Objekt zeitlich sinnvoll einsetzbar ist. ObjektID ist eine Nummer für das Objekt. Das Attribut wird derzeit normalerweise nicht genutzt. Hier könnte es sein, dass zukünftig eine zentral vorgegebene Nummerierung eingeführt wird.</xs:documentation>
            </xs:annotation>
            <xs:sequence>
                <xs:element ref="AutorEintrag" minOccurs="1" maxOccurs="unbounded"/>
            </xs:sequence>
			<xs:sequence>
				<xs:annotation>
					<xs:documentation xml:lang="de">
						Ab der Zusi3-Hauptversion 3.1.3.0 (und einigen vorherigen Betaversionen der Programme) ist in allen Zusi-XML-Formaten an dieser Stelle das Element 'Datei' zulässig. Es dient dazu, Bezüge zu Dateien in Zusi-fremden Dateiformaten herzustellen, damit solche Dateien bei Exportoperationen des Dateiverwaltungsprogramms automatisch mitkopiert werden. Typische Anwendungsfälle sind z.B. jpg-Dateien der Fahrplanintros oder in Streckensound-Ereignissen verwendete wav-Dateien.
					</xs:documentation>
				</xs:annotation>
                <xs:element ref="Datei" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
            <xs:attribute name="Beschreibung" type="xs:string"/>
            <xs:attribute name="DateiKategorie" type="xs:string"/>
            <xs:attribute name="DateiTyp" type="xs:string" use="required" fixed="Signal"/>
            <xs:attribute name="EinsatzAb"/>
            <!-- Datentyp TDateTime -->
            <xs:attribute name="EinsatzBis"/>
            <!-- Datentyp TDateTime -->
            <xs:attribute name="MinVersion" type="xs:string" use="required" fixed="A.1"/>
            <xs:attribute name="ObjektID" type="xs:int"/>
            <xs:attribute name="Version" type="xs:string" use="required" fixed="A.1"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="AutorEintrag">
        <xs:annotation>
            <xs:documentation xml:lang="de">AutorAufwand ist der zur Erstellung des Objekts benötigte Zeitaufwand, gemessen in 'Haus-Einheiten'. 1 Haus-Einheit entspricht dem Zeitaufwand zur Erstellung eines durchschnittlichen 3D-Hauses. AutorBeschreibung dient vor allem bei Gemeinschaftsproduktionen der näheren Beschreibung, was genau der Autor zum Objekt beigetragen hat. AutorEmail dient der optionalen Angabe einer Mailadresse des Autors. AutorID steht für eine durch die Firma Hölscher vergebene Autoren-ID. Autor-IDs mit negativen Werten werden an Programme vergeben, die selbstständig ohne großen menschlichen Input Zusi-Inhalte generieren. AutorLizenz muss angegeben werden, wenn der jeweilige Autor eine abweichende Verteilung der ihm zustehenden Einnahmen aus der kommerziellen Nutzung der Zusi-Objekte wünscht. Es gilt: 0 = Einnahmen an den Autor, 1 = Einnahmen auf alle anderen Autoren im Pool verteilen, 2 = Einnahmen gehen an Firma Carsten Hölscher Software, 3 = Objekt ist in der Public Domain (Autor verzichtet auf seine Autorenrechte), 4 = Private nicht zur Veröffentlichung vorgesehene Datei, 5 = Kommerzielle Sondernutzung AutorName ist der Name des Autors. Bei Autoren mit AutorenID der Firma Hölscher muss die genaue Schreibweise des AutorNamens mit Firma Hölscher abgestimmt sein, da dort eine Plausibilitätsprüfung stattfindet (= passt die ID zum Namen?)</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:attribute name="AutorAufwand" type="xs:float"/>
            <xs:attribute name="AutorBeschreibung" type="xs:string"/>
            <xs:attribute name="AutorEmail" type="xs:string"/>
            <xs:attribute name="AutorID" type="xs:int" use="required"/>
            <xs:attribute name="AutorLizenz" default="0"/>
            <!--Datentyp integer enum -->
            <xs:attribute name="AutorName" type="xs:string" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="Signal">
        <xs:complexType>
            <xs:annotation>
                <xs:documentation xml:lang="de">
                    Formal ebenfalls zulässig, in Signalvorlagen aber nicht sinnvoll sind folgende zusätzliche Attribute: BeideRichtungen, NameBetriebsstelle, Signalname, Stellwerk, ZufallsWert
                    BoundingR: Der Boundingradius der 3D-Dateien dieses Signals. Bei zu geringem Boundingradius werden die 3D-Dateien am Bildschirmrand wegploppen. Zu Details siehe Zusi-3-Doku Kapitel 5.1.1.10
                    SigAssiErgaenzen: Ist dieses Attribut auf "1" gesetzt, wird der Signalassistent nur bereits bestehende Matrixzeilen und -spalten mit den Daten dieses Signals vervollständigen, aber nicht (wie bei Attributwert "0") neue Zeilen und Spalten in der Kombinationsmatrix anlegen. Auf Ersatzsignale hat das Attribut keine Auswirkung; stattdessen hat jedes Ersatzsignal ein eigenes Attribut "SigAssiErgaenzen".
                    SigAssiGrundZeile: Wird eingesetzt zusammen mit SigAssiErgaenzen. Die Konfiguration aus der angegebenen Grundzeile wird im Zielsignal in alle Zeilen eingetragen, für die unsere signal.xml keine anderweitige Konfiguration enthält. Damit erspart man sich, jede im Zielsignal denkbare Kombination aus Zeile und Spalte explizit konfigurieren zu müssen. Da Signalzeilen von 0 gezählt werden und Attribute mit Wert "0" beim Schreiben weggelassen werden können, bedeutet das Nichtvorhandensein dieses Attributs, dass die erste Zeile Grundzeile ist.
                    SigAssiKeineGrunddaten: Wird hinter SigAssiRadio benutzt wenn Formulare vor der eigentlichen Positionierung des Signals mit SigAssiPosition benutzt werden.
                    SigAssiKeineKODiff: Wird eingesetzt, wenn das Signal in eine vorhandene Signalmatrix integriert werden soll, aber etwaige durch SigAssiPosition vorgegebene Verschiebungen des Signalstandorts nicht mitmachen soll, sondern auf jeden Fall an den vorgesehenen Koordinaten eingebaut werden soll. Anwendungsfall: Zum Beispiel PZB-Magnete, die unabhängig vom Standort des Hauptsignals (links/rechts vom Gleis) auf jeden Fall an der rechten Schiene positioniert werden sollen.
                    SignalFlags: Codiert binär folgende optionale Funktionen: "Fahrwegsignal wirkt auf beide Fahrtrichtungen", "Fahrwegsignal ist Weichenanimation", "Rangiersignal bei Zugfahrstraße umstellen", "Signal enthält Bahnübergangssteuerung", "Kennlichtschaltung mit Nachfolgesignal", "Kennlichtschaltung mit Vorgängersignal", "Reisendendarstellung".
                    SignalTyp: Definiert die Funktion des Signals. Wird u.a. für korrekte Buchfahrplandarstellung und Befehlsformulare benötigt. Zur Bedeutung der Werte siehe die Tabelle in Zusi-3-Doku 5.3.1.8.2
                    Zwangshelligkeit:
                </xs:documentation>
            </xs:annotation>
            <xs:sequence>
                <xs:annotation>
                    <xs:documentation xml:lang="de">Formal ebenfalls zulässig, in Signalvorlagen aber nicht sinnvoll ist hier das Element KoppelSignal</xs:documentation>
                </xs:annotation>
                <xs:element minOccurs="0" ref="p"/>
                <xs:element minOccurs="0" ref="phi"/>
                <xs:choice>
                    <xs:element ref="SigAssiPosition"/>
                    <xs:choice maxOccurs="unbounded">
                        <xs:annotation>
                            <xs:documentation xml:lang="de">Beim Einlesen akzeptiert Zusis 3D-Editor zwar auch mehr als 64 SignalFrames. Die über 64 hinausgehenden SignalFrames können allerdings im Simulator nicht angesteuert werden (wegen Limitierung des Signalbild-Attributs auf einen 64-Bit-Integer -> 1 Bit pro SignalFrame).</xs:documentation>
                        </xs:annotation>
                        <xs:element ref="MatrixEintrag"/>
                        <xs:element ref="Ersatzsignal"/>
                        <xs:element ref="HsigBegriff"/>
                        <xs:element ref="SigAssiCheck"/>
                        <xs:element ref="SigAssiRadio"/>
                        <xs:element ref="SigAssiText"/>
                        <xs:element ref="SignalFrame" minOccurs="0" maxOccurs="64"/>
                        <xs:element ref="VsigBegriff"/>
                    </xs:choice>
                </xs:choice>
            </xs:sequence>
            <xs:attribute name="BoundingR" type="xs:integer"/>
            <xs:attribute name="SigAssiErgaenzen" type="xs:integer"/>
            <xs:attribute name="SigAssiGrundZeile" type="xs:integer"/>
            <xs:attribute name="SigAssiKeineGrunddaten" type="xs:integer"/>
            <xs:attribute name="SigAssiKeineKODiff" type="xs:integer"/>
            <xs:attribute name="SignalFlags" type="xs:integer"/>
            <xs:attribute name="SignalTyp" type="xs:integer"/>
            <xs:attribute name="Zwangshelligkeit" type="xs:float"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="SigAssiPosition">
        <xs:complexType>
            <xs:sequence>
                <xs:element maxOccurs="unbounded" ref="SigAssiEintrag"/>
            </xs:sequence>
            <xs:attribute name="SigAssiTitel" type="xs:string"/>
            <xs:attribute name="SigAssiVorbelegung" use="required" type="xs:integer"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="Ersatzsignal">
        <xs:complexType>
            <xs:annotation>
                <xs:documentation xml:lang="de">
                    SigAssiErgaenzen: Ist dieses Attribut auf "1" gesetzt, wird der Signalassistent nur ein bereits bestehendes Ersatzsignal mit gleicher ErsatzsigID mit den Daten dieses Eintrags vervollständigen, aber nicht (wie bei Attributwert "0") ein neues Ersatzsignal anlegen, wenn noch keines mit gleicher ErsatzsigID existiert.
                </xs:documentation>
            </xs:annotation>
            <xs:sequence>
                <xs:element ref="MatrixEintrag"/>
            </xs:sequence>
            <xs:attribute name="ErsatzsigBezeichnung" type="xs:string"/>
            <xs:attribute name="ErsatzsigID" type="xs:NMTOKEN"/>
            <xs:attribute name="SigAssiErgaenzen" type="xs:integer"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="HsigBegriff">
        <xs:complexType>
            <xs:attribute name="FahrstrTyp" type="xs:long"/>
            <xs:attribute name="HsigGeschw" type="xs:decimal"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="SigAssiCheck">
        <xs:annotation>
            <xs:documentation xml:lang="de">
                SigAssiCheck: Generiert im Formular des Signalassistenten eine Liste von Ankreuzfeldern. Für jeden Untereintrag wird ein Ankreuzfeld dargestellt. Eine Signaloption kann damit an- und abgewählt werden.
                SigAssiPassiv: Eine Bitmaske, die für jede Checkbox angibt, ob sie deaktiviert ist. Eine deaktivierte Checkbox wird ausgegraut dargestellt. Ihr durch "SigAssiVorbelegung" vorgegebener Zustand kann dadurch vom Streckenbauer nicht geändert werden.
                SigAssiTitel: Hat bei SigAssiCheck anders als bei SigAssiRadio keine Funktion und wird vom 3D-Editor ignoriert.
                SigAssiVorbelegung: Eine Bitmaske, die für jede Checkbox angibt, ob sie standardmäßig angekreuzt ist.
            </xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element maxOccurs="unbounded" ref="SigAssiEintrag"/>
            </xs:sequence>
            <xs:attribute name="SigAssiPassiv" type="xs:integer"/>
            <xs:attribute name="SigAssiTitel" type="xs:string"/>
            <xs:attribute name="SigAssiVorbelegung" type="xs:integer"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="SigAssiRadio">
        <xs:annotation>
            <xs:documentation xml:lang="de">
                SigAssiRadio generiert im Formular des Signalassistenten eine Wahlmöglichkeit mit Radiobuttons (genau eine der angebotenen Optionen muss vom Streckenbauer ausgewählt werden)
                SigAssiPassiv: Die Radiobuttons werden ausgegraut dargestellt. Ihr durch "SigAssiVorbelegung" vorgegebener Zustand kann dadurch vom Streckenbauer nicht geändert werden.
                SigAssiTitel: Definiert die Überschrift über den Radiobuttons.
                SigAssiVorbelegung: Definiert, welcher Radiobutton vorausgewählt ist. Die Zählung beginnt bei 0.
            </xs:documentation>
        </xs:annotation>
        <xs:complexType mixed="true">
            <xs:sequence>
                <xs:element minOccurs="0" maxOccurs="unbounded" ref="SigAssiEintrag"/>
            </xs:sequence>
            <xs:attribute name="SigAssiPassiv" type="xs:integer"/>
            <xs:attribute name="SigAssiTitel" type="xs:string"/>
            <xs:attribute name="SigAssiVorbelegung" type="xs:integer"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="SigAssiText">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="SigAssiEintrag"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="SignalFrame">
        <xs:complexType>
            <xs:annotation>
                <xs:documentation xml:lang="de">Formal ebenfalls zulässig, in Signalvorlagen aber nicht sinnvoll sind folgende zusätzliche Attribute: WeichenbaugruppeIndex, WeichenbaugruppeNr, WeichenbaugruppeBeschreibung, WeichenbaugruppePos0, WeichenbaugruppePos1. Diese sind in diesert xsd nicht definiert, weil sie in signal.xml nicht sinnvoll sind und ihr Vorkommen dort als Fehler anzusehen ist (entsteht, wenn eine signal.xml aus einer Weiche entwickelt wurde)</xs:documentation>
            </xs:annotation>
            <xs:choice maxOccurs="unbounded">
                <xs:element ref="Datei"/>
                <xs:element ref="p"/>
                <xs:element ref="phi"/>
            </xs:choice>
        </xs:complexType>
    </xs:element>
    <xs:element name="VsigBegriff">
        <xs:complexType>
            <xs:attribute name="VsigGeschw" type="xs:decimal"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="p">
        <xs:complexType>
            <xs:attribute name="X" type="xs:decimal"/>
            <xs:attribute name="Y" type="xs:decimal"/>
            <xs:attribute name="Z" type="xs:decimal"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="phi">
        <xs:complexType>
            <xs:attribute name="X" type="xs:decimal"/>
            <xs:attribute name="Y" type="xs:decimal"/>
            <xs:attribute name="Z" type="xs:decimal"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="Datei">
        <xs:complexType>
            <xs:attribute name="Dateiname" use="required"/>
            <xs:attribute name="NurInfo" type="xs:integer"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="MatrixEintrag">
        <xs:complexType>
            <xs:sequence>
                <xs:element minOccurs="0" maxOccurs="unbounded" ref="Ereignis"/>
            </xs:sequence>
            <xs:attribute name="MatrixGeschw" type="xs:decimal"/>
            <xs:attribute name="Signalbild" type="xs:long"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="Ereignis">
        <xs:complexType>
            <xs:attribute name="Beschr" type="xs:string"/>
            <xs:attribute name="Er" type="xs:integer"/>
            <xs:attribute name="Wert" type="xs:decimal"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="SigAssiEintrag">
        <xs:complexType>
            <xs:sequence>
                <xs:element minOccurs="0" ref="SigAssiBild"/>
                <xs:element minOccurs="0" maxOccurs="unbounded" ref="SigAssiDateiEintrag"/>
            </xs:sequence>
            <xs:attribute name="SigAssiBezeichnung"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="SigAssiBild">
        <xs:annotation>
            <xs:documentation xml:lang="de">Das Element SigAssiBild gibt eine bmp-Datei an, die im Signalassistenten als Vorschaubild für den gewählten SigAssiEintrag angezeigt wird. Der Farbwert des Pixels unten links in der Datei wird immer als Transparenzfarbwert interpretiert.</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:attribute name="Dateiname" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="SigAssiDateiEintrag">
        <xs:complexType>
            <xs:sequence>
                <xs:element minOccurs="0" ref="Datei"/>
                <xs:element minOccurs="0" ref="p"/>
                <xs:element minOccurs="0" ref="phi"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>