如何记录XML文件的结构

时间：2009-11-17 23:23:22

标签： xsd xml-documentation

说到记录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工具进行更新？

6 个答案:

答案 0 :(得分：37)

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

有关XML Schema的介绍，请参阅XML Schools tutorial。

以下是您的示例，表示为带有xs:annotation标记的XML架构：

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

答案 1 :(得分：5)

享受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注释，而不是文档元素。

  • 多个连续注释（如示例中所示）将变为单个元素中的单个多行文档字符串。

  • 显而易见的事实：doc.xml中的内联XML注释无关紧要，只有schema.rnc计数中的内容。

如果需要XML Schema 1.0，请生成它（schema.xsd）

假设您有一个名为trang的（开源）工具，您可以按如下方式创建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限制

  • 多重性只能是＆＃34;零或一个＆＃34;，＆＃34;只有一个＆＃34;，＆＃34;零个或多个＆＃34;或者＆＃34;一个或多个＆＃34;。 （少数元素的多重性可以通过＆＃34;愚蠢的重复＆＃34;＆＃34;零或一个＆＃34;定义来描述）
  • 有XML Schema 1.0构造，RELAX NG无法描述。

结论

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

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

答案 2 :(得分：4)

您可以尝试通过创建XSD架构来记录它，该架构可以提供更正式的XML规范。许多工具将以样本XML为起点为您生成XSD。

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

答案 3 :(得分：2)

就个人而言，我更希望在XML中看到它（第二种方式）。

将元素放在表格中并不能清楚地告诉您哪些元素是哪些元素的父元素等等。将它放在XML中更加清晰，我可以看到发生了什么。

答案 4 :(得分：2)

在表格中显示它有其限制，例如mulit级别的嵌套子级，但对于一个简单的XML结构，我认为这很好。对于任何具有多个嵌套级别的东西，我更喜欢XML方式。

更好的方法是创建XML Schema（XSD）文件。这样，您就可以在XML中看到它，并且可以在使用某些软件对模式文件输入数据后检查文件。

有关XSD的一系列精彩教程，请查看w3schools - XML Schema Tutorial

答案 5 :(得分：0)

我只想添加一件事，以防有人发现它有用。我有时用 HTML 编程，有时用 android 编程。当我做HTML时，我按照与W3Schools格式相同的格式记录我的自定义XML，如http://www.w3schools.com/tags/att_a_href.asp中那样，如果它是我正在处理的Android项目，那么我遵循http://developer.android.com/guide/topics/manifest/activity-element.html#screen中的Google标准。 这样，我合作的程序员不需要做任何额外的工作来理解我的文档。

相关问题
最新问题