Validation of objects

Overview

In SBML there are requirements that must be met in order for the document to represent a valid SBML model. LibSBML provides a checkConsistency function that performs a number of validation tests on a fully constructed SBML document. However, this function is not always applicable to a model under construction.

Example of the issues

1) A user is contructing a model and wishes to check the consistency of a Species object. Firstly, the checkConsistency function must be called on an SBMLDocument, so unless the Species has been already been added to a Model within a SBMLDocument, the function is not available. Secondly, unless any other SBML objects referred to by the Species have also been added, the checkConsistency function will not provide accurate information. For example, a Species is constructed as follows.

Species * s = new Species();

int i = s->setId("4dd");

It has not been added to a Model within a SBMLDocument and so the checkConsistency function cannot be called. The Species s is not valid, since a species must have the compartment attribute set, but in libSBML-3 there is no way to determine this.

2) In fact, in the above example, the id attribute of the Species would not have been set, as the syntax is invalid. The user could determine the fact that the id had not been set and why by examining the return value of the setId function. However, in libSBML-3, there is no functionality that allows the user to check the syntax of intended attribute values.

Solution

In order to tackle the first issue, each SBML component object has two new functions:

bool hasRequiredAttributes();

bool hasRequiredElements();

The hasRequiredAttributes function returns true if all the attributes that are required according to the SBML specification have been set, false otherwise. In certain cases, SBML component objects require additional elements. For example a FunctionDefinition requires a math element. The hasRequiredElements function returns true if the object has all required elements, false otherwise.

Species * s = new Species();
s->setId("s");

bool finished = s->hasRequiredAttributes();

s->setCompartment("c");

finished = s->hasRequiredAttributes();

The value of finished after the first call to hasRequiredAttribues will be false and after the second call it will be true.

The second issue has been addressed by adding a static class SyntaxChecker.

class LIBSBML_EXTERN SyntaxChecker
{
public:

  /**
   * Predicate returning @c true or @c false depending on whether the
   * argument string conforms to the SBML type SId. 
   */  
  static bool isValidSBMLSId(std::string sid);

  
  /**
   * Predicate returning @c true or @c false depending on whether the
   * argument string conforms to the XML 1.0 type ID. 
   */  
  static bool isValidXMLID(std::string id);


  /**
   * Predicate returning @c true or @c false depending on whether the
   * argument string conforms to the SBML type UnitSId. 
   */
  static bool isValidUnitSId(std::string units);


  /**
   * Predicate returning @c true or @c false depending on whether the
   * argument XMLNode represents XHTML that conforms to the 
   * requirements of the SBML specification.
   */
  static bool hasExpectedXHTMLSyntax(const XMLNode * xhtml, 
                                     SBMLNamespaces * sbmlns = NULL); 
};

This allows the user to check the syntax of id, units, metaid and notes attributes before assigning values.