xsd - tutorial - xml structure

Cómo documentar la estructura de archivos XML

Question

Cuando se trata de documentar la estructura de archivos XML ...

Uno de mis compañeros lo hace en una tabla de Word.

Otro pega los elementos en un documento de Word con comentarios como este:

<learningobject id="{Learning Object Id (same value as the loid tag)}" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                xsi:noNamespaceSchemaLocation="http://www.aicpcu.org/schemas/cms_lo.xsd">




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

¿Cuál de estos métodos es el preferido? ¿Hay alguna manera mejor?

¿Hay otras opciones que no requieren herramientas de Documentador de esquemas de terceros para actualizar?

Answer 1

Disfruta de la sintaxis compacta de RELAX NG.

Experimentando con varios lenguajes de esquema XML, he encontrado que RELAX NG es la mejor opción para la mayoría de los casos (razonamiento al final).

Requerimientos

• Permitir documentar la estructura del documento XML
• Hacerlo en forma legible
• Mantenlo simple para el autor.

Muestra XML modificada (doc.xml)

He añadido un atributo, para ilustrar también este tipo de estructura en la documentación.

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

Use la sintaxis de RELAX NG Compact con comentarios (schema.rnc)

RELAX NG permite describir una estructura XML de muestra de la siguiente manera:

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

Creo que es muy difícil superar la simplicidad, manteniendo un nivel dado de expresividad.

Cómo comentar la estructura.

• Siempre coloque el comentario antes del elemento relevante, no después de él.
• para facilitar la lectura, use una línea en blanco antes del bloque de comentarios
• use el prefijo ## , que se traduce automáticamente en un elemento de documentación en otro formato de esquema. El # solo hash se traduce en comentario XML y no en un elemento de documentación.

• múltiples comentarios consecutivos (como en el ejemplo) se convertirán en una sola cadena de documentación multilínea dentro de un solo elemento.

• hecho obvio: los comentarios XML en línea en doc.xml son irrelevantes, solo lo que está en el schema.rnc cuenta.

Si se requiere XML Schema 1.0, genérelo (schema.xsd)

Suponiendo que tiene una herramienta (de código abierto) llamada trang disponible, puede crear un archivo de esquema XML de la siguiente manera:

$ trang schema.rnc schema.xsd

El esquema resultante se ve así:

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

Ahora pueden sus clientes, insistiendo en usar solo XML Schema 1.0 usar su especificación de documento XML.

Validando doc.xml contra schema.rnc

Existen herramientas de código abierto como jing y rnv admiten la sintaxis de RELAX NG Compact y que funcionan tanto en Linux como en MS Windows.

Nota: esas herramientas son bastante antiguas, pero muy estables. Léalo como un signo de estabilidad, no como un signo de ser obsoleto.

Utilizando jing:

$ jing -c schema.rnc doc.xml

La -c es importante, jing por defecto asume RELAX NG en forma XML.

Usando rnv para verificar, el schema.rnc sí es válido:

$ rnv -c schema.rnc

y para validar doc.xml :

$ rnv schema.rnc doc.xml

rnv permite validar múltiples documentos a la vez:

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

Sintaxis de RELAX NG Compact - pros

• muy legible, incluso novato debe entender el texto
• fácil de aprender (RELAX NG viene con un buen tutorial, uno puede aprender la mayor parte dentro de un día)
• muy flexible (a pesar del hecho, parece simple, cubre muchas situaciones, algunas de ellas ni siquiera pueden resolverse con XML Schema 1.0).
• existen algunas herramientas para convertir a otros formatos (formulario XML RELAX NG, XML Schema 1.0, DTD, pero incluso generación de documentos XML de muestra).

Limitaciones de RELAX NG

• la multiplicidad puede ser solo "cero o uno", "solo uno", "cero o más" o "uno o más". (La multiplicidad de un pequeño número de elementos se puede describir mediante la "repetición estúpida" de las definiciones de "cero o uno")
• Hay construcciones de XML Schema 1.0, que no pueden ser descritas por RELAX NG.

Conclusiones

Para el requisito definido anteriormente, la sintaxis de RELAX NG Compact parece el mejor ajuste. Con RELAX NG usted obtiene ambos: un esquema legible por humanos que puede usarse incluso para la validación automatizada.

Las limitaciones existentes no entran en vigencia con mucha frecuencia y, en muchos casos, pueden resolverse mediante comentarios u otros medios.

Answer 2

Escribiría un archivo de esquema XML (XSD) para definir la estructura del documento XML. Se pueden incluir etiquetas xs:annotation y xs:documentation para describir los elementos. El archivo XSD se puede transformar en documentación utilizando hojas de estilo XSLT como xs3p o herramientas como XML Schema Documenter .

Para una introducción al esquema XML, vea el tutorial de Escuelas XML .

Aquí está su ejemplo, expresado como esquema XML con xs:annotation etiquetas de xs:annotation :

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="objectroot">
    <xs:complexType>
      <xs:sequence>

        <xs:element name="v" type="xs:string">
          <xs:annotation>
            <xs:documentation>Current version of the object from the repository.</xs:documentation>
          </xs:annotation>
        </xs:element>

        <xs:element name="label" minOccurs="0" maxOccurs="unbounded" type="xs:string">
          <xs:annotation>
            <xs:documentation>Name of the object from the repository.</xs:documentation>
          </xs:annotation>
        </xs:element>

      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Answer 3

Mostrarlo en una tabla tiene sus limitaciones, por ejemplo, niveles múltiples de niños anidados, pero para una estructura XML simple, creo que esto estaría bien. Para cualquier cosa con más de un nivel anidado preferiría la forma XML.

Una forma aún mejor sería crear un archivo de esquema XML (XSD). De esa manera, obtiene los beneficios de verlo en XML y puede verificar el archivo después de que los datos se ingresen en el archivo de esquema utilizando algún software.

Para obtener una gran serie de tutoriales sobre XSD, visite w3schools - Tutorial de esquema XML

Answer 4

Personalmente, preferiría verlo en XML (la segunda forma).

Poner los elementos en la tabla no le dirá claramente qué elementos son los elementos del elemento secundario del padre, etc. Ponerlo en XML es bastante claro y puedo ver lo que está pasando.

Answer 5

Puede intentar documentarlo creando un esquema XSD que proporcione una especificación más formal de su XML. Muchas herramientas generarán el XSD desde XML de muestra como punto de partida.

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

Answer 6

Solo quiero agregar una cosa más, en caso de que alguien lo encuentre útil.
A veces programo en HTML y otras veces en Android . Cuando hago HTML, documento mi XML personalizado siguiendo el mismo formato que W3Schools, como en http://www.w3schools.com/tags/att_a_href.asp Si estoy trabajando en un proyecto de Android, sigo los estándares de Google y http://developer.android.com/guide/topics/manifest/activity-element.html#screen
De esta manera, los programadores con los que trabajo no tienen que hacer ningún trabajo adicional para comprender mi documentación.