[vodml] WD comments

[Gerard Lemson]

HI Mark
I have followed up on your comments.
Please see comments below and latest version of the VO-DML docs and vo-dml-v1.0.xsd on volute at gavo.

I also updated the IVOA profile used in the magicdraw version of the sample Source data model in vo-dml/models/source/SOurceDM.xml.

> 
> -----Original Message-----
> From: dm-bounces at ivoa.net [mailto:dm-bounces at ivoa.net] On Behalf Of
> CresitelloDittmar, Mark
> Sent: Tuesday, January 19, 2016 12:57 PM
> To: Data Models mailing list <dm at ivoa.net>
> Subject: [vodml] WD comments
> 
> Gerard/DMers,
> 
> 
> With the couple element pattern restriction items which have come up recently
> and my experience working with the xslt script for Modelio, I decided to give the
> doc another full read/review.  Below are some comments.. many I believe have
> been mentioned before on an earlier draft.  Most are typographical or
> consistency items between text and figures.
> 
> 
> VO-DML document: V1.0-20151007
> 
> 
> pg 15:Figure 1
> 
>   + Contraint is not an extension of ReferableElement
> 
>   + missing SubsettedRole
> 
I updated the diagram, including more things I noticed that were out of date.

> 
> pg 18:Section 4.1.1
> 
>   + pattern shown here (and reported by validator), does not match that
> 
>      shown in the VO-DML/Schema snippet for "ElementID" on pg 19
> 
>       "[\w\._-]+"  vs "[\w\./_*]+"
> 
In schema use VODMLID (iso ElementID), corresponding to first of these options. Already mentioned in text, but not everywhere. XML Schema snippet was updated.

TODO check that all schema snippets are in sync with actual schema!

> 
> pg 18:Section 4.1.2
> 
>   + already reported separately, the pattern enforced by the validator
> 
>       does not match the definition of xsd:NCName, namely by the omission
> 
>       of '.' and '-' characters... possibly others
> 
> 
>       It would be helpful to have a pattern or short description here.
> 
Indeed, name is no longer just an NCName but follow the pattern defined in the VODMLName type in the XML schema.

> 
> pg 18:Figure 4
> 
>   + description ends mid-sentence.
> 
Reference to Appendix C added.
> 
> pg 18: footnote.. 'will be left out in from now on' => 'will be left out from now
> on'
> 
Check!
> 
> pg 20: VO-UML
> 
>   + 'This type has not explicit counterpart in VO-UML,'  s/b
> 
>      ' This type has no explicit counterpart in UML,'
> 
No, this must be VO-UML, which plays the role of a UML Profile. 

> 
> pg 20: VO-DML/Schema
> 
>   + pattern shown here '[\w_-]+:[\w\./_*]+'
> 
>      a) indicates a pattern for the 'prefix', which is not stated in the Model.name
> description
> 
>          I'm not sure what the validator enforces on this one.
> 
>      b) the ID pattern matche the previous schema snippet, not Section
> 4.1.1/validator pattern.
> 
> 
Updated the suffix part of the pattern to correspond to the VODMLID pattern.
Indeed the prefix should be same as in ModelName, which I have updated to be
[a-zA-Z][\w_-]* in schema and in doc. Added that here as well.

> 
> pg 22: VO-DML/XML
> 
>   + I'll mention it once here, but several of the XML examples don't include the
> closing tag, which they probably should, for completeness.. makes it clear that
> there is nothing missing.
> 
I don't know if I agree. I try to keep the snippets as small as possible, focusing on the core concept that is being illustrated.
To me the ... s indicate that things are missing, which includes (obviously) the closing tags if those are not there.
But I am happy to be convinced otherwise.
> 
> pg 22: Section 4.4.1
> 
>   + does not mention the pattern restriction shown above in the Schema snippet
> 
Added this.

>   + also, subsequent Schema snippet on pg 25 shows Model.name has type
> "ModelPrefix"
> 
>      which does not exist in the document.
> 
Indeed, should be ModelName. Fixed this.
> 
> pg 24: Figure 7
> 
>   + profile tags for model stereotype do not match text and what is being used in
> the IVOA_UML_Profile ('title', 'version', 'authors', previousVersion' )
> 
Updated my MagicDraw profile to conform to the properties one can assign to a model in VO-DML and created new screenshot. 
Should be reflected in the MD template model we're planning to create.
Btw, lastModified is (I hope) generated automatically in my xmi2vo-dml generation script, and is therefore not really necessary to add tho the UML template/profile.
> 
> pg 25: VO-DML/Schema
> 
>   + above mentioned.. Model element 'name' has type 'ModelPrefix' which is not
> in the document.
> 
Changed it to ModelName, which is not in document, but exists in XSD.
> 
> pg 26: Section 4.5.3
> 
>   + url type 'anyURL' is 'anyURI' in schema snippet of page 27
> 
Fixed.
> 
> pg 27: Figure 8
> 
>   + modelimport stereotype tags do not match text and IVOA_UML_Profile.
> 
>      (version, url, documentationURL)
Fixed screenshot.
> 
>   + description states 'possible tags'.. isn't this defining the tags?
> 
Yes. Updated caption. Please check.
> 
> pg 32: Section 4.9.1
> 
> pg 33: Section 4.10
> 
>   + could use some clarification of the pattern restriction in light of the list
> discussion.
> 
Added text.
> 
> pg 35: Figure 12
> 
>   + object has stereotype <<dataType>>, while description shows <<datatype>>
> 
Fixed.
> 
> pg 39: VO-DML/Schema
> 
>   + '... and multiplicity that defines whether.'   ends mid-sentence.
> 
Fixed.
> 
> pg 39: Section 4.14.1
> 
>   + element name == 'semanticconcept', but text references 'topconcept'.
> 
>      If I'm reading this right, the word "topconcept" is referring to this element
> name "semanticconcept", and not the 'topConcept' attribute on the
> SemanticConcept type.
> 
Should be semanticconcept. Fixed it.
> 
> pg 40: VO-DML/Schema
> 
>   + related to above, the element name should be 'semanticconcept'
> 
> 
> pg 42: top of page
> 
>   + large space in final sentence.
> 
Fixed.
> 
> pg 61: Appendix C
> 
>   + 'for generating such unique [word missing], and the following grammar is
> built starting from [such s/b 'this'?] previous attemp'
> 
> 
Fixed


Note, in footnote 33 we state that an attribute with a semanticcocept MUST have datatype=ivoa:anyURI. Ok to keep this in the footnote? And note to self to add this in the schematron validator.

Note, in the last paragraph of 3.3 we state that different fonts are used to identify occurrence of same concept in different representations of VO-DML: language, schema and VO-UML. Should check that we stick to this in the actual text.


Cheers
Gerard