如何记录XML文件的结构

Question

在记录XML文件的结构时......

我的一位同事在Word表格中做到了这一点.

另一个将元素粘贴到Word文档中,其中包含以下注释:

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

哪种方法更受青睐？有没有更好的办法？

是否有其他选项不需要第三方Schema Documenter工具进行更新？

Answer 1

我编写了一个XML Schema(XSD)文件来定义XML文档的结构.可以包含标签xs:annotation和xs:documentation标签来描述元素.可以使用XSLT样式表(如xs3p)或XML Schema Documenter等工具将XSD文件转换为文档.

有关XML Schema的介绍,请参阅XML Schools教程.

这是您的示例,表示为带有xs:annotation标记的XML Schema :

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

享受RELAX NG紧凑语法

尝试使用各种XML模式语言,我发现RELAX NG最适合大多数情况(最后的推理).

要求

• 允许记录XML文档结构
• 以可读的形式做
• 为作者保持简单

修改后的示例XML(doc.xml)

我添加了一个属性,以说明文档中的这种类型的结构.

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

使用RELAX NG Compact语法和注释(schema.rnc)

RELAX NG允许以下列方式描述示例XML结构:

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

我认为,很难击败简单性,保持给定的表达水平.

如何评论结构

• 始终将评论放在相关元素之前,而不是之后.
• 为了便于阅读,请在注释块之前使用一个空行
• 使用##前缀,它自动转换为其他模式格式的文档元素.单个哈希#转换为XML注释,而不是文档元素.

• 多个连续注释(如示例中所示)将变为单个元素内的单个多行文档字符串.

• 显而易见的事实:内联XML注释doc.xml是无关紧要的,只有schema.rnc计数内容.

如果需要XML Schema 1.0,请生成它(schema.xsd)

假设您有一个名为trangavailable 的(开源)工具,您可以创建一个XML Schema文件,如下所示:

$ trang schema.rnc schema.xsd

结果模式如下所示:

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

现在,坚持仅使用XML Schema 1.0的客户可以使用您的XML文档规范.

根据schema.rnc验证doc.xml

有开源工具jing,rnv支持RELAX NG Compact语法,可以在Linux和MS Windows上运行.

注意:这些工具相当陈旧,但非常稳定.阅读它作为稳定的标志,而不是过时的迹象.

使用jing:

$ jing -c schema.rnc doc.xml

这-c很重要,jing默认情况下采用XML形式的RELAX NG.

使用rnv来检查时,schema.rnc本身是有效的:

$ rnv -c schema.rnc

并验证doc.xml:

$ rnv schema.rnc doc.xml

rnv 允许一次验证多个文档:

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

RELAX NG Compact语法 - 专业

• 非常可读,甚至新手应该理解文本
• 易于学习(RELAX NG带有很好的教程,人们可以在一天内学到大部分内容)
• 非常灵活(尽管事实上,它看起来很简单,它涵盖了许多情况,其中一些甚至无法通过XML Schema 1.0解决).
• 存在一些用于转换为其他格式的工具(RELAX NG XML形式,XML Schema 1.0,DTD,甚至生成示例XML文档).

RELAX NG限制

• 多重性可以仅为"零或一","仅一个","零或更多"或"一个或多个".(少数元素的多重性可以通过"零或一个"定义的"愚蠢重复"来描述)
• 有一些XML Schema 1.0构造,RELAX NG无法描述.

结论

对于上面定义的要求,RELAX NG Compact语法看起来最合适.使用RELAX NG,您可以获得两者 - 人类可读的模式,甚至可用于自动验证.

现有限制不会经常生效,并且在许多情况下可以通过评论或其他方式解决.