by Ben Bornstein (updated by Akiya Jouraku)

In addition to using the SBML Online Validator web interface, you can also call the validator over the web from your own program or script. There are a number of reasons you might want to do this. Since "always on" Internet connectivity is becoming ubiquitous (especially in academic settings), remote validation may be the quickest and easiest way for your simulator to check an SBML model for syntax and consistency. Even if you choose not to call the validator every time your program reads an SBML file, it might be nice to give your users the option. In another scenario, you may want to run the validator over a large set of SBML files in batch mode. If for some reason, you cannot or do not wish to run the validator remotely, you can bundle it in your own program by using libSBML.

The Online Validator is called by submitting either an HTTP GET or POST command directly to the URL http://sbml.org/validator/. This isn't as complicated as it may sound. It's much simpler than using so-called "web service" protocols like SOAP or XML-RPC. When calling the validator you can specify that validation results be returned in one of several formats, including:

• XML
• XHTML
• Javascript Object Notation (JSON)
• Plain text

In the tutorials below, we provide full example programs that show you how to call the Online Validator from:

• The command line
• GNU Emacs
• Python
• Java

We'll start by calling the Online Validator from the command-line with a program called curl. Since Curl is a high-level tool, it hides a few of the details we need to worry about in Python and Java.

The Command Line

The curl program is a command-line tool for transferring files to and from URLs. It supports many protocols including Telnet, FTP, and HTTP. Most Linux, Mac OS X (Tiger, Leopard), and Windows (Cygwin) systems come with curl already installed. For our purposes the curl syntax is straightforward:

This calls the SBML validator by setting three form variables (the -F option): file, output, and offcheck. The at symbol (@) instructs curl to read the value of the variable from the filename that follows. The output parameter indicates the format of the validation results and the offcheck parameter indicates which consistency check will be disabled ('u' disables the units check).

You can ask the validator to validate files located anywhere on the Internet by passing a URL instead of a file. For example, try the following:

The validator will indicate there were no error (i.e. the SBML file is valid) by returning the following XML:

Note: If instead you see:

Make sure the validator URL ends in a slash (/): http://sbml.org/validator/.

Let's validate an SBML file with some errors:

Although the XML has been wrapped for readability, this output is still a bit hard to read. Let's ask the validator to distill it to plain text:

This output (still wrapped for web page display) is more readable. There are two errors, one on line 15 and the other on line 16. Compare the XML and text outputs to the XHTML output.

As described in the first example, you can choose which consistency checks will be disabled. To disable one or more consistency checks, pass the comma-separated characters to the offcheck parameter. Available characters are as follows:

For example, the following command will disable unit consistency check (u), modeling practices check (p), and SBO consistency check (s).

That's all there is too it! Here are some more curl commands to experiment with:

Finally, you can use curl to write a validateSBML.sh shell script:

1. #!/bin/sh
3. ##
4. ##usage: validateSBML.sh [-h] [-d opt1[,opt2,...]] [-o output] filename.xml
5. ## validateSBML.sh [-h] [-d opt1[,opt2,...]] [-o output] http://.../filename.xml
6. ##
7. ## Validates the SBML document given by filename.xml using the
8. ## SBML.org Online Validator.
9. ##
11. # Print the usage statement at the top of this program and available options.
12. usage() {
13. synopsis=`grep "^##" $0 | sed 's/##//'`
14. cat << EOF
15. $synopsis
17. options:
19. -o output
20. Specify an output format.
22. text : plain text (Default)
23. xml : XML
24. xhtml : XHTML
25. json : JavaScript Object Notation
27. -d opt1[,opt2,...]
28. Disable the given consistency check options.
29. The options are given as comma-separated characters.
30. Each character is one of the followings:
32. u : disable the units consistency check
33. g : disable the overall SBML consistency check
34. i : disable the identifier consistency check
35. m : disable the MathML consistency check
36. s : disable the SBO consistency check
37. o : disable the overdetermined model check
38. p : disable the modeling practice check
40. -h Print this usage.
41. EOF
43. }
45. validator_url='http://sbml.org/validator/'
46. output='text'
48. # Parse the command-line arguments.
49. while getopts d:o:h opt
50. do
51. case $opt in
52. d)
53. offcheck="-F offcheck=$OPTARG"
54. ;;
55. o)
56. output=$OPTARG
57. ;;
58. *)
59. usage
60. exit
61. ;;
62. esac
63. done
64. shift `expr $OPTIND - 1`
66. # Exit if no SBML file given.
67. if [ $# -lt 1 ]; then
68. usage
69. exit
70. fi
72. filename=$1
74. if echo $filename | grep -q '^http://'; then
75. src="url=${filename}"
76. else
77. src="file=@${filename}"
78. fi
80. curl -F output=${output} -F ${src} ${offcheck} ${validator_url}

GNU Emacs

Most modern GNU Emacs installations come with PSGML mode for editing XML files. When this mode is active (e.g. when you load an XML file), you can validate the XML by issuing the command M-x sgml-validate (C-c C-v). To validate SBML files, simply override the PSGML validate command to call the Online Validator (the validator's plain text output format is understood by Emacs):

1. Copy validateSBML.sh from the Command Line Tutorial to a directory on your local machine (e.g. ~/emacs)

2. Add the following to your .emacs initialization file:

   (setq sgml-validate-command "~/emacs/validateSBML.sh")

Python

If you've already read through the Command Line Tutorial, you're in good shape. Things are only slightly more complicated in Python (and Java). Both languages provide libraries for communicating with web servers, but you need to do a little work to send data to the server in the correct multipart post format. Fortunately, we've done the work for you. The Python function encode() encodes both a dictionary of name-value pairs and the contents of a file in the appropriate format:

1. import random, string
3. def encode (parameters, filename=None):
4. """encode(parameters, filename=None) -> (boundary, data)
6. Encodes the contents of validator parameters (a Python dictionary)
7. and filename (assumed to XML) into a format suitable for uploading
8. to the SBML.org validator via an HTTP POST.
10. Adapted from the Python Cookbook:
11. - http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/146306
12. """
13. boundary = '<<' + ''.join([random.choice(string.digits) for n in range(30)])
14. lines = [ ]
16. if filename is not None:
17. format = 'Content-Disposition: form-data; name="file"; filename="%s"'
18. lines.append('--' + boundary)
19. lines.append(format % filename)
20. lines.append('Content-Type: text/xml')
21. lines.append('')
23. stream = open(filename)
24. lines.extend( map(string.rstrip, stream.readlines()) )
25. stream.close()
27. if parameters is not None:
28. for (name, value) in parameters.items():
29. lines.append('--' + boundary)
30. lines.append('Content-Disposition: form-data; name="%s"' % name)
31. lines.append('')
32. lines.append( str(value) )
34. lines.append('--' + boundary + '--')
35. lines.append('')
37. return (boundary, string.join(lines, '\r\n'))

All that's left is to write a function that uses encode() and Python's httplib to make an HTTP POST request to the validator.

1. import httplib
3. def validateSBML (filename, parameters=None):
4. """validateSBML(filename, parameters=None) -> string
6. Validates the given SBML filename (or http:// URL) by calling the
7. SBML.org online validator. The results are returned as a string
8. whose format may be controlled by setting parameters['output'] to
9. one of: 'xml', 'xhtml', 'json', 'text' (default: xml).
10. """
11. if parameters is None:
12. parameters = { }
14. if filename.startswith('http://'):
15. parameters['url'] = filename
16. filename = None
18. parameters.setdefault('output', 'xml')
20. (boundary, body) = encode(parameters, filename)
21. headers = { 'Content-Type': 'multipart/form-data; boundary=%s' % boundary }
23. http = httplib.HTTPConnection(HOST)
24. http.request('POST', URL, body, headers)
26. return http.getresponse().read()

You can download validateSBML.py which includes both encode() and validateSBML() along with some additional code to run the Python script from the command-line.

Java

If you've already read through the Command Line Tutorial, you're in good shape. Things are only slightly more complicated in Java (and Python). Both languages provide libraries for communicating with web servers, but you need to do a little work to send data to the server in the correct multipart post format. Fortunately, we've done the work for you with the Java class MulitpartPost:

1. import java.net.URL;
2. import java.net.URLConnection;
4. import java.io.File;
5. import java.io.FileInputStream;
6. import java.io.InputStream;
7. import java.io.OutputStream;
8. import java.io.IOException;
10. import java.util.Random;
13. /**
14. * Performs a Multipart HTTP post to the given URL. A post operation
15. * is started with the creation of a MultipartPost object. Post
16. * parameters are sent with writeParameter() and may be eithier
17. * strings or the contents of an XML file. A post is finished by
18. * calling done() which returns an InputStream for reading the servers
19. * response.
20. *
21. * NOTE: This class is meant to communicate with the SBML.org online
22. * validator. As such, it assumes uploaded files are XML and always
23. * sends a Content-Type: text/xml.
24. */
25. class MultipartPost
26. {
27. public MultipartPost (String url) throws IOException
28. {
29. Random random = new Random();
31. connection = ( new URL(url) ).openConnection();
32. boundary = "<<" + Long.toString(random.nextLong(), 30);
33. String type = "multipart/form-data; boundary=" + boundary;
35. connection.setDoOutput(true);
36. connection.setRequestProperty("Content-Type", type);
38. stream = connection.getOutputStream();
39. }
41. public InputStream done () throws IOException
42. {
43. writeln("--" + boundary + "--");
44. writeln();
46. stream.close();
48. return connection.getInputStream();
49. }
51. public void writeParameter (String name, String value) throws IOException
52. {
53. writeln("--" + boundary);
54. writeln("Content-Disposition: form-data; name=\"" + name + "\"");
55. writeln();
56. writeln(value);
57. }
59. public void writeParameter (String name, File file) throws IOException
60. {
61. String prefix = "Content-Disposition: form-data; name=\"file\"; filename=";
63. writeln("--" + boundary);
64. writeln(prefix + '"' + file.getName() + '"');
65. writeln("Content-Type: text/xml");
66. writeln();
68. InputStream source = new FileInputStream(file);
69. copy(source, stream);
71. stream.flush();
72. source.close();
73. }
75. void copy (InputStream source, OutputStream destination) throws IOException
76. {
77. byte[] buffer = new byte[8192];
78. int nbytes = 0;
80. while ((nbytes = source.read(buffer, 0, buffer.length)) >= 0)
81. {
82. destination.write(buffer, 0, nbytes);
83. }
84. }
86. void writeln (String s) throws IOException
87. {
88. write(s);
89. writeln();
90. }
92. void writeln () throws IOException
93. {
94. write('\r');
95. write('\n');
96. }
98. void write (char c) throws IOException
99. {
100. stream.write(c);
101. }
103. void write (String s) throws IOException
104. {
105. stream.write(s.getBytes());
106. }
109. URLConnection connection;
110. OutputStream stream;
111. String boundary;
112. }

All that's left is to write a function that uses MultipartPost to make an HTTP POST request to the validator:

1. import java.io.File;
2. import java.io.InputStream;
3. import java.io.IOException;
5. import java.util.HashMap;
6. import java.util.Iterator;
7. import java.util.Map;
8. import java.util.NoSuchElementException;
11. /**
12. * SBMLValidator is simply a container for the static method
13. * validateSBML(filename, parameters).
14. */
15. class SBMLValidator
16. {
17. /**
18. * Validates the given SBML filename (or http:// URL) by calling the
19. * SBML.org online validator. The results are returned as an
20. * InputStream whose format may be controlled by setting
21. * parameters.put("output", ...) to one of: "xml", "xhtml", "json",
22. * "text" (default: xml).
23. *
24. * @return an InputStream containing the validation results.
25. */
26. public static InputStream validateSBML (String filename, Map parameters)
27. throws IOException
28. {
29. if (parameters.get("output") == null)
30. {
31. parameters.put("output", "xml");
32. }
34. MultipartPost post = new MultipartPost("http://sbml.org/validator/");
35. InputStream result = null;
37. if (filename.startsWith("http://"))
38. {
39. post.writeParameter("url", filename);
40. }
41. else
42. {
43. post.writeParameter("file", new File(filename));
44. }
46. try
47. {
48. Iterator iter = parameters.keySet().iterator();
50. while ( iter.hasNext() )
51. {
52. String name = (String) iter.next();
53. String value = (String) parameters.get(name);
55. post.writeParameter(name, value);
56. }
57. }
58. catch (NoSuchElementException e)
59. {
60. e.printStackTrace();
61. }
63. return post.done();
64. }
65. }

You can download validateSBML.java which includes both MultipartPost and SBMLValidator.validateSBML() along with some additional code to run the Java program from the command-line.

Validator XML Output

The XML output produced by the Online Validator is its most basic format. All other output formats (XHTML, JSON, and plain text) are derived from the XML through XSLT scripts. The format is:

The C printf-style format specifiers denote: %s - string, %u - unsigned integer. The SBML filename that was validated (sans any directory or path information) and the satuts of validation options are always given. Next the status of the validation result is given. The status is either 'no-errors', 'warning', 'error', or a single critical error. When the status is a 'warning' or 'error', one or more corresponding problems are reported.

Below we briefly explain each status of the validation result:

Problems :

Each <problem> has a category, a code, and a severity that uniquely identify it. The category is one of the following strings:

• Internal
• System
• XML
• SBML
• SBML Level 1 compatibility
• SBML Level 2 Version 1 compatibility
• SBML Level 2 Version 2 compatibility
• SBML Level 2 Version 3 compatibility
• General SBML consistency
• Identifier consistency
• Units consistency
• MathML consistency
• SBO consistency
• Overdetermined model
• Modeling practice

Problem severities range from zero to three:

• 0. Advisory
• 1. Warning
• 2. Error
• 3. Fatal

The position of a problem within a document is located by line and column (starting at 1). The <message> element contains the message itself and <excerpt> quotes the line within the document where the problem occurred. Since both of these elements may contain content that could be misinterpreted as XML (e.g. <, >, ', ", etc.) they are always escaped by <![CDATA[ ... ]]> sections.