apdx-validation.tex

% -*- TeX-master: "main"; fill-column: 72 -*-
\section{Validation of SBML documents} \label{apdx-validation}

\subsection{Validation and consistency rules} \label{validation-rules}

This section summarizes all the conditions that must (or in some cases,
at least \emph{should}) be true of an SBML Level~3 Version~1 model that
uses the \FBCPackage. We use the same conventions as are used in the
SBML Level~3 Version~1 Core specification document. In particular, there
are different degrees of rule strictness. Formally, the differences are
expressed in the statement of a rule: either a rule states that a
condition \emph{must} be true, or a rule states that it \emph{should} be
true. Rules of the former kind are strict SBML validation rules---a
model encoded in SBML must conform to all of them in order to be
considered valid. Rules of the latter kind are consistency rules. To
help highlight these differences, we use the following three symbols
next to the rule numbers:

\begin{description}

\item[\hspace*{6.5pt}\vSymbol\vsp] A \vSymbolName indicates a
\emph{requirement} for SBML conformance. If a model does not follow this
rule, it does not conform to the Flux Balance Constraints specification.
(Mnemonic intention behind the choice of symbol: ``This must be
checked.'')

\item[\hspace*{6.5pt}\cSymbol\csp] A \cSymbolName indicates a
\emph{recommendation} for model consistency. If a model does not follow
this rule, it is not considered strictly invalid as far as the Flux
Balance Constraints specification is concerned; however, it indicates
that the model contains a physical or conceptual inconsistency.
(Mnemonic intention behind the choice of symbol: ``This is a cause for
warning.'')

\item[\hspace*{6.5pt}\mSymbol\msp] A \mSymbolName indicates a strong
recommendation for good modeling practice. This rule is not strictly a
matter of SBML encoding, but the recommendation comes from logical
reasoning. As in the previous case, if a model does not follow this
rule, it is not strictly considered an invalid SBML encoding. (Mnemonic
intention behind the choice of symbol: ``You're a star if you heed
this.'')

\end{description}

The validation rules listed in the following subsections are all stated
or implied in the rest of this specification document. They are
enumerated here for convenience. Unless explicitly stated, all
validation rules concern objects and attributes specifically defined in
the Flux Balance Constraints package.

For \notice convenience and brevity, we use the shorthand
``\token{fbc:\-x}'' to stand for an attribute or element name \token{x}
in the namespace for the \FBCPackage, using the namespace prefix
\token{fbc}. In reality, the prefix string may be different from the
literal ``\token{fbc}'' used here (and indeed, it can be any valid XML
namespace prefix that the modeler or software chooses). We use
``\token{fbc:\-x}'' because it is shorter than to write a full
explanation everywhere we refer to an attribute or element in the
\FBCPackage namespace.

\subsubsection*{General rules about this package}

\validRule{fbc-10101}{To conform to the \FBCPackage specification for
SBML Level~3 Version~1, an SBML document must declare the use of the
following XML Namespace:\\
\textsl[-25]{\uri{http://www.sbml.org/sbml/level3/version1/fbc/version1}
}. (References: SBML Level~3 Package Specification for Flux Balance
Constraints, Version~1, \sec{xml-namespace}.)}

\validRule{fbc-10102}{Wherever they appear in an SBML document, elements
and attributes from the \FBCPackage must be declared either implicitly
or explicitly to be in the XML namespace
\uri{http://www.sbml.org/sbml/level3/version1/fbc/version1}.
(References: SBML Level~3 Package Specification for Flux Balance
Constraints , Version~1, \sec{xml-namespace}.) }

\subsubsection*{General rules about identifiers}

\validRule{fbc-10301}{(Extends validation rule \#10301 in the SBML
Level~3 Version~1 Core specification.) Within a \Model the values of the
attributes \token{id} and \token{fbc:\-id} on every instance of the
following classes of objects must be unique across the set of all
\token{id} and \token{fbc:\-id} attribute values of all such objects in
a model: the \Model itself, plus all contained \FunctionDefinition,
\Compartment, \Species, \Reaction, \SpeciesReference,
\ModifierSpeciesReference, \Event, and \Parameter objects, plus the
\FluxBound, \Objective and \FluxObjective objects defined by the
\FBCPackage. (References: SBML Level~3 Package Specification for Flux
Balance Constraints, Version~1, \sec{primtypes}.) }

\validRule{fbc-10302} {
The value of a \token{fbc:\-id} attribute must always conform to the
syntax of the SBML data type \primtype{SId}. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{primtypes}.)
}

\subsubsection*{Rules for the extended \class{SBML} class}

\validRule{fbc-20101}{In all SBML documents using the \FBCPackage, the
\SBML object must include a value for the attribute
\token{fbc:\-required} attribute. (References: SBML Level~3 Version~1
Core, Section~4.1.2.) }

\validRule{fbc-20102}{The value of attribute \token{fbc:\-required} on
the \SBML object must be of the data type \primtype{boolean}.
(References: SBML Level~3 Version~1 Core, Section~4.1.2.) }

\validRule{fbc-20103}{The value of attribute \token{fbc:\-required} on
the \SBML object must be set to \val{false}. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{xml-namespace}.) }

\subsubsection*{Rules for extended \class{Model} object}

\validRule{fbc-20201}{There may be at most one instance of each of the
following kinds of objects within a \Model object using Flux Balance
Constraints: \ListOfFluxBounds and \ListOfObjectives. (References: SBML
Level~3 Package Specification for Flux Balance Constraints, Version~1,
\sec{model-class}.) }

\validRule{fbc-20202}{The various
\textsf{\textbf{ListOf\rule{0.15in}{0.5pt}}} subobjects with an \Model
object are optional, but if present, these container object must not
be empty. Specifically, if any of the following classes of objects are
present on the \Model, it must not be empty: \ListOfFluxBounds and
\ListOfObjectives. (References: SBML Level~3 Package Specification for
Flux Balance Constraints, Version~1, \sec{model-class}.) }

\validRule{fbc-20203}{Apart from the general notes and annotation
subobjects permitted on all SBML objects, a \ListOfFluxBounds container
object may only contain \FluxBound objects. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{model-class}.) }

\validRule{fbc-20204}{Apart from the general notes and annotation
subobjects permitted on all SBML objects, a \ListOfObjectives container
object may only contain \Objective objects. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{model-class}.) }

\validRule{fbc-20205}{A \ListOfFluxBounds object may have the optional
attributes \token{meta\-id} and \token{sboTerm} defined by SBML Level~3
Core. No other attributes from the SBML Level~3 Core namespace or the
Flux Balance Constraints namespace are permitted on a \ListOfFluxBounds
object. (References: SBML Level~3 Package Specification for Flux Balance
Constraints, Version~1, \sec{model-class}.) }

\validRule{fbc-20206}{A \ListOfObjectives object may have the optional
attributes \token{meta\-id} and \token{sboTerm} defined by SBML Level~3
Core. Additionally the \ListOfObjectives must contain the attribute
\token{active\-Objective}. No other attributes from the SBML Level~3
Core namespace or the Flux Balance Constraints namespace are permitted
on a \ListOfObjectives object. (References: SBML Level~3 Package
Specification for Flux Balance Constraints, Version~1,
\sec{model-class}.) }

\validRule{fbc-20207}{The value of attribute
\token{fbc:\-activeObjective} on the \ListOfObjectives object must be of
the data type \primtype{SIdRef}. (References: SBML Level~3 Package
Specification for Flux Balance Constraints, Version~1,
\sec{activeObjective-attribute}). }

\validRule{fbc-20208}{The value of attribute
\token{fbc:\-activeObjective} on the \ListOfObjectives object must be
the identifier of an existing \Objective. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{activeObjective-attribute}.) }

\subsubsection*{Rules for extended \class{Species} object}

\validRule{fbc-20301}{A \SBML \class{Species} object may have the
optional attributes \token{fbc:\-charge} and
\token{fbc:\-chemicalFormula}. No other attributes from the Flux Balance
Constraints namespaces are permitted on a \class{Species}. (References:
SBML Level~3 Package Specification for Flux Balance Constraints,
Version~1, \sec{species-class}) }

\validRule{fbc-20302}{The value of attribute \token{fbc:\-charge} on
the \SBML \class{Species} object must be of the data type
\primtype{integer}. (References: SBML Level~3 Package Specification for
Flux Balance Constraints, Version~1, \sec{species-class}). }

\validRule{fbc-20303}{The value of attribute
\token{fbc:\-chemicalFormula} on the \SBML \class{Species} object must
be set to a \primtype{string} consisting only of atomic names or user
defined compounds and their occurrence. (References: SBML Level~3 Package
Specification for Flux Balance Constraints, Version~1,
\sec{species-class}.) }

\subsubsection*{Rules for \class{FluxBound} object}

\validRule{fbc-20401}{A \FluxBound object may have the optional SBML
Level 3 Core attributes \token{metaid} and \token{sboTerm}. No other
attributes from the SBML Level 3 Core namespace are permitted on a
\FluxBound. (References: SBML Level~3 Version~1 Core, Section~3.2.) }

\validRule{fbc-20402}{A \FluxBound object may have the optional SBML
Level 3 Core subobjects for notes and annotations. No other elements
from the SBML Level 3 Core namespace are permitted on a \FluxBound.
(References: SBML Level~3 Version~1 Core, Section~3.2.) }

\validRule{fbc-20403}{A \FluxBound object must have the required
attributes \token{fbc:\-reaction}, \token{fbc:\-operation} and
\token{fbc:\-value}, and may have the optional attributes
\token{fbc:\-id} and \token{fbc:\-name}. No other attributes from the
SBML Level~3 Flux Balance Constraints namespace are permitted on a
\FluxBound object. (References: SBML Level~3 Package Specification for
Flux Balance Constraints, Version~1, \sec{fluxbound-class}.) }

\validRule{fbc-20404}{The attribute \token{fbc:\-reaction} of a \FluxBound
must be of the data type \token{SIdRef}. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{fluxbound-class}.) }

\validRule{fbc-20405}{The attribute \token{fbc:\-name} of a \FluxBound
must be of the data type \token{string}. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{fluxbound-class}.) }

\validRule{fbc-20406}{The attribute \token{fbc:\-operation} of a
\FluxBound must be of the data type \token{FbcOperation} and thus its
value must be one of \val{lessEqual}, \val{greaterEqual} or \val{equal}.
(References: SBML Level~3 Package Specification for Flux Balance
Constraints, Version~1, \sec{fluxbound-class}.) }

\validRule{fbc-20407}{The attribute \token{fbc:\-value} of a \FluxBound
must be of the data type \token{double}. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{fluxbound-class}.) }

\validRule{fbc-20408}{The value of the attribute \token{fbc:\-reaction}
of a \FluxBound object must be the identifier of an existing \Reaction
object defined in the enclosing \Model object. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{fluxbound-class}.) }

\validRule{fbc-20409}{The combined set of all \FluxBound's with
identical values for \token{fbc:\-reaction} must be consistent. That is
while it is possible to define a lower and an upper bound for a
reaction, it is not possible to define multiple lower or upper bounds.
(References: SBML Level~3 Package Specification for Flux Balance
Constraints, Version~1, \sec{fluxbound-class}.) }

\subsubsection*{Rules for \class{Objective} object}

\validRule{fbc-20501}{A \Objective object may have the optional SBML
Level 3 Core attributes \token{metaid} and \token{sboTerm}. No other
attributes from the SBML Level 3 Core namespace are permitted on a
\Objective. (References: SBML Level~3 Version~1 Core, Section~3.2.) }

\validRule{fbc-20502}{A \Objective object may have the optional SBML
Level 3 Core subobjects for notes and annotations. No other elements
from the SBML Level 3 Core namespace are permitted on a \Objective.
(References: SBML Level~3 Version~1 Core, Section~3.2.) }

\validRule{fbc-20503}{A \Objective object must have the required
attributes \token{fbc:\-id} and \token{fbc:\-type} and may have the
optional attribute \token{fbc:\-name}. No other attributes from the SBML
Level~3 Flux Balance Constraints namespace are permitted on a \Objective
object. (References: SBML Level~3 Package Specification for Flux Balance
Constraints, Version~1, \sec{objective-class}.) }

\validRule{fbc-20504}{The attribute \token{fbc:\-name} on a \Objective
must be of the data type \token{string}. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{objective-class}.) }

\validRule{fbc-20505}{The attribute \token{fbc:\-type} on a \Objective
must be of the data type \token{FbcType} and thus its value must be one
of \val{minimize} or \val{maximize}. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{objective-class}.) }

\validRule{fbc-20506}{A \Objective object must have one and only one
instance of the \ListOfFluxObjectives object. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{objective-class}.) }

\validRule{fbc-20507}{The \ListOfFluxObjectives subobject within a
\Objective object must not be empty. (References: SBML Level~3 Package
Specification for Flux Balance Constraints, Version~1,
\sec{objective-class}.) }

\validRule{fbc-20508}{Apart from the general notes and annotation
subobjects permitted on all SBML objects, a \ListOfFluxObjectives
container object may only contain \FluxObjective objects. (References: SBML
Level~3 Package Specification for Flux Balance Constraints, Version~1,
\sec{objective-class}.) }

\validRule{fbc-20509}{A \ListOfFluxObjectives object may have the
optional \token{meta\-id} and \token{sboTerm} defined by SBML Level~3
Core. No other attributes from the SBML Level~3 Core namespace or the
Flux Balance Constraints namespace are permitted on a
\ListOfFluxObjectives object. (References: SBML Level~3 Package
Specification for Flux Balance Constraints, Version~1,
\sec{objective-class}.) }

\subsubsection*{Rules for \class{FluxObjective} object}

\validRule{fbc-20601}{A \FluxObjective object may have the optional SBML
Level 3 Core attributes \token{metaid} and \token{sboTerm}. No other
attributes from the SBML Level 3 Core namespace are permitted on a
\FluxObjective. (References: SBML Level~3 Version~1 Core, Section~3.2.)
}

\validRule{fbc-20602}{A \FluxObjective object may have the optional SBML
Level 3 Core subobjects for notes and annotations. No other elements
from the SBML Level 3 Core namespace are permitted on a \FluxObjective.
(References: SBML Level~3 Version~1 Core, Section~3.2.) }

\validRule{fbc-20603}{A \FluxObjective object must have the required
attributes \token{fbc:\-reaction} and \token{fbc:\-coefficient}, and may
have the optional attributes \token{fbc:\-id} and \token{fbc:\-name}. No
other attributes from the SBML Level~3 Flux Balance Constraints
namespace are permitted on a \FluxObjective object. (References: SBML
Level~3 Package Specification for Flux Balance Constraints, Version~1,
\sec{fluxobjective-class}.) }

\validRule{fbc-20604}{The attribute \token{fbc:\-name} on a \FluxObjective
must be of the data type \token{string}. (References: SBML Level~3
Package Specification for Flux Balance Constraints, Version~1,
\sec{fluxobjective-class}.) }

\validRule{fbc-20605}{The value of the attribute \token{fbc:\-reaction}
of a \FluxObjective object must conform to the syntax of the SBML data
type \primtype{SIdRef}. (References: SBML Level~3 Package Specification
for Flux Balance Constraints, Version~1, \sec{fluxobjective-class}.) }

\validRule{fbc-20606}{The value of the attribute \token{fbc:\-reaction}
of a \FluxObjective object must be the identifier of an existing
\Reaction object defined in the enclosing \Model object. (References:
SBML Level~3 Package Specification for Flux Balance Constraints,
Version~1, \sec{fluxobjective-class}.) }

\validRule{fbc-20607}{The value of the attribute
\token{fbc:\-coefficient} of a \FluxObjective object must conform to the
syntax of the SBML data type \primtype{double}. (References: SBML
Level~3 Package Specification for Flux Balance Constraints, Version~1,
\sec{fluxobjective-class}.) }