up | Examples |

# Examples

We have attempted to provide at least one example for each element. (There are also some examples for many of the attributes and types). The examples for the elements are used for:

- Validation. The concatenated examples are validated against the schema. This ensures the schema is valid and also provides examples of how to write valid documents. Note that XMLSchema validators sometimes have different levels of strictness. In particular Xerces does not allow documentation in references to elements; this has been highlighted in public discussion. The only area where our examples do not always validate are in namespaceed data values (e.g. within dictRef values).
- Guidelines for usage. The examples show minimal examples of how each element can be used and so are a guide to its semantics.
- Code generation. The `schema` code will autogenerate Java code for each example. This will show how to construct a DOM containing this element, and also how to read such a DOM element. It also acts as a secondary check on the validity of the autogenerated code.

By convention an element `foo` will have an example `foo1.xml`. There may be other examples (`foo2.xml`, etc.) which are often more complex and so will not be used for autogeneration.

Some examples:

-     <molecule id="m1" title="angle example" >
      <?cml example="compilable"?>
        <atomArray>
          <atom id="a1"/>
          <atom id="a2"/>
          <atom id="a3"/>
        </atomArray>
        <angle units="degrees" atomRefs3="a1 a2 a3">123.4</angle>
      </molecule>

  Note:
  - This is the example for `angle`, even although the root element is not `angle`.
  - The title attribute should reflect this.
  - The processing instruction is probably obsolete
  - The example is validatable (e.g. the angle value must conform to nonNegativeAngleType).

-     <atom id="a1" title="O3'" elementType="O"
        formalCharge="1" hydrogenCount="1"
        isotope="17" occupancy="0.7"
        x2="1.2" y2="2.3"
        x3="3.4" y3="4.5" z3="5.6"
        convention="abc:chem" dictRef="chem:atom"
      >
        <scalar title="dipole" dictRef="ccml:dipole"
          units="units:debye">0.2</scalar>
        <atomParity atomRefs4="a3 a7 a2 a4">1</atomParity>
        <electron id="e1" atomRef="a1" count="2"/>
      </atom>

  Note:
  - This demonstrates all the main attributes and child elements.
  - The examples should all be well-formed XML documents.