如何记录 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>

首选哪种方法？有更好的办法吗？

是否有其他选项不需要第三方架构文档工具来更新？

Answer 1

我将编写一个 XML 架构 (XSD) 文件来定义 XML 文档的结构。可以包含 xs:annotation 和 xs:documentation 标签来描述元素。可以使用 XSLT 样式表（例如 xs3p 或工具（例如 XML 架构文档管理器。

有关 XML 架构的介绍，请参阅 XML Schools 教程。

这是您的示例，表示为带有 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>

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 紧凑语法 (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 语法紧凑 - 优点

• 是非常易读，即使是新手也应该​​理解文本
• 易于学习（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，您可以获得两种 - 人类可读的模式，甚至可用于自动验证。

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

Answer 3

您可以尝试通过创建 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>

Answer 4

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

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

Answer 5

在表中显示它有其局限性，例如多层嵌套子项，但对于简单的 XML 结构，我认为这会很好。对于任何具有多个嵌套级别的内容，我更喜欢 XML 方式。

更好的方法是创建 XML 架构 (XSD) 文件。这样，您就可以获得在 XML 中查看它的好处，并且可以在使用某些软件根据架构文件输入数据后检查该文件。

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

Answer 6

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