Xsd 如何记录XML文件的结构_Xsd_Xml Documentation

Xsd 如何记录XML文件的结构

xsd

Xsd 如何记录XML文件的结构,xsd,xml-documentation,Xsd,Xml Documentation,当涉及到记录XML文件的结构时我的一个同事在单词表中这样做另一个将元素粘贴到Word文档中，并带有如下注释： <learningobject id="{Learning Object Id (same value as the loid tag)}" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http

当涉及到记录XML文件的结构时

我的一个同事在单词表中这样做

另一个将元素粘贴到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>

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

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

还有其他不需要第三方Schema Documenter工具来更新的选项吗？

就我个人而言，我更喜欢XML格式（第二种方式）

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

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

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

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

有关XSD的一系列教程，请查看

我将编写一个XML模式（XSD）文件来定义XML文档的结构

xs:annotation

和

xs:documentation

标签可以用来描述元素。XSD文件可以使用XSLT样式表（如）或工具（如）转换为文档

有关XML模式的介绍，请参阅

下面是您的示例，用带有

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>


存储库中对象的当前版本。
存储库中对象的名称。

享受RELAX NG紧凑语法通过对各种XML模式语言的实验，我发现RELAXNG最适合大多数情况（最后是推理）

要求

允许记录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>

我认为，要保持一定的表达水平，很难超越简单性

如何评论结构

始终将注释放在相关元素之前，而不是之后

为了便于阅读，请在注释块前使用一个空行

使用
##
前缀，它会自动转换为其他模式格式的文档元素。单个散列
#
转换为XML注释，而不是文档元素

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

显而易见的事实是：
doc.XML
中的内联XML注释是不相关的，只有
schema.rnc
中的注释才起作用

如果需要XMLSchema 1.0，则生成它（Schema.xsd）假设您有一个名为
trang
的（开源）工具可用，您可以创建一个XML模式文件，如下所示：

$ trang schema.rnc schema.xsd
结果架构如下所示：

<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>   </v> <label>   </label> </objectRoot>

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

-c
很重要，
jing
默认采用XML格式的RELAXNG
使用
rnv
检查
schema.rnc
本身是否有效：

$ rnv -c schema.rnc
并验证
doc.xml
：

$ rnv schema.rnc doc.xml

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

$ rnv schema.rnc doc.xml otherdoc.xml anotherone.xml
RELAXNG紧凑语法-优点

非常可读，即使是新手也应该理解文本

易于学习（RELAXNG附带了很好的教程，您可以在一天内学习大部分内容）

非常灵活（尽管事实上，它看起来很简单，它涵盖了许多情况，其中一些问题甚至无法通过XMLSchema1.0解决）

存在一些用于转换为其他格式的工具（RELAXNG XML表单、XMLSchema1.0、DTD，甚至生成示例XML文档）

放宽限制

多重性只能是“零或一”、“仅一”、“零或多”或“一或多”。（少量元素的多样性可以用“零或一”定义的“愚蠢重复”来描述）

存在XML模式1.0构造，RELAXNG无法描述这些构造

结论对于上面定义的需求，RELAXNG紧凑语法看起来最适合。使用RELAXNG，您可以获得两种模式—人类可读的模式，甚至可以用于自动验证

现有的限制并不经常生效，在许多情况下可以通过评论或其他方式解决。
我只想补充一点，以防有人发现它有用<我有时用HTML编程，有时用android编程。当我使用HTML时，我会使用与W3Schools相同的格式记录我的自定义XML，就像我正在从事的android项目一样，然后我会遵循Google标准，如

这样，与我一起工作的程序员就不必做任何额外的工作来理解我的文档。
玩得好，菲尔，玩得好；）好主意。尽管我有点担心我的文档永远不会更新，因为现在有人需要另一个工具来更新它。@joe：一个选择是直接使用该文件作为文档，另外，您还可以使用标准工具生成进一步的文档；并使用XSD检查（验证）XML；并与可能需要了解您的格式的其他方进行交流。因为这是一种标准，学会使用它成为一种有价值的技能
<objectRoot created="2015-05-06T20:46:56+02:00"> <v>   </v> <label>   </label> </objectRoot>