UCM 1-1-1 Reference

A container for information about a bond in a chemical structure. The bond element can represent various bonds from simple ones that connect two node elements to delocalized or other bonds, in which multiple node or point elements participate.

There are two possible contexts where different attributes and child elements are enabled for this element.

For the bond element without the idrefs attribute the following applies. It is mandatory to specify the value of the id and order attribute, but the idrefs attribute must be omitted. All id references must be specified using one or more join child elements. The particle element(s) must represent enough bonding electrons, which can be used by all bond elements that refer to this element. This element must contain zero or one description element as the first child followed by zero or more property, one or more join and zero or more particle child elements, and by zero or one stereo child element (the sequence of child elements is mandatory).

For the bond element with the idrefs attribute the following applies. It is mandatory to specify the value of the id, idrefs and order attribute. The value of the idrefs attribute must contain two id references. Each id reference must refer to the node or point element inside a structure element. If electrons participating in the bond are not expressed inside this bond element by the particle element(s) each id reference must refer only to the node element inside a structure element. The particle element(s) must represent enough bonding electrons, which can be used by all bond elements that refer to this element. This element must contain zero or one description element as the first child followed by zero or more property and particle child elements, and by zero or one stereo child element (the sequence of child elements is mandatory and join child elements must be omitted). Usage of this context is mandatory when the bond element has the order attribute with the value "PS", "S", "PD", "D", "PT", "T", "PQ" or "Q".

A container for various definitions.

It is optional to specify the value of the id attribute and mandatory to specify the format for this element. Then, inside this element UCM can be used to define descriptions, nodes and properties; UnitsML can be used to define quantities with appropriate units; and literature references can be defined using BibTeXML.

This element can contain UCM, UnitsML or BibTeXML content, which must use the appropriate namespace. The UCM namespace is "http://www.universalchemicalmarkup.org", UnitsML namespace is "urn:oasis:names:tc:unitsml:schema:xsd:UnitsMLSchema-1.0" and BibTeXML namespace is "http://bibtexml.sf.net/". Usually the most advantageous approach is to specify these using namespace prefixes on the ucm element or on relevant define elements. The UCM content is restricted to zero or more description, property and node child elements (the sequence of child elements is mandatory). The UnitsML and BibTeXML content must be valid according to the UnitsML or BibTeXML schema.

A container for the description with optional literature reference(s).

There are two possible contexts where attributes are enabled differently for this element.

For the description element that is a child of the define element the following applies. It is mandatory to specify the value of the id attribute and optional to specify one or more id references using the idrefs or litrefs attribute.

For the description element that is not a child of the define element the usage of id, idrefs and litrefs attributes is optional.

In both contexts each id reference in the idrefs attribute must refer to the external description (i.e. the description element inside a define element), while each id reference in the litrefs attribute must refer to the literature reference defined using BibTeXML inside a define element.

This element can contain a simple plain text or XHTML content, which must use the "http://www.w3.org/1999/xhtml" namespace. Usually the most advantageous approach is to specify it using a namespace prefix on the ucm element. The XHTML content must be valid according to the XHTML schema.

A container for information about how to join node or point elements that participate in the bond.

It is optional to specify the value of the id attribute and mandatory to specify two or more id references using the idrefs attribute. Each id reference must refer to the node or point element inside a structure element. If electrons participating in the bond are not expressed inside the parent bond element by the particle element(s) each id reference must refer only to the node element inside a structure element. The value of this element must specify the interpretation of id references in the idrefs attribute.

The following values are currently enabled:

• "SQ" - Sequential interpretation
• "CC" - Cyclic interpretation
• "CT" - Centered interpretation

The sequential interpretation means that the node or point elements referenced by the neighboring id references are bonded by the bond expressed in the parent bond element. The cyclic interpretation only extends the sequential interpretation by regarding also the first and last id reference as neighboring. The centered interpretation means the first id reference refers to the node or point element that is bonded, by the bond expressed in the parent bond element, to all node or point elements specified by the remaining id references.

A container for information about a chemical node that represents a monoatomic particle (usually an atom or a monoatomic ion) composed of protons, neutrons or electrons.

There are three possible contexts where different attributes and child elements are enabled for this element.

For the node element inside a define element the following applies. It is mandatory to specify the value of the id attribute, but the idrefs and charge attribute must be omitted as well as coordinates ("x", "y", "z") in 3-dimensional space. This element must contain zero or one description element as the first child followed by zero or more property and one or more particle child elements (the sequence of child elements is mandatory and the stereo child element must be omitted). The particle child elements must define the number of protons, neutrons and electrons.

For the node element that is inside a structure element and has the idrefs attribute, the following applies. It is mandatory to specify the value of the attribute id, idrefs and charge (if not zero), and optional to specify coordinates ("x", "y", "z") in 3-dimensional space. The value of the idrefs attribute must be one id reference that refers to the node definition (i.e. the node element inside a define element). The node definition must contain enough bonding electrons (expressed by the particle element), which can be used by all bonds of the node element that uses this definition. This element must contain zero or one description element as the first child followed by zero or more property child elements and by zero or one stereo child element (the sequence of child elements is mandatory and particle child elements must be omitted).

For the node element that is inside a structure element and without the idrefs attribute, the following applies. It is mandatory to specify the value of the attribute id and charge (if not zero), and optional to specify coordinates ("x", "y", "z") in 3-dimensional space, but the idrefs attribute must be omitted. Inside the element must be enough bonding electrons (expressed by the particle element), which can be used by all bonds of this element. This element must contain zero or one description element as the first child followed by zero or more property and one or more particle child elements, and by zero or one stereo child element (the sequence of child elements is mandatory). The particle child elements must define the number of protons, neutrons and electrons.

A container for information about one or more subatomic particles.

There are two possible contexts where different attributes and child elements are enabled for this element.

For the particle element inside a bond element the following applies. It is optional to specify the value of the id attribute and mandatory to specify one id reference using the idrefs attribute. The id reference must refer to the bond or structure element or to the node element inside a structure element. The referenced bond, structure or node element must contain enough subatomic particles (of the given type), which can be used by the particle element. In addition it is also mandatory to provide the value of the type and counts attribute, but the fractions attribute must be omitted. This element must contain zero or one description element as the first child followed by zero or more property and share child elements (the sequence of child elements is mandatory).

For the particle element inside a node element the following applies. It is optional to specify the value of the id attribute and mandatory to specify the value of the type and counts attribute, but the idrefs attribute must be omitted. If the type attribute value is "N" and the counts attribute contains more than one particle count in its value it is mandatory to specify the occurrence ratio of each count using the fractions attribute. In other cases the fractions attribute must be omitted. This element must contain zero or one description element as the first child followed by zero or more property child elements (the sequence of child elements is mandatory and share child elements must be omitted).

A container for information about a point in a chemical structure.

It is mandatory to specify the value of the id attribute as well as coordinates ("x", "y", "z") in 3-dimensional space.

The intended usage of the point element is to describe important places in the structure that are outside the scope of node elements. An example may be the places to which other node or structure (via its point child element) is or can be bonded.

This element must contain zero or one description element as the first child followed by zero or more property child elements (the sequence of child elements is mandatory).

A container for information about a measured or calculated property. The property element can be used in a bond, node, particle, point or structure element or for a property definition in a define element.

There are two possible contexts where different attributes and child elements are enabled for this element.

For the property element inside a define element, or the property element that does not have the idrefs attribute, the following applies. It is mandatory to specify the value of the id, type and quantity attribute, but the idrefs attribute must be omitted. This element must contain zero or one description element as the first child followed by zero or more property (it can be nested) child elements and one values child element (the sequence of child elements is mandatory).

For the property element that has the idrefs attribute, the following applies. It is mandatory to specify the value of the id and idrefs attribute, but the type and quantity attribute must be omitted. The value of the idrefs attribute must be one id reference referencing the property definition (i.e. the property element inside a define element). This element must contain zero or one description element as the only child (property and values child elements must be omitted).

A container for information about how bonding electrons are shared between node elements that participate in the bond.

It is optional to specify the value of the id attribute and mandatory to specify two or more id references using the idrefs attribute. Each id reference must refer to the node element inside a structure element. For each id reference it is also mandatory to specify the sharing ratio using the fractions attribute.

This element must contain zero or one description child element.

A container for describing the stereochemistry of a structure element or around a node or bond element.

It is optional to specify the value of the id attribute and mandatory to specify the id references using the idrefs attribute. Each id reference must refer to the node or point element inside a structure element. In addition it is also mandatory to provide the value of the sense attribute.

The interpretation of the stereo element depends on the sequence and number of id references. There are five possible contexts with different interpretation.

For the stereo element, which is inside a node or bond element and has the idrefs attribute with four id references, describing the stereochemistry of a chirality centre or bond, the following applies. The id references indicate substituents on the node or bond element ordered by descending priority.

For the stereo element, which is inside a node element and has the idrefs attribute with five or seven id references, describing the stereochemistry of a square planar or octahedral complex, the following applies. The first id reference denotes the central node element and the remaining id references indicate substituents on the central node element ordered by descending priority.

For the stereo element, which is inside a structure element and has the idrefs attribute with six id references, describing the stereochemistry of a chiral axis, the following applies. The first two id references refer to the node or point elements defining the axis and the remaining id references indicate substituents on the axis ordered by descending priority.

For the stereo element, which is inside a structure element and has the idrefs attribute with five id references, describing the twist conformation of a bidentate ligand, the following applies. The first id reference denotes the central node element, the next two id references refer to the node elements forming the reference plane together with the central node element and the last two id references refer to the node elements forming the twist. The sequence of id references for node elements forming the twist is from left to right side (as seen from the observer point of view described in the sense attribute documentation).

For the stereo element, which is inside a structure element and has the idrefs attribute with seven id references, describing the absolute configuration of three bidentate ligands, the following applies. The first id reference denotes the central node element, the next three id references refer to the node elements forming the first reference plane (above the central node element) and the last three id references refer to the node elements forming the second reference plane (below the central node element). The first reference plane can be chosen arbitrarily.

The priority of substituents should be (thus it is not mandatory) assigned according to the Cahn-Ingold-Prelog system of priority rules. The sense attribute documentation describes how to assign the value describing the stereo configuration based on the sequence of id references and the position of referenced elements. Note that the stereo configuration described by this element should correspond with the 3-dimensional coordinates ("x", "y", "z") of referenced elements, but UCM validation currently does not verify this. It is assumed that software tools working with the stereochemistry in UCM should implement the necessary checks and if required also algorithms that can asign the stereo configuration using the 3-dimensional coordinates ("x", "y", "z") automatically or semiautomatically (e.g. when the user decides the substituents priority manually).

This element must contain zero or one description child element.

A container for the chemical structure. The structure element can represent a complete chemical structure or just some relevant part of it. Thus, using this element it is possible to express structures and substructures as well as structure queries and identifiers.

There are two possible contexts where different attributes and child elements are enabled for this element.

For the structure element that has the format attribute with the value of "UCM", the following applies. It is mandatory to specify the value of the id, format and type attribute, and optional to specify the value of the charge attribute. This element must contain zero or one description element as the first child followed by zero or more structure (it can be nested), property, node, bond, point and stereo child elements (the sequence of child elements is mandatory).

For the structure element that has the format attribute with other value than "UCM", the following applies. It is mandatory to specify the value of the id, format and type attribute, but the charge attribute must be omitted. The content of this element must conform to regular expression patterns, which check whether the used characters and content structures follow the basic specifications of the given format. Note that for "SMILES", "SMARTS" and "SLN" format values the chemical reactions syntax is not enabled in structure elements. Additionally, for the content of structure elements using other format value than "UCM" the validation in UCM does not attempt to verify that it represents chemically correct or otherwise valid data. It is assumed that software tools working with such data (e.g. structure queries and identifiers) should implement the necessary algorithms to check and parse the data and where required and possible obtain the corresponding chemical structures. These structures could be later stored in UCM format (i.e. in the structure elements with the format attribute value of "UCM").

In both contexts the type attribute value further restricts the values of the format attribute, which in turn restricts the possible content of this element. If the type attribute has the value of "ST", the format attribute can have any value listed in its documentation as enabled on structure elements. In other words just the "UNITSML" and "BIBTEXML" values are not enabled. If the type attribute value is "SBST", the format attribute must have the value of "UCM". In the case of "STQR" type value the format attribute can have any value enabled for structure elements except for the "UCM" value. Finally, for the type value "STID" the format attribute can have any value enabled for structure elements with the exception of "UCM", "SMILES", "SMARTS" and "SLN" values.

The root element of UCM. The ucm element is the main container for all UCM attributes and elements.

It is optional to specify the value of the id attribute and mandatory to specify the version and namespace of UCM used for this element. Usually the most advantageous approach is to specify the UCM namespace "http://www.universalchemicalmarkup.org" as the default one using the xmlns attribute on the ucm element. Optionally also other namespace prefixes can be specified on the ucm element. This is useful to enable the XHTML usage inside description elements or BibTeXML and UnitsML usage inside define elements.

This element must contain zero or one description element as the first child followed by zero or more define and structure child elements (the sequence of child elements is mandatory).

Note that special xml:base and xml:lang attributes may be used on all UCM elements. The xml:base attribute is utilized by the xi:include mechanism, as it provides the base URI (Uniform Resource Identifier) for interpreting any relative URI in the scope of the parent element. The xml:lang attribute denotes a language code for the natural language in the scope of the parent element. The values of both xml:base and xml:lang attributes are inherited. Other special attributes from XML namespace "http://www.w3.org/XML/1998/namespace.html" are not currently supported, but if the need arises we may add them. Special attributes from XML namespace are implemented in UCM according to their definitions in the official schema, which is available at "http://www.w3.org/2009/01/xml.xsd".

A container for numeric values representing a measured or calculated property.

It is optional to specify the value of the id attribute. Then, this element must contain one or more whitespace separated double precision floating point numbers. The special values "-INF" (negative infinity), "INF" (positive infinity) and "NaN" (not a number) are supported as well as optional scientific notation. The decimal separator must be "." and no thousands separator may be used.