OMEX release candidate 1

[Nicolas Le Novere]

Dear Colleagues,

Please find attached the first release candidate of the OMEX specification. The differences with the draft 1 are minors and correspond to the discussions held on the list and at HARMONY 2015. This version is stable. The only changes in the specification will be clarifications, with no change of classes or syntax.

Best regards

--
Nicolas LE NOVERE, Babraham Institute, Babraham Campus Cambridge, CB22 3AT
Tel: +441223496433 Fax: +441223496034 Mob:+447833147074 twitter:@lenovere
Skype:n.lenovere, n.len...@gmail.com, ORCID: 0000-0002-6309-7327
http://lenoverelab.org/, http://lenoverelab.org/perso/lenov/

[Nicolas Le Novere]

That was HARMONY 2014 of course, not 2015 ;-)

[Felix Winter]

Hi everyone,

I just read the current Release Candidate of the COMBINE archive specification.
If I understand the current state of the document correctly, there is still time
to suggest changes which could improve clarity.  Please find my remarks below.
As english is not my first language I may be wrong on some items, but I hope
that at least some of these remarks are valuable.

Best, Felix

Suggestions with respect to clarity:

Information which is not related to the COMBINE archive itself but refers to
other COMBINE specifications could be removed from the spec:
1. The information that "these conventions are identical to the conventions used
in the other COMBINE specification documents" may be correct, but does not add
any information useful to understand the COMBINE archive specification. I would
therefore suggest to remove it.
2. The AbstractClass definition is explained in the section on "Documents
conventions" (Page 3, line 7) but never used throughout the document. At least,
I couldn't spot any appearance. If this is really the case there is no need to
explain it in the beginning.
3. The information that the terms take from the vCard Ontology differ from the
terms described in the SBML specification is only important for people aquainted
with the details of SBML. For readers without this background this information
is confusing. I would therefore suggest to either remove line 12 to 19 on page 9
without any replacement, or to replace them by a footnote which states just:
"Note: These terms are different from the terms used in the SBML Level.Version
vCard specification". Right now no information on the level or version of the
SBML specification is given and the information may become incorrect after
future releases of the SBML spec.

On the other hand, when the reader is referred to other specifications for more
information, the specific document the authors had in mind should be referenced.
E.g. line 21, page 3 : "For other matters involving the use of UML and XML, we
follow the conventions used in other COMBINE specification documents." Here a
reference to a particular document would be helpful, as otherwise the reader is
left to wonder where to look for more information. One information I was looking
for was the description of the way optional attributes are declared in the UML
diagram. The COMBINE archive specification uses "attribute type (optional)"
(Fig1, Page 6), while the SBML spec uses "{use="optional"}". The SED-ML spec and
the SBOL spec have no way to indicate optional attributes in the UML-diagrams
and some other COMBINE specifications don't use UML at all.

Lack of clarity about what is allowed or not:
On page 7, line 22, it is declared that the last line in the example give above
should not be used. I understand the previous sentence in a way that this
example is considered invalid. If this is indeed the case, it should be stated.
Right now, it reads like the use of purl URIs for media types where an
Identifiers.org URI is available is not forbidden but discouraged.

Repetition of information:
The information in the first sentence of page 8 is just a repetition of the last
sentence on page 7: I would suggest to replace both sentences by the
following:"If a software is not able to interpret the format of a file for which
the master attribute is set, it can safely ignore the master attribute." or
something like this.

Error in the description of the illustrative example (Section 4)
Page 10, line 3: "One of these entries is the OmexManifest itself, ..." This
seems to be wrong. If I got the discussion on the combine-archive mailing list
right, then the " location="." " does _not_ refer to the manifest, but to the
archive itself. (See email from Nicolas Le Novère at Apr. 24) The first entry is
therefore _not_ the OmexManifest.


Consistency throughout the document:
mixture of lower case and upper case "A" in the word "Archive": COMBINE archive
(Page 4, line 8) vs. COMBINE Archive (Page 4, line 20)
mixture of lower case and upper case for the word "manifest", e.g. in the
caption for Fig 1.
inconsistent use of parentheses to mark references: No parentheses for
Wikipedia, PKWARE Inc, Soiland-Reyes, ... parentheses for Waltemath et al, Biron
ald Malhotra, Freed and Borenstein, ...
inconsistent use of "Media type" (Page 10, line 5) and "Internet Media type"
(everywhere else) for the same concept. I would suggest to always use "Internet
Media type".
inconsistent use of "data": (Page 2, line 11 and page 5, line 31). In the first
occurance, "data" does not include the models itself, in the second occurance it
does. Also, most of the time the files inside the archive are referred to as
"files", not as "data files". I would suggest to remove the word "data" from
page 5, line 31.

Possible typos:
Page 6, line 12: names -> named
Page 6, line 21: missing dot at the end of the sentence.
Page 7, line 2: Wrong typeface for "is required" after "string"
Page 8, line 24: tagges -> tagged
Page 9, lines 9 and 14: Footnote 4 has been defined two times with different
content.
Page 9, line 21: too -> to

Minor style suggestion (very subjective :) ) :
Page 5, line 2: "expound" is quite an unusual word for a technical document. I
personally would use it only with respect to religious scriptures or
philosophical ideas. Maybe "explain" does a better job?
Page 10, line 4: "Additionally ...". As there are only two things in the
enumeration, I would suggest to replace the comma with an "and".

--

Dipl. math. oec. Felix Winter

ASD Advanced Simulation & Design GmbH
Erich-Schlesinger-Str. 50
18059 Rostock
Germany

fon     +49 (0)381 4403270
fax     +49 (0)381 4403277
web     www.asd-online.com
email   felix....@asd-online.com
 
• Geschäftsführerin: Dr. Catrin Bludszuweit-Philipp •
• Amtsgericht Rostock • HRB Nr. 6897 • USt.-IdNr. • DE812131740 •
• Bankverbindung: OSPA Rostock • BLZ 130 50000 • Konto-Nr. 230000401 •

The information transmitted is intended only for the person or entity to which
it is addressed and may contain confidential and/or privileged material. Any
review, retransmission, dissemination or other use of, or taking of any action
in reliance upon, this information by persons or entities other than the
intended recipient is prohibited. If you received this in error, please contact
the sender and delete the material from any computer.