web-dev-qa-db-ja.com

XMLファイルの構造を文書化する方法

XMLファイルの構造を文書化することになると...

私の同僚の1人がWordテーブルでそれを行っています。

もう1つは、次のようなコメントを付けて要素を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>

これらの方法のどれが好ましいですか？もっと良い方法はありますか？

サードパーティのSchemaDocumenterツールを更新する必要のない他のオプションはありますか？

xsdxml-documentation
24
joe

XMLドキュメントの構造を定義するためにXMLスキーマ（XSD）ファイルを作成します。 xs:annotationタグとxs:documentationタグを含めて、要素を説明できます。 XSDファイルは、 xs3p などのXSLTスタイルシートまたは XML Schema Documenter などのツールを使用してドキュメントに変換できます。

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>
37
Phil Ross

RELAXをお楽しみくださいNGコンパクトな構文

さまざまなXMLスキーマ言語を試してみたところ、ほとんどの場合にRELAX NGが最適であることがわかりました（最後に理由があります）。

要件

  • XMLドキュメント構造の文書化を許可する
  • 読みやすい形式で行う
  • 作者にとってはシンプルにしてください

変更されたサンプルXML（doc.xml）

このタイプの構造もドキュメントで説明するために、1つの属性を追加しました。

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

与えられたレベルの表現力を保ちながら、シンプルさを打ち負かすことは非常に難しいと思います。

構造にコメントする方法

  • 常にコメントを配置してください前関連する要素の後ではなく。
  • 読みやすくするために、コメントブロックの前に1行の空白行を使用してください
  • ##プレフィックスを使用します。これは、他のスキーマ形式のドキュメント要素に自動的に変換されます。単一のハッシュ#は、ドキュメント要素ではなくXMLコメントに変換されます。

  • （例のように）複数の連続するコメントは、単一の要素内で単一の複数行のドキュメント文字列に変わります。

  • 明らかな事実：doc.xmlのインラインXMLコメントは無関係であり、schema.rncにあるものだけがカウントされます。

XMLスキーマ1.0が必要な場合は、それを生成します（schema.xsd）

trangという（オープンソースの）ツールが利用可能であると仮定すると、次のようにXMLスキーマファイルを作成できます。

$ 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スキーマ1.0のみを使用することを主張するクライアントは、XMLドキュメント仕様を使用できます。

Schema.rncに対するdoc.xmlの検証

RELAX NGコンパクトな構文をサポートし、LinuxとMSWindowsの両方で動作するjingやrnvのようなオープンソースツールがあります。

注：これらのツールはかなり古いですが、非常に安定しています。時代遅れの兆候としてではなく、安定性の兆候としてそれを読んでください。

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には優れたチュートリアルが付属しており、ほとんどを1日で習得できます）
  • 非常に柔軟性があります（事実にもかかわらず、見た目はシンプルで、多くの状況をカバーし、XMLスキーマ1.0では解決できないものもあります）。
  • 他の形式に変換するためのいくつかのツール（RELAX NG XML形式、XMLスキーマ1.0、DTD、さらにはサンプルXMLドキュメントの生成）が存在します。

RELAX NG制限

  • 多重度は、「ゼロまたは1」、「1つだけ」、「ゼロ以上」、または「1つ以上」のみにすることができます。 （少数の要素の多様性は、「ゼロまたは1」の定義の「愚かな繰り返し」によって説明できます）
  • XML Schema 1.0構造がありますが、これはRELAXNGでは記述できません。

結論

上記で定義された要件の場合、RELAX NGコンパクトな構文が最適のように見えます。RELAXNGを使用すると、両方が得られます-自動化にも使用できる人間が読めるスキーマ検証。

既存の制限はあまり有効にならず、多くの場合、コメントまたはその他の手段で解決できます。

5
Jan Vlcinsky

XMLのより正式な仕様を提供するXSDスキーマを作成して、それを文書化してみてください。多くのツールは、開始点としてサンプル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>
4
zac

個人的には、XMLで表示したいと思います（2番目の方法）。

テーブルに要素を配置しても、どの要素がどの要素の親子であるかなどは明確にわかりません。それをXMLに入れるのはかなり明確で、何が起こっているのかがわかります。

2
mauris

テーブルに表示するには、制限があります。ネストされた子のマルチレベルですが、単純なXML構造の場合、これで問題ないと思います。ネストされたレベルが複数ある場合は、XML方式をお勧めします。

さらに良い方法は、XMLスキーマ（XSD）ファイルを作成することです。そうすることで、XMLで表示できるというメリットがあり、ソフトウェアを使用してスキーマファイルに対してデータを入力した後でファイルを確認できます。

XSDに関する一連のすばらしいチュートリアルについては、 w3schools-XMLスキーマチュートリアル を確認してください。

2
Adam Harte

誰かがそれが役に立つと思う場合に備えて、もう1つ追加したいと思います。
私は時々プログラミングをします HTML と他の時間で Android。 HTMLを実行するときは、 http：//www.w3schools.com/tags/att_a_href.asp のように、W3Schoolsと同じ形式に従ってカスタムXMLを文書化します。 Android私が取り組んでいるプロジェクトは、 http：//developer.Android.com/guide/topics/manifest/activity-element.htmlのようにGoogleの標準に従います。 ＃画面
このようにして、私が一緒に仕事をしているプログラマーは、私のドキュメントを理解するために余分な作業をする必要がありません。

0
Carolina Prieto Muñiz