Guideline:Schema documentation

From BioSchemas

1 Changelog order
2 Enumeration types
3 First sentence in a documentation
4 Examples

Changelog order

New entries in a changelog should be put at first.

Enumeration types

Enumeration types must be treated in a special way, because xsddoc does not really supports documentating enumeration values. Here is an example how to do it:

<xs:simpleType name="sourceName">
  <xs:annotation><xs:documentation>
The name of a data source. The name could be any valid XML name (<code>xs:Name</code> 
type, e.g. <code>my:db</code>). However the names of some well-known databases and 
internet resources are provided as enumeration values. If the list contains an appropiate 
entry you should use this instead of defining your own name.
<p><b>Attention</b>: XML names are case sensitive.</p>
<p>Predefined data source names:</p>
  </xs:documentation></xs:annotation>
  <xs:union memberTypes="xs:Name">
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:enumeration value="default">
          <xs:annotation><xs:documentation>
<li><code>default</code>: default source. Should be the default value for any element or attribute 
of type <code>bs:sourceName</code>.</li>
          </xs:documentation></xs:annotation>
        </xs:enumeration>
        <xs:enumeration value="aaindex">
          <xs:annotation><xs:documentation>
<li><code>aaindex</code>: <a href="http://www.genome.jp/aaindex/">Amino acid index database.</a>]</li>
          </xs:documentation></xs:annotation>
        </xs:enumeration>
      </xs:restriction>
    </xs:simpleType>
  </xs:union>
</xs:simpleType>

[edit]

First sentence in a documentation

The first sentence in a <xs:documentation> element should not contain any markup because this sentence is used by SUT for the short description of the corresponding element, attribute, etc. in the overview page. Further it should concisely describe the element, attribute, etc.

[edit]