#339 Clarify the use of namespaces for annotations

[Sarah Keating]

This was reported via libsbml-development:

For me the specification reads like the namespaces MUST be on the local annotation elements.
It nowhere states that the namespace can be defined on some parent element or the xml document for the annotation.

[1]
The following reads for me
L3V1 p15 L1f
"In XML, the Annotation content type is any, allowing essentially arbitrary well-formed XML data content."
like the XML data on annotation should be a well-formed xml snippet which I can parse in isolation with an XML parser.
This is not the case if I need the global namespaces of SBML. So the annotation is only well-formed in the context of the full XML document and not in isolation.

[2]
All examples in the specification clearly define the namespaces on the annotation xml, nowhere is any clue that the namespaces can be on the xml document.

[3]
L3V1 p15 L23ff
The key point of the example above is that application-specific annotation data are entirely contained inside
a single top-level element within the SBML annotation container.

entirely contained includes for me the namespaces, otherwise only part of the annotation data is in the single top-level element of annotation, and parts, i.e. the namespaces, are somewhere else.

It would be nice if this could be clarified in the specification.

I personally would prefer the interpretation that namespaces must be on the local xml annotation. Otherwise the xml annotation is not self-consistent, but one must always inject the namespaces to work with them in isolation.

=====================

We obviously need to decide how to clarify this issue; or indeed whether it was the intention that an annotation did declare all of it's namespaces and that the failure to report this is a libsbml bug.

I do recall people wanting to be able to put all annotation namespaces on the top-level as it meant that for the miriam-rdf annotations they did not need to be decalred every time.

[Lucian Smith]

Declaring namespaces is an XML-level rule, and it would be weird (in my mind) to override it and make it more restrictive. We could call it out as a best practices issue, though. I'll work up some text along these lines so we can look at it.

[Nicolas Le Novère]

I concur with Lucian

[Andreas Dräger]

I agree. AFAIK, SBML follows the rule what is allowed in XML is also allowed in SBML unless explicitly stated otherwise. A clarification in the sentence quoted under point [1] should solve the issue.

[Brett Olivier]

I agree with Lucian, a simple clarification works for me.

[Sarah Keating]

Fine by me - but also an example where we dont list the annotation namespaces and just note that these have been decalred elsewhere.

[Lucian Smith]

I added the following text, right after the bit about 'must use XML namespaces':

"The namespace may be declared on the root element using that namespace, or on any XML element containing it, up to and including the root <sbml> object itself."</sbml>

Then I added a new example right after the first one:

Similarly, if the mysim namespace was declared in a containing element such as the <sbml> object, the annotation might look like:
<annotation>
<mysim:molecule mysim:weight="18.02" mysim:atomcount="3">
</mysim:molecule></annotation></sbml>

[Lucian Smith]

This change has been committed to SVN, and will appear in the second release candidates of l3v1r2 and l3v2. It has also been added to http://sbml.org/Documents/Specifications/SBML_Level_3/Version_1/Core/Confirmed_issues_in_the_Level_3_Version_1_Core_Specification

[Lucian Smith]

With the release of L3v2, this issue is now resolved.