如何记录XML文件的结构

29

在记录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>

这些方法中哪一个更受青睐?有更好的方式吗?

是否有其他选项可以更新而不需要使用第三方模式文档工具?

6个回答

44
我会编写一个XML Schema(XSD)文件来定义XML文档的结构。可以包括xs:annotationxs: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>

干得好,Phil,干得好;) - Adam Harte
好主意。虽然我有点担心我的文档永远不会得到更新,因为现在有人需要另一个工具来更新它。 - joe
2
@joe:一种选择是直接使用<schema>文件作为文档——好处是你可以使用标准工具来生成进一步的文档;并且使用XSD来检查(validate)XML和与其他可能需要了解你的格式的方当交换。因为这是一个标准,学会使用它成为你在其他任务/雇主中宝贵的技能——同样,它也是就业市场中常见的技能,因此可以找到替代者。不幸的是,它是一种令人困惑的标准,比你提到的任何一个都难以阅读和编写。 - 13ren
@13ren:是的,XSD文件结构很难阅读,这真是不幸。我觉得把它当做“文档”来传递是不太合适的。如果有一个可以以用户友好界面打开XSD文件的工具就好了(与只生成只读文件供查看的工具相反)。甚至一个生成Word文档格式的文档工具也会很不错。 - joe
@joe:它可能符合或不符合您对用户友好性的概念,但允许XSD模式文档在Web浏览器中显示的一种工具是W3C网站上的xsd.xsl样式表。它不隐藏XSD语法或将其转换为更易读的形式,但它可以很好地显示XHTML编码的文档元素,并将同一模式文档中定义的其他组件的引用转换为超链接(在任何非Mozilla浏览器中)。 - C. M. Sperberg-McQueen

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

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

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

使用jing:

$ 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简洁语法 - 优点

  • 易读,即使新手也应该理解文本
  • 易学 (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简洁语法似乎是最合适的选择。使用RELAX NG可以得到既适用于自动验证又易于阅读的模式。

现有的限制并不经常出现,并且在许多情况下可以通过注释或其他方式解决。


1
这个回答读起来像是一个针对RELAX NG的推广广告,占用了比其他回答多得多的空间(紧凑语法算什么),而且还必须通过xsd模式。简而言之,它掩盖了其他更好的回答。 - M.H.
@M.H. RELAX NG紧凑语法(RNC)根本不需要您生成XSD。与接受的答案中的XSD相比,RNC具有相同数量的行和更少的字符。 - Jan Vlcinsky

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>

好主意。虽然我有点担心我的文档永远不会被更新,因为现在需要另一个工具来更新它。 - joe
@joe:你不需要工具来维护它。你可以使用类似XmlSpy的工具从XML实例文档中生成XSD,然后你可以使用记事本来维护它,因为它们只是文本文档。 - zac
1
@zac:如果你考虑整个过程,就会知道需要这样做。(1)有人阅读文档。(2)发现需要更改。(3)返回xsd源代码。(4)更新xsd源代码。(5)查找工具,如XmlSpy,重新生成文档。使用另一个工具是一种负担,限制了这种文档形式的使用。 - joe

2

就个人而言,我更喜欢以XML格式呈现(第二种方式)。

将元素放入表格中无法清楚地告诉您哪些元素是哪些元素的父母子女等关系。将其放入XML中则更加清晰,我可以看到发生了什么。


2
在表格中展示它有其限制,例如多级嵌套的子元素,但对于简单的XML结构,我认为这样做是可以的。对于任何超过一个嵌套级别的内容,我更喜欢使用XML方式。
甚至更好的方法是创建一个XML模式(XSD)文件。这样,你可以在XML中看到它的优点,并且可以使用一些软件在数据输入后根据模式文件检查文件。
如果想了解关于XSD的一系列教程,请访问w3schools - XML Schema Tutorial

0

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接