28

在记录 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 工具进行更新?

4

6 回答 6

44

我会编写一个 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>
于 2009-11-17T23:34:20.327 回答
6

享受 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 注释而不是文档元素。
  • 多个连续的注释(如示例中所示)将在单个元素中变成单个多行文档字符串。

  • 显而易见的事实:inline XML 注释doc.xml无关紧要,只有 in 才schema.rnc重要。

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

假设您有一个名为 available 的(开源)工具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

有一些开源工具,例如jingrnv支持 RELAX NG Compact 语法,并且可以在 Linux 和 MS Windows 上运行。

注意:这些工具相当陈旧,但非常稳定。将其视为稳定的标志,而不是过时的标志。

使用精:

$ jing -c schema.rnc doc.xml

-c重要的是,jing默认情况下假定 RELAX NG 采用 XML 格式。

使用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,您可以同时获得 - 人类可读的模式,甚至可用于自动验证。

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

于 2015-05-06T19:54:50.347 回答
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>
于 2009-11-17T23:33:33.350 回答
2

就个人而言,我更喜欢在 XML 中看到它(第二种方式)。

将元素放在表格中不会清楚地告诉您哪些元素是哪些元素的父子元素等等。把它放在 XML 中会更清楚,我可以看到发生了什么。

于 2009-11-17T23:26:43.170 回答
2

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

一个更好的方法是创建一个 XML Schema (XSD) 文件。这样,您就可以在 XML 中看到它的好处,并且您可以在输入数据后使用一些软件对照模式文件检查文件。

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

于 2009-11-17T23:34:08.560 回答
0

我只想再添加一件事,以防有人发现它有用。
我有时用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
这样与我一起工作的程序员不必做任何额外的工作来理解我的文档。

于 2015-06-29T06:09:57.163 回答