#296 reformat XML Definition string section

[Lucian Smith]

From Andreas:

"The description of the XML definition String at the beginning of a file should be moved to section 3.1 (from Section about SBML container) and be made a subsection.

In this subsection we should also clarify

1. if we prefer (or don't care) about the use of quotation marks vs. apostrophes for argument values (attribute='value' vs. attribute="value")
2. If XML comments can be written before the XML declaration or only right after that and how comments look like.
3. The use of style files and transformations (xls); is it valid SBML to make use of those?"

[Michael Hucka]

I agree with these points.

[Brett Olivier]

1) XML allows both so, for me, SBML shouldn't care.
2) How do XML parsers react to XML comments before the XML declaration? I would tend towards only after it. Other than that, XML only has one comment type and that is valid virtually anywhere in the XML right?
3) I don't quite get this. If the model is serialised to XML then why consider other language families (like XSL) unless there is an issue with parsers not reading the file?

[Michael Hucka]

Regarding #3: XSL is an XML format for expressing transformations. I think what Andreas means is that XML can allow embedding transformations expressed in XSLT (e.g., http://www.w3schools.com/xsl/xsl_choose.asp), but the SBML specification does not disallow incorporating such things

[Andreas Dräger]

Yes, at no place we say if it is valid SBML or not to make use of XSLT, neither is there a word about XML comments.

[Frank Bergmann]

1. should remain unspecified, both are valid ways to use and there is no need to restrict one or favor one over another.
2. comments are invalid before the processing instructions. Other than that xml comments are allowed before the root document. I see no need to restrict that.
3. as for xslt, if xsl instructions are within an sbml document, it will have to be run through an xslt processor to produce valid SBML.

So i would prefer not to restrict the document in those regards. I don't see a need for any additional statements.

[Andreas Dräger]

The aim of this proposed change is not to introduce any restrictions at all. This is only a request to explain unspecified SBML code.

1) The specification uses double quotation marks everywhere and does not state at all if it is also legal to use single quotation marks, neither if both can be mixed (of course not within one attribute, such as attribute="value', but something like attribute1='value1' attribute2="value2"). Would this be valid? There is no information given at all.
2) While basic XML structures, such as Strings etc. are explained, there is no information about what a comment is and where it can be used. This is simply missing in the specification.
3) The specification does not say if it is allowed to insert something like at the beginning of the file or if this is not legal SBML code.

In my opinion, it is important to explain how legal and correct files look like. It is not about restricting anything. Until now, it is simply unclear.

[Frank Bergmann]

i don't think this information is missing, it is part of the definition of XML, and we do reference that one. We couldn't repeat the definition in full in any case. So I would not want to cherry pick some parts of the xml specification and leave out others:

1. yes, this is valid and specified in the xml spec
2. this information is given in the xml spec, clarifying where and when comments can be used (and that if they are used tools reading the xml do not have to provide access to the strings).
3. i think it is quite clear that a document containing processing instructions that would alte the document is perhaps a good template for some, but not an sbml document.

[Nicolas Le Novère]

For 1) and 2) I am with Frank. SBML has to be valid XML, and therefore follows all the rules and restrictions of XML. When SBML imposes more restrictions (e.g. character encoding etc.) we specify them. If something is not specified, the fallback is XML. We repeat the XML definitions of some primitive data types because we build on them afterwards.

For 3) I am a bit puzzled. Where would we put XSL instructions? We define clearly what is SBML. Anything in the document that is not SBML can be completely ignored by SBML processing tools. And within the SBML element, I do not think it is allowed to put XSL instruction anywhere. I think I probably completely missed the point. Tell-me.

Andreas, I agree with your that "it is important to explain how legal and correct files look like." That is different from enumerating everything that is not legal.

[Sarah Keating]

I agree with everything said here - we need to be clear but we do not need to regurgitate the entire XML specification :-)

In Section 3.1 we say

Readers should consult the XML Schema 1.0 specification for the normative definitions of the XML data types used by SBML.

Maybe we need an additional sentence along the lines of:

Unless explicitly stated otherwise SBML conforms to the XML definitionand it's rules relating to the use of syntax, comments etc.

[Andreas Dräger]

Some clarification here so that nobody feels puzzled. I just tried to validate an SBML file after inserting a reference to a local XSL style file as shown here

<?xml version='1.0' encoding='utf-8' standalone='no'?>
<?xml-stylesheet type="text/xsl" href="my_style_file.xsl"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" ...>...</sbml>

The online validator did not complain at all, so this seems to be fine. I just wanted to make sure that inserting a reference to a style file is valid. The specification doesn't say anything about it. However, if the general idea is that what is legal in XML version 1 is also leagal in SBML unless otherwise stated, we can leave it out, I am fine with that.

The main point that I am critizising is that the XML declaration is explained when introducing the SBML container element. We have a general section about XML at the beginning. The SBML container is totally unrelated to the XML header. This should not be at this position in the specification. Again, since every valid XML document must start with this declaration and SBML falls back to XML unless otherwise stated, we could also completely leave this out there. Or we should move it to the place where it belongs: section 3.1.

[Lucian Smith]

Bearing in mind that I created these issues from a series of comments from Andreas, and given that Andreas's last comment is "Mostly, I think this is in the wrong section," I'm marking this issue as a duplicate of https://sourceforge.net/p/sbml/sbml-specifications/298/. The issues discussed here are still relevant (i.e. we should be explicit in saying that the XML spec is the default), but I think folding it into the other tracker item will help clarify what to do next.