— the global portal for all things SBML

SBML Level 3 Principles


This area is a working space for discussing principles guiding SBML Level 3.

Organization and versioning of packages

All additional packages besides the Core are built on top of the core. Conceptually, all packages are placed the same level in a hierarchy rooted under the XML namespace URI "". The versioning scheme for packages is as follows:

  1. The root version number in the SBML namespace URI refers to the version of the Core package. For example, "" indicates the version of the SBML Level 3 Core package.
    • The URI for Version 1 of the Core package is "" (i.e., including the component /core at the end), so that all package namespace URIs have the same parallel structure.
  2. All other packages are numbered sequentially using monotonically increasing integers, regardless of the version of the Core package.
    1. The first version of a package is version 1. (Example: SBML Level 3 Layout, Version 1.) The second version is Version 2, and so on.
    2. The XML namespace URI for a package is the concatenation of the root Level 3 URI, the package label (as listed in the Level 3 activity table), and the package version number. (Example: the URI for the Qualitative Models package, version 1, is "".)
  3. When the version of the Core package is incremented, all packages must be reviewed and separately verified for compatibility with the new version of the Core. For each package, when it is revised to work with the new Core (or after it is determined that no changes are necessary), a new version of that package must be released in order to coincide with the new version of the Core. The version number of a package is not reset when the Core changes versions. For example, given a package P with version number N for Core version X, if a new Core version X+1 is released, P must be reviewed and a new version N+1 of P must be released before package P can be used with Core version X+1.

The diagram below illustrates the package version numbering approach:

The package numbering approach is designed to avoid confusion and ambiguity about which version of a package is usable with which version of the Core. Although the scheme does lead to a more rapid increase in version numbers than other possible numbering scheme, we believe this trade-off is worth it; in this approach, it is entirely unambiguous which version of a package corresponds to a given version of the Core.

Use of XPath instead of SId

A problem faced in SBML Level 3 packages is how to reference identifiers inside a model from outside of that model. For example, this is faced by the Layout package, since it places a list of layouts outside of a <model>; it is also faced by the package for hierarchical model composition, in which multiple models can potentially be encapsulated inside another.

Rather than invent a novel hierarchical referencing scheme using some custom object structure, the SBML Level 3 approach uses XML XPath 1.0 syntax. Currently, in Level 2, the data type of attributes that can refer to identifiers of other objects in a model is SId. (Note this matter is only about references to identifiers, not the definition of those identifiers—the identifier syntax will remain the same.) In Level 3, the data type of these attributes is string as defined in the SBML Level 2 Version 4 specification (the type is actually defined by XML Schema 1.0), and the syntax permitted in these strings is XPath 1.0 syntax. The type string type allows all Unicode characters, with the following exceptions:

  • The characters 0xFFFE and 0xFFFF are not permitted
  • The ampersand (&) character must be escaped using the entity &amp;
  • The less-than character (<) character must be escaped using the entity &lt;

Although XPath allows quite elaborate references to be made, in SBML only some kinds of references will make sense in a given context. For example, each Species object has an attribute, compartment, whose value must refer to a compartment in the model where that particular Species entity appears. The model entities indexed by an XPath expression used as the value of a compartment attribute must be the identifiers of compartments in the model.

Here is an example of using XPath syntax, in one form (though others are possible). Here, "..." represents omitted text:

<?xml version="1.0" encoding="UTF-8"?> 
<sbml xmlns="" level="3" version="1">
  <model id="example">
      <compartment id="comp" ... />
      <species compartment="/sbml/model/listOfCompartments/compartment[@id='comp']" ... />

Other XPath selectors can also produce the same results for this case. In the definition of Species in SBML Level 3 Core, the value of the compartment attribute is only constrained to refer to an existing compartment in the model, not in how the XPath selector is constructed.

We note that there exist many implementations of XPath processors, for a variety of programming languages; we expect that software authors will not have to develop their own XPath processing engines. (LibSBML will incorporate one of these for its Level 3 support too.)

No default values

A common source of confusion and error in interpreting models in SBML Level 2 is the specification of default values for certain attributes of SBML components. These include default values for stoichiometries, default units, etc. The following definition of Species illustrates how defaults are used for the value of the attributes hasOnlySubstanceUnits, boundaryCondition, and constant:

The presence of a default attribute value means that an SBML model file does not need to mention the defaulted attributes and their values. For example, the following <species> definition in SBML Level 2 does not mention a value for the attributes hasOnlySubstanceUnits, boundaryCondition, and constant, and thus their values are assumed to be all "false":

<species id="s" compartment="c">

Note that this matter only concerns attributes that have default values, not optional attributes with no default values (such as <initialConcentration>) ; such attributes have no value at all if they are not mentioned in a component's definition in a model.

Experience with SBML has lead to the realization that it is far too easy for a reader to misinterpret such a model—a reader needs to memorize the SBML specification in complete detail to know that unmentioned attributes even exist, and to know their values. Further, some SBML default values are controversial in SBML, with different modelers preferring (and often assuming) one value in particular. Finally, the fact that default values exist at all means that a model is in some sense not self-contained.

For SBML Level 3, the SBML Editors have concluded the best approach is simply to remove all default values from the specification. This means that any attribute or element not mentioned in the XML file does not exist in that model. The price of this approach is only an increase in verbosity and file size. The former is only an issue for human readers (computer systems don't care), while the latter issue is largely mitigated by the speeds and storage capacities of modern computers as well as use of compression technologies.

Consequently, in Level 3, the species example above would have to be written as follows:

<species id="s" compartment="c" 
                hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false">

Note that in this particular example, the other Species attributes (e.g., initialAmount) are not assigned values and thus (like the original Level 2 version above) have no value for this particular instance. (This example is not necessarily realistic for a functioning model; it is only meant to illustrate how the Level 3 no-default-values approach works.)

A consequence for the unit system in SBML is that there are no default values for the SBML "built-in" units. The unit identifiers substance, time, volume, area, length always have to be defined if a model uses them; no default definitions for these units are provided in SBML Level 3. This is unlike the situation in SBML Level 2, where these unit identifiers do have default definitions (and, for example, the default unit of compartment size is volume, which in turn is defined to be "liter"). If a model does not use a particular unit, it does not have to define a value for it.

Finally, this principle does not apply to the MathML subset used in SBML. MathML constructs that have attributes with default values remain unchanged in Level 3 Core. The rationale for this is the following: (1) it would not be a MathML requirement, but an SBML requirement, and thus would represent a new restriction on MathML content in SBML; (2) it would potentially lead to implementation problems for developers using off-the-shelf MathML parser libraries, because such parsers may not offer control over this behavior.

Approach to handling MathML additions

In the past, there have been proposals to extend the subset of MathML supported in SBML, for example by the addition of MathML's <sum> and <vector>. Level 3 represents an obvious opportunity to revisit the topic of adding more MathML constructs.

After briefly flirting with the idea of adding new MathML constructs in anticipation of their need by Level 3 packages, and careful consideration of the implications, the SBML Editors decided against doing so. Instead, each Level 3 package will define whatever additional MathML constructs it needs on a case-by-case basis. The rationale for this design principle is the following:

  1. It is impossible to predict which constructs will be needed by future Level 3 packages; therefore, attempts to add MathML constructs in anticipation of future needs is doomed to failure.
  2. Adding MathML constructs to the Core, if they cannot properly be used except via some Level 3 package, would be asking for trouble. People would inevitably attempt to use them anyway.
  3. Additions of MathML constructs to the Core would further distance the Core from Level 2 Version 4, going against the goal of making the Level 2 to Level 3 Core transition as straightforward as possible.

Retrieved from ""

This page was last modified 13:44, 12 March 2009.

Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 13:44, 12 March 2009.