Small inconsistency in Internal Data Structure

jloehel commented 6 years ago

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

According to your documentation, the internal data structure looks like this:

<documentation>
  <element name="profiles">
    <namespace/>
    <description>Creates Namespace Section for Drivers</description>
    <child id="profile"/>
  </element>
  <element name="users">
    <namespace/>
    <description>A List of Users</description>
    <child id="user"/>
    <attribute>
      <name>group</name>
      <namespace/>
      <description>Contains the group to which the user belongs</description>
      <type>
        <description/>
        <param/>
      </type>
      <use>required</use>
    </attribute>
    <!-- ... -->
  </element>
  <!-- ... --->
</documentation>

Three inconsistencies:

The name of the element is written as <element name="...">. However, the attribute name is written as <attribute><name>. Could this be made consistent? Such as <attribute name="...">.
The <use> element contains probably the values "required" or "optional". Is that assumption correct? In that case, you could move this information like this: <attribute name="..." required="yes|no"> By default, "no" is the default value.
The id attribute from <child id="profile"/> refers to another element. As such, shouldn't it be named "ref" or something similar?

It could help to make XPaths a bit easier. :grin:

Furthermore, it may help to formalize the structure if we would have a RELAX NG grammar. Some questions:

The document structure should have a version attribute in its root element; this way, we can identify any compatibility issues
Should the <namespace/> element be optional?
Should the <description> element be optional?
Should the natural language of some description be preserved in the <description> element? Maybe as <description xml:lang="en">?
Should the id attribute in <element> be xml:id?

jloehel commented 6 years ago

Original comment by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

Hallo Jürgen,

ich habe im Branch rng_schema. Damit angefangen ein Schema für das Zwischenformat zu erstellen:

Cool, dann hatten wir die selbe Idee. ;-)) Vielleicht können wir das unsere beiden Erkenntnisse zusammenführen.

Die Änderungen klingen für mich plausibel.

Das ist schön. :-)

Ich bin mir nachwievor noch nicht ganz im Klaren, was ein gute XML-Struktur ausmacht und worauf ich achten muss, daher sind Vorschläge sehr willkommen.

Eine gute XML-Struktur zu entwerfen kann manchmal schwierig werden.

Woran ich mich orientiere sind meist folgende Punkte:

Attribut vs. Element?

Das war (früher?) immer ein großes Streitthema. Hing vermutlich mit der DTD zusammen, die nur in Attributen rudimentäre Datentypen erlaubt, in Elementen jedoch nicht. Mittlerweile ist es durch XSD und RNG nicht mehr so wichtig. Sind manche Informationen optional?
Maschine vs. Mensch?

Manche machen einen Unterschied ob die XML-Struktur nur von Maschinen gelesen wird oder ob sie auch ein Mensch zu Gesicht bekommt. Ich denke trotzdem, irgendein Entwickler wird die Struktur dennoch lesen (müssen) um sinnvolle Verarbeitungen machen zu können.
Dokumentation vs. Markup?

Eine XML-Struktur sollte möglichst so sprechende Namen haben, dass man den Sinn, Zweck und Inhalt erraten kann. Ohne irgendeine Referenz-Dokumentation gelesen zu haben. Das wäre der Idealfall, der aber sicherlich leider nicht immer möglich ist. Trotzdem kann man durch sinnvolle Benennung bereits viele Mehrdeutigkeiten und Ungenauigkeiten ausschließen.
Konsistenz und Wiederverwertung

Kommen bestimmte Strukturen in anderen vor? In dem Fall kann man Dinge wiederverwerten. Das verhindert eine ausufernde Anzahl von Tags und man kann sich die Dinge auch besser merken. Des Weiteren ist es natürlich besser, wenn gleiches auch gleich benannt wird.
Explizites Markup vs. Implizites Markup

Bevor man seine Namen entwirft, sollte man sich überlegen was man auszeichnen möchte. Soll z.B. eine Konto-Transaktion dargestellt werden, dann wäre ein erster Entwurf sowas: <transaction>withdrawal 2018 02 15 200.00 </transaction>.

Das enthält noch sehr viel implizite Daten: der Typ der Transaktion, das Datum und der Wert. So eine Struktur lässt sich schlecht parsen, sortieren, vergleichen usw. Besser -- da leichter zugänglich -- wäre so eine:

<transaction type="withdrawal">
   <date>2018-02-15</date>
   <amount>200.00</amount>
</transaction>

Das soll erstmal nur eine kleine Inspiration sein. Ich habe von Elliotte Rusty Harold das Buch "Effective XML" (50 Specific Ways to Improve Your XML). Das kann ich nächste Woche gerne mitbringen.

jloehel commented 6 years ago

Hallo Thomas,

ich habe im Branch rng_schema. Damit angefangen ein Schema für das Zwischenformat zu erstellen: https://bitbucket.org/jloehel/rng2doc/src/72e9ae9d93d14f7b0b5e163197c760684e4f47e2/?at=feature%2Frng_schema

Die Änderungen klingen für mich plausibel. Ich bin mir nachwievor noch nicht ganz im Klaren, was ein gute XML-Struktur ausmacht und worauf ich achten muss, daher sind Vorschläge sehr willkommen.

jloehel commented 6 years ago

Original comment by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

See commit bc51215 in branch "feature/issue17-datastructure" for an idea about how the formalized structure of the RNG could look like.

openSUSE / rng2doc

Small inconsistency in Internal Data Structure #17