Comment décrire la structure des fichiers XML

Profiter de RELAX NG compact syntaxe

Expérimenter avec différents langages de schéma XML, j'ai trouvé RELAX NG le meilleur ajustement pour la plupart des cas (raisonnement à la fin).

Exigences

• Permettent de documenter la structure du document XML
• Le faire sous une forme lisible
• Garder les choses simples pour l'auteur

Modifié échantillon XML (doc.xml)

J'ai ajouté un attribut, pour illustrer aussi ce type de structure dans la documentation.

<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>

Utilisation RELAX NG Compact syntaxe avec des commentaires (schéma.rnc)

RELAX NG permet de décrire l'échantillon de la structure XML de la manière suivante:

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
    }*
}

Je pense que c'est très dur à battre la simplicité, de la maintenir à un niveau donné de l'expressivité.

Comment commenter la structure

• toujours placer le commentaire avant élément pertinent, pas après.
• pour des raisons de lisibilité, utilisez une ligne vide avant le bloc de commentaire
• utilisation ## préfixe, qui est automatiquement traduit dans la documentation de l'élément dans d'autres format de schéma. De hachage unique # se traduit par de commentaire XML et non pas une documentation élément.

• plusieurs commentaires consécutifs (comme dans l'exemple) va se transformer en multi-ligne de chaîne de documentation au sein d'un seul élément.

• un fait évident: la ligne des commentaires XML dans doc.xml sont hors de propos, seulement ce qui est dans schema.rnc compte.

Si XML Schema 1.0 est nécessaire, il génère (schéma.xsd)

En supposant que vous avez un (open source), l'outil d' trang disponibles, vous pouvez créer un fichier de Schéma XML comme suit:

$ trang schema.rnc schema.xsd

Schéma résultant ressemble à ceci:

<?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>

Peut maintenant vos clients, en insistant sur l'utilisation de XML Schema 1.0 utilisez votre document XML spécification.

Validation doc.xml à l'encontre du schéma.rnc

Il y a des outils open source tels que jing et rnv soutenir RELAX NG Compact de la syntaxe et de travail sur Linux ainsi que sur MS Windows.

Remarque: ces outils sont un peu vieux, mais très stable. Le lire comme un signe de stabilité non pas comme signe d'être obsolète.

À l'aide de jing:

$ jing -c schema.rnc doc.xml

La -c est important, jing par défaut suppose RELAX NG en forme XML.

À l'aide de rnv de vérifier, la schema.rnc lui-même est valide:

$ rnv -c schema.rnc

et de valider doc.xml:

$ rnv schema.rnc doc.xml

rnv permet de valider plusieurs documents à la fois:

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

RELAX NG Compact syntax - pros

• très lisible, même débutant devrait comprendre le texte
• facile à apprendre (RELAX NG est livré avec bon tutoriel, on peut en savoir plus en moins d'un jour)
• très souple (malgré le fait, il semble simple, il couvre de nombreuses situation, certains d'entre eux ne sont pas encore résolus par le Schéma XML 1.0).
• des outils pour la conversion dans d'autres formats (XML RELAX NG forme, XML Schema 1.0, DTD, mais même de la génération du document XML exemple) existe.

RELAX NG limitations

• multiplicité peut être seulement "zéro ou un", "un", "zéro ou plus" ou "un ou plusieurs". (La multiplicité des petit nombre d'éléments peut être décrit par "stupide répétition" de zéro "ou un" définitions)
• Il y a de Schéma XML 1.0 constructions, qui ne peut être décrite par RELAX NG.

Conclusions

De l'exigence définie ci-dessus, RELAX NG Compact syntaxe ressemble le meilleur ajustement. RELAX NG, vous obtenez à la fois - lisible par l'homme de schéma qui est encore utilisable pour la validation automatique.

Les limitations existantes ne viennent pas en effet très souvent, et peut être dans de nombreux cas résolus par commentaires ou par d'autres moyens.

Personnellement, je préfère la voir en XML (le 2ème).

De mettre les éléments dans le tableau ne vais pas vous dire clairement quels sont les éléments qui éléments " parent-enfant et ainsi de suite. Mettre en XML est plutôt clair et je peux voir ce qu'il se passe.

Je veux juste ajouter une chose de plus, dans le cas où quelqu'un le trouve utile.
Je fais parfois de la programmation dans HTML et d'autres fois dans android. Quand je fais du HTML, j'ai mon document XML personnalisé suivant le même format que W3Schools, comme dans http://www.w3schools.com/tags/att_a_href.asp si c'est un projet android, je suis en train de travailler sur puis-je suivre Google normes en http://developer.android.com/guide/topics/manifest/activity-element.html#screen

De cette façon, les programmeurs, je travaille avec ne pas avoir à faire aucun travail supplémentaire pour comprendre ma documentation.