id[el.atom.id]REQUIRED

An identifier for an atom

Of the form prefix:suffix where prefix and suffix are purely alphanumeric (with _ and -) and prefix is optional. This is similar to XML IDs (and we promote this as good practice for atomIDs. Other punctuation and whitespace is forbidden, so IDs from (say) PDB files are not satisfactory.

The prefix is intended to form a pseudo-namespace so that atom IDs in different molecules may have identical suffixes. It is also useful if the prefix is the ID for the molecule (though this clearly has its limitation). Atom IDs should not be typed as XML IDs since they may not validate.

example

<cml>
  <molecule id="m1">
    <atomArray>
<!-- this atom might be referenced as m1:a2. This is not formally
     part of CML yet -->
      <atom id="a2" elementType="O"/>
    </atomArray>
  </molecule>
  <molecule id="m2">
    <atomArray>
<!-- this atom might be referenced as m2:a2. This is not formally
     part of CML yet -->
      <atom id="a2" elementType="O"/>
    </atomArray>
  </molecule>
</cml>

[xsd:string]

Pattern: [A-Za-z0-9_-]+(:[A-Za-z0-9_-]+)?

The mandatory unique ID for the atom.

count[el.atom.count]

A count multiplier for an element

Many elements represent objects which can occur an arbitrary number of times in a scientific context. Examples are action, object or molecules.

example

<list>
<object title="frog" count="10"/>
<action title="step3" count="3">
  <p>Add 10 ml reagent</p>
</action>
</list>

[xsd:nonNegativeInteger]

The occurrence count of the atom.

Most useful in formula but possibly useful in atomArray where coordinates and connectivity is not defined. No formal default, but assumed to be 1.

elementType[el.atom.elementType]

Allowed elementType values

The periodic table (up to element number 118. In addition the following strings are allowed:

Dummy. This does not correspond to a "real" atom and can support a point in space or within a chemical graph.

example

<atomArray>
  <atom id="a1" elementType="C"/>
  <atom id="a2" elementType="N"/>
  <atom id="a3" elementType="Pb"/>
  <atom id="a4" elementType="Dummy"/>
</atomArray>

UNION OF

Allowed values

Ac
Al
Ag
Am
Ar
As
At
Au
B
Ba
Bh
Bi
Be
Bk
Br
C
Ca
Cd
Ce
Cf
Cl
Cm
Co
Cr
Cs
Cu
Db
Dy
Er
Es
Eu
F
Fe
Fm
Fr
Ga
Gd
Ge
H
He
Hf
Hg
Ho
Hs
I
In
Ir
K
Kr
La
Li
Lr
Lu
Md
Mg
Mn
Mo
Mt
N
Na
Nb
Nd
Ne
Ni
No
Np
O
Os
P
Pa
Pb
Pd
Pm
Po
Pr
Pt
Pu
Ra
Rb
Re
Rf
Rh
Rn
Ru
S
Sb
Sc
Se
Sg
Si
Sm
Sn
Sr
Ta
Tb
Tc
Te
Th
Ti
Tl
Tm
U
Uun
Uuu
Uub
Uut
Uuq
Uup
Uuh
Uus
Uuo
V
W
Xe
Y
Yb
Zn
Zr
Dummy

[xsd:string]

Pattern: [A-Za-z]+:[A-Za-z][A-Za-z0-9\-]+

The elementType. Almost mandatory

formalCharge[el.atom.formalCharge]

The formal charge on an atom

Used for electron-bookeeping. This has no relation to its calculated (fractional) charge.

example

<atomArray>
  <atom id="a1" elementType="N" formalCharge="+1"/>
  <atom id="a2" elementType="O" formalCharge="-1"/>
</atomArray>

[xsd:integer]

The formalCharge on the atom

NOT the calculated charge or oxidation state. No formal default, but its absence implies 0. It may be good practice to include it explicitly.

hydrogenCount[el.atom.hydrogenCount]

The total number of hydrogen atoms bonded to an atom

The total number of hydrogen atoms bonded to an atom, whether explicitly included as atoms or not. It is an error to have hydrogen count less than the explicit hydrogen count. There is no default value and no assumptions about hydrogen Count can be made if it is not given.

If hydrogenCount is given on every atom, then the values can be summed to give the total hydrogenCount for the (sub)molecule. Because of this hydrogenCount should not be used where hydrogen atoms bridge 2 or more atoms.

example


<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" dictRef="chem:atom"
  xmlns:stm="http://www.xml-cml.org/schema/stmml"
>
  <stm:scalar title="dipole" dictRef="d:dip" 
    units="unit:debye">0.2</stm:scalar>
  <atomParity atomRefs4="a3 a7 a2 a4">1</atomParity>
  <electron id="e1" atomRef="a1" count="2"/>
</atom>

[xsd:nonNegativeInteger]

The explicit hydrogen count

nonHydrogenCount[el.atom.nonHydrogenCount]

The number of non-hydrogen atoms attached to an atom

Obsolete in core CML. Only useful in CML queries

[xsd:nonNegativeInteger]

The non-hydrogen count (obsolete - moved to CML Query)

isotope[el.atom.isotope]

The numeric representation of an isotope

In core CML this represents a single number; either the combined proton/neutron count or a more accurate estimate of the nuclear mass. This is admittedly fuzzy, and requires a more complex object (which can manage conventions, lists of isotopic masses, etc.) See isotope.

The default is "natural abundance" - whatever that can be interpreted as.

Delta values (i.e. deviations from the most abundant istopic mass) are never allowed.

[xsd:decimal]

minInclusive: 0.0

maxInclusive: 99999999999.0

The isotopic mass. Default implies "natural abundance"

occupancy[el.atom.occupancy]

Occupancy of an atomic site

Primarily for crystallography. Values outside 0-1 are not allowed.

example

See atom.

[xsd:decimal]

minInclusive: 0

maxInclusive: 1

The occupancy (mainly from crystallography)

x2[el.atom.x2]

The x coordinate of a 2-D representation (unrelated to 3-D structure). Note that x- and y- 2D coordinates are required for graphical stereochemistry such as wedge/hatch. x- and y- coordinates must be both present or both absent.

x3[el.atom.x3]

The x coordinate of a 3-D cartesian representation. x3 y3 and z3 coordinates must be both present or both absent.

xFract[el.atom.xFract]

The fractional x coordinate in a crystal structure. xFract, yFract and zFract coordinates must be all present or all absent. A crystal element is required

xy2[el.atom.xy2]

An x/y coordinate pair

An x/y coordinate pair consisting of two real numbers, separated by whitespace or a comma. In arrays and matrices, it may be useful to set a separate delimiter

example


<list>
  <array
      >1.2,3.4   3.2,4.5   6.7,23.1 </array>
  <array delimiter="/"
      >/1.2 3.4/3.2 4.5/6.7 23.1/</array>
</list>

[xsd:string]

Pattern: \s*([-]|[+])?\d*\.?\d*(\s+|[,])([-]|[+])?\d*\.?\d*\s*

The combined x and y coordinates of a 2-D representation (unrelated to 3-D structure). Note that x- and y- 2D coordinates are required for graphical stereochemistry such as wedge/hatch.

xyz3[el.atom.xyz3]

An x/y/z coordinate triple

An x/y/z coordinate triple consisting of three real numbers, separated by whitespace or commas. In arrays and matrices, it may be useful to set a separate delimiter

example

<list>
  <array>1.2,3.4,1.2   
    3.2,4.5,7.3   6.7,23.1,5.6 </array>
  <array delimiter="/"
  >/1.2 3.4 3.3/3.2 4.5 4.5/6.7 23.1 5.6/</array>
</list>

[xsd:string]

Pattern: \s*([-]|[+])?\d*\.?\d*(\s+|[,])([-]|[+])?\d*\.?\d*(\s+|[,])([-]|[+])?\d*\.?\d*\s*

The combined x, y, z coordinates of a 3-D cartesian representation.

xyzFract[el.atom.xyzFract]

An x/y/z coordinate triple

An x/y/z coordinate triple consisting of three real numbers, separated by whitespace or commas. In arrays and matrices, it may be useful to set a separate delimiter

example

<list>
  <array>1.2,3.4,1.2   
    3.2,4.5,7.3   6.7,23.1,5.6 </array>
  <array delimiter="/"
  >/1.2 3.4 3.3/3.2 4.5 4.5/6.7 23.1 5.6/</array>
</list>

[xsd:string]

Pattern: \s*([-]|[+])?\d*\.?\d*(\s+|[,])([-]|[+])?\d*\.?\d*(\s+|[,])([-]|[+])?\d*\.?\d*\s*

The combined x, y, z fractional coordinates in a crystal structure. A crystal element is required

y2[el.atom.y2]

The y coordinate of a 2-D representation (unrelated to 3-D structure). Note that x2 and y2 coordinates are required for graphical stereochemistry such as wedge/hatch. x2 and y2 coordinates must be both present or both absent.

y3[el.atom.y3]

The y coordinate of a 3-D cartesian representation. x3 y3 and z3 coordinates must be both present or both absent.

yFract[el.atom.yFract]

The fractional x coordinate in a crystal structure. xFract, yFract and zFract coordinates must be all present or all absent. A crystal element is required

z3[el.atom.z3]

The z coordinate of a 3-D cartesian representation. x3 y3 and z3 coordinates must be both present or both absent.

zFract[el.atom.zFract]

The fractional x coordinate in a crystal structure. xFract, yFract and zFract coordinates must be all present or all absent. A crystal element is required

title[att.title]

A title on an element.

No controlled value.

example

<action title="turn on heat" start="T09:00:00" convention="xsd"/>

convention[att.convention]

A string referencing a dictionary, units, convention or other metadata.

The namespace is optional but recommended where possible

Note: this convention is only used within STMML and related languages; it is NOT a generic URI.

example

<list>
<!-- dictRef is of namespaceRefType -->
  <scalar dictRef="chem:mpt">123</scalar>  
<!-- error -->
  <scalar dictRef="mpt23">123</scalar>  
</list>

[xsd:string]

Pattern: [A-Za-z][A-Za-z0-9_]*(:[A-Za-z][A-Za-z0-9_]*)?

A reference to a convention

There is no controlled vocabulary for conventions, but the author must ensure that the semantics are openly available and that there are mechanisms for implementation. The convention is inherited by all the subelements, so that a convention for molecule would by default extend to its bond and atom children. This can be overwritten if necessary by an explicit convention.

It may be useful to create conventions with namespaces (e.g. iupac:name). Use of convention will normally require non-STMML semantics, and should be used with caution. We would expect that conventions prefixed with "ISO" would be useful, such as ISO8601 for dateTimes.

There is no default, but the conventions of STMML or the related language (e.g. CML) will be assumed.

example

<bond convention="fooChem" order="-5"
   xmlns:fooChem="http://www.fooChem/conventions"/>

dictRef[att.dictRef]

A string referencing a dictionary, units, convention or other metadata.

The namespace is optional but recommended where possible

Note: this convention is only used within STMML and related languages; it is NOT a generic URI.

example

<list>
<!-- dictRef is of namespaceRefType -->
  <scalar dictRef="chem:mpt">123</scalar>  
<!-- error -->
  <scalar dictRef="mpt23">123</scalar>  
</list>

[xsd:string]

Pattern: [A-Za-z][A-Za-z0-9_]*(:[A-Za-z][A-Za-z0-9_]*)?

A reference to a dictionary entry.

Elements in data instances such as scalar may have a dictRef attribute to point to an entry in a dictionary. To avoid excessive use of (mutable) filenames and URIs we recommend a namespace prefix, mapped to a namespace URI in the normal manner. In this case, of course, the namespace URI must point to a real XML document containing entry elements and validated against STMML Schema.

Where there is concern about the dictionary becoming separated from the document the dictionary entries can be physically included as part of the data instance and the normal XPointer addressing mechanism can be used.

This attribute can also be used on dictionary elements to define the namespace prefix

example

<scalar dataType="xsd:float" title="surfaceArea" 
  dictRef="cmlPhys:surfArea" 
  xmlns:cmlPhys="http://www.xml-cml.org/dict/physical"
  units="units:cm2">50</scalar>

example

<stm:list xmlns:stm="http://www.xml-cml.org/schema/stmml">
  <stm:observation>
    <p>We observed <object count="3" dictRef="#p1"/> 
      constructing dwellings of different material</p>
  </stm:observation>
  <stm:entry id="p1" term="pig">
    <stm:definition>A domesticated animal.</stm:definition>
    <stm:description>Predators include wolves</stm:description>
    <stm:description class="scientificName">Sus scrofa</stm:description>
  </stm:entry>
</stm:list>

ref[att.ref]

A reference to an existing element

A reference to an existing element in the document. The target of the ref attribute must exist. The test for validity will normally occur in the element's appinfo

Any DOM Node created from this element will normally be a reference to another Node, so that if the target node is modified a the dereferenced content is modified. At present there are no deep copy semantics hardcoded into the schema.

BASE: idType

A unique ID for an element

This is not formally of type ID (an XML NAME which must start with a letter and contain only letters, digits and .-_:). It is recommended that IDs start with a letter, and contain no punctuation or whitespace. The function generate-id() in XSLT will generate semantically void unique IDs.

It is difficult to ensure uniqueness when documents are merged. We suggest namespacing IDs, perhaps using the containing elements as the base. Thus mol3:a1 could be a useful unique ID. However this is still experimental.

[xsd:string]

Pattern: [A-Za-z0-9_-]+(:[A-Za-z0-9_-]+)?

A reference to an element of given type

ref modifies an element into a reference to an existing element of that type within the document. This is similar to a pointer and it can be thought of a strongly typed hyperlink. It may also be used for "subclassing" or "overriding" elements.

example

<cml>
  <molecule id="m1">
    <atomArray>
      <atom elementType="N"/>
      <atom elementType="O"/>
    </atomArray>
  </molecule>
  <html:p>The action of <molecule ref="#m1"/> on cardiac muscle ...</html:p>
</cml>