XSDを文書化する手間が省けますか？

Question

最近、XMLを介してクライアントにデータ抽出を提供し始めました。このXMLの構造を定義するスキーマ（XSD）があります。私は要素と属性のドキュメントをスキーマ自体に含めたいと思っています。私が見つけている唯一のことは、非常に面倒な "注釈"と "ドキュメンテーション"タグです。

だから、このよう読まするシンプルで簡単な何かを取る：

<xs:element name="TransactionType" type="xs:string" /> 

そしてこの醜い混乱で終わる：

<xs:element name="TransactionType" type="xs:string"> 
    <xs:annotation> 
     <xs:documentation> 
      Type of transaction 
     </xs:documentation> 
    </xs:annotation> 
</xs:element> 

はもっと良いものはありますか？

<xs:element name="TransactionType" type="xs:string" description="Type of transaction" /> 

PS：これは単純な固定長のファイルとして、またCSVとしてすでに提供されています。 1つのクライアントがXMLを要求し、XMLを使用したい第2のクライアントがいます。私は文書を求められた。最初にXMLバージョンを開発した最初のクライアントは、XSDがほしいと思っていました。したがって、私は、第2のクライアントに1つの文書（要素を説明する簡単な注釈付きのXSD）を送信したいと考えています。

Answer 1

いいえ、ありません。 <xs:annotation><xs:documentation>はすべてあります。

Answer 2

XSDは、ドキュメンテーションのために言及したタグを提供します。 私はあなたに同意する、彼らは煩わしく、ファイルをさらに大きくする。

これは不幸にも私たちが持っているものです。

Answer 3

はい、これは面倒ですが、残念ながらドキュメント化の唯一の仕組みです。しかし、注釈タグは、多くのニーズを満たすために提供されています。あなたはそこにコンピュータ処理の指示を置くことができます、そこに人間が読める文書を置くことができます。

XSDは、情報を効果的にコンピュータプログラムに伝えるために、より多く設計されています。たとえば、スキーマからコードジェネレータを実行している場合、コードジェネレータは、JavaDocなどのコードの自己文書化、または他の言語と同等のアノテーション要素情報を含めることができます。

また、注釈ドキュメントタグに任意の長さのテキストを含めることもできます。これは、HTMLタグと実際には任意のXMLを含むことができます。これが属性ではなく要素である理由です。

Answer 4

煩雑なアノテーションタグとドキュメンテーションタグを使っても、XSDを簡単に読みやすいHTMLドキュメントファイルに簡単に変換できます。

魔法はxs3pと呼ばれています.XSD（まったく別のXMLです）をきれいに整理された非常に便利なドキュメントHTMLに変換するには相当な量のXSLTファイルです。

無料です。うまくいきます。 :-)

もちろん、注釈/ドキュメントをXSDに追加する必要がありますが、XSDと別のドキュメントファイル（これよりも早く同期が外れる可能性が高い後ほど......）

マルク・

Answer 5

私が提案持っている - なぜあなたは、あなたが提案する方法で、すなわちスキーマを書いていないが

<xs:element name="TransactionType" type="xs:string" description="Type of transaction" /> 

とあなたが内部的に使用すると、コンパクトなバージョンを使用し、顧客に変換XSDを配る

<xs:element name="TransactionType" type="xs:string"> 
<xs:annotation> 
    <xs:documentation> Type of transaction </xs:documentation> 
</xs:annotation> 
</xs:element> 

の完全な形式にそれを変換するためにXSLTを通します。