So dokumentieren Sie die Struktur von XML-Dateien

Genießen Sie die RELAX NG - Kompaktsyntax

Beim Experimentieren mit verschiedenen XML-Schemasprachen habe ich festgestellt, dass RELAX NG für die meisten Fälle am besten geeignet ist (Argumentation am Ende).

Bedarf

• Dokumentieren Sie die XML-Dokumentstruktur
• Tun Sie es in lesbarer Form
• Halten Sie es für den Autor einfach

Geändertes Beispiel-XML (doc.xml)

Ich habe ein Attribut hinzugefügt, um auch diese Art von Struktur in der Dokumentation darzustellen.

<objectRoot created="2015-05-06T20:46:56+02:00">
    <v>
        <!-- Current version of the object from the repository. !-->
        <!-- (Occurance: 1) -->
    </v>
    <label>
        <!-- Name of the object from the repository. !-->
        <!-- (Occurance: 0 or 1 or Many) -->
    </label>
</objectRoot>

Verwenden Sie RELAX NG Kompakte Syntax mit Kommentaren (schema.rnc)

RELAX NG ermöglicht die Beschreibung der XML-Beispielstruktur auf folgende Weise:

start =

## Container for one object
element objectRoot {

    ## datetime of object creation
    attribute created { xsd:dateTime },

    ## Current version of the object from the repository
    ## Occurrence 1 is assumed by default
    element v {
        text
    },

    ## Name of the object from the repository
    ## Note: the occurrence is denoted by the "*" and means 0 or more
    element label {
        text
    }*
}

Ich denke, es ist sehr schwer, die Einfachheit zu übertreffen, indem man das gegebene Maß an Ausdruckskraft behält.

Wie kommentiere ich die Struktur?

• platziere immer den Kommentar vor relevantes Element, nicht danach.
• verwenden Sie zur besseren Lesbarkeit eine Leerzeile vor dem Kommentarblock
• verwenden Sie das Präfix ##, das automatisch in ein Dokumentationselement in einem anderen Schemaformat übersetzt wird. Ein einzelner Hashcode # wird in einen XML-Kommentar und nicht in ein Dokumentationselement übersetzt.

• mehrere aufeinanderfolgende Kommentare (wie im Beispiel) werden in eine einzelne mehrzeilige Dokumentationszeichenfolge innerhalb eines einzelnen Elements umgewandelt.

• offensichtliche Tatsache: Die Inline-XML-Kommentare in doc.xml sind irrelevant, nur das, was in schema.rnc steht, zählt.

Wenn XML Schema 1.0 erforderlich ist, generieren Sie es (schema.xsd)

Vorausgesetzt, Sie haben ein (Open Source) Tool namens trang zur Verfügung, können Sie eine XML-Schemadatei wie folgt erstellen:

$ trang schema.rnc schema.xsd

Das resultierende Schema sieht folgendermaßen aus:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="objectRoot">
    <xs:annotation>
      <xs:documentation>Container for one object</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="v"/>
        <xs:element minOccurs="0" maxOccurs="unbounded" ref="label"/>
      </xs:sequence>
      <xs:attribute name="created" use="required" type="xs:dateTime">
        <xs:annotation>
          <xs:documentation>datetime of object creation</xs:documentation>
        </xs:annotation>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
  <xs:element name="v" type="xs:string">
    <xs:annotation>
      <xs:documentation>Current version of the object from the repository
Occurance 1 is assumed by default</xs:documentation>
    </xs:annotation>
  </xs:element>
  <xs:element name="label" type="xs:string">
    <xs:annotation>
      <xs:documentation>Name of the object from the repository
Note: the occurance is denoted by the "*" and means 0 or more</xs:documentation>
    </xs:annotation>
  </xs:element>
</xs:schema>

Jetzt können Ihre Kunden, die darauf bestehen, nur XML Schema 1.0 zu verwenden, Ihre XML-Dokumentspezifikation verwenden.

Validierung von doc.xml gegen schema.rnc

Es gibt Open-Source-Tools wie jing und rnv, die die RELAX NG Compact-Syntax unterstützen und sowohl unter Linux als auch unter MS Windows arbeiten.

Hinweis: Diese Tools sind ziemlich alt, aber sehr stabil. Lesen Sie es als Zeichen der Stabilität und nicht als Zeichen der Veraltetheit.

Mit jing:

$ jing -c schema.rnc doc.xml

Der -c ist wichtig, jing setzt standardmäßig RELAX NG in XML-Form voraus.

Wenn Sie rnv zur Überprüfung verwenden, ist der schema.rnc selbst gültig:

$ rnv -c schema.rnc

und doc.xml zu bestätigen:

$ rnv schema.rnc doc.xml

rnv ermöglicht die gleichzeitige Überprüfung mehrerer Dokumente:

$ rnv schema.rnc doc.xml otherdoc.xml anotherone.xml

RELAX NG Kompakte Syntax - Profis

• sehr gut lesbar, auch Neulinge sollten den Text verstehen
• leicht zu erlernen (RELAX NG kommt mit gutem Tutorial, man kann das meiste innerhalb eines Tages lernen)
• sehr flexibel (trotz der Tatsache, dass es einfach aussieht, deckt es viele Situationen ab, einige davon können mit XML Schema 1.0 nicht gelöst werden).
• es gibt einige Tools zum Konvertieren in andere Formate (RELAX NG XML-Formular, XML Schema 1.0, DTD, aber auch die Generierung von XML-Beispieldokumenten).

RELAX NG Einschränkungen

• multiplizität kann nur "null oder eins", "nur eins", "null oder mehr" oder "eins oder mehr" sein. (Die Vielzahl kleiner Elemente kann durch "dumme Wiederholung" von "Null oder Eins" -Definitionen beschrieben werden.)
• Es gibt XML Schema 1.0-Konstrukte, die von RELAX NG nicht beschrieben werden können.

Schlussfolgerungen

Für die oben definierte Anforderung sieht die Syntax von RELAX NG Compact am besten aus. Mit RELAX NG erhalten Sie ein vom Menschen lesbares Schema, das sogar für die automatisierte Validierung verwendet werden kann.

Bestehende Einschränkungen treten nicht oft in Kraft und können in vielen Fällen durch Kommentare oder andere Maßnahmen gelöst werden.

Sie können versuchen, dies zu dokumentieren, indem Sie ein XSD-Schema erstellen, das eine formellere Spezifikation Ihres XML bietet. Viele Tools generieren die XSD für Sie aus einem Beispiel-XML als Ausgangspunkt.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="objectroot">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="v" minOccurs="1" type="xs:string"/> <!-- current version -->
      <xs:element name="label" type="xs:string"/> <!-- object name -->
    </xs:sequence>
  </xs:complexType>
</xs:element>
</xs:schema>

Ich persönlich würde es lieber in XML sehen (der 2. Weg).

Wenn Sie die Elemente in die Tabelle einfügen, können Sie nicht eindeutig erkennen, welche Elemente das übergeordnete untergeordnete Element der Elemente usw. sind. Das Einfügen in XML ist etwas klarer und ich kann sehen, was los ist.

Wenn Sie es in einer Tabelle anzeigen, hat es Einschränkungen, z. Mehrere Ebenen verschachtelter Kinder, aber für eine einfache XML-Struktur wäre dies in Ordnung. Für alles mit mehr als einer verschachtelten Ebene würde ich den XML-Weg bevorzugen.

Ein noch besserer Weg wäre das Erstellen einer XML-Schema-Datei (XSD-Datei). Auf diese Weise erhalten Sie die Vorteile, die Sie in XML sehen, und Sie können die Datei überprüfen, nachdem die Daten mit der Schemadatei eingegeben wurden. Verwenden Sie dazu eine Software.

Eine ganze Reihe von Tutorials zu XSD finden Sie unter w3schools - XML ​​Schema Tutorial

Ich möchte nur noch etwas hinzufügen, falls jemand es für nützlich hält.
Ich programmiere manchmal in HTML und andere Zeiten in Android. Wenn ich HTML verwende, dokumentiere ich mein benutzerdefiniertes XML mit demselben Format wie W3Schools, wie in http://www.w3schools.com/tags/att_a_href.asp wenn es sich um ein Android-Projekt handelt, an dem ich arbeite, folge ich Google-Standards wie in http://developer.Android.com/guide/topics/manifest/activity-element.html#screen
Auf diese Weise müssen die Programmierer, mit denen ich arbeite, keine zusätzlichen Arbeiten ausführen, um meine Dokumentation zu verstehen.