TWiki> IVOA Web>IvoaResReg>VOResource11RFC (2018-07-27, MarkCresitelloDittmar) EditAttach

VOResource 1.1 Proposed Recommendation: Request for Comments

VOResource 1.1 is an update to the basic schema for resource records in the VO; the most salient rationale is improved interoperability with DataCite (but in total there's 1 1/2 pages of changes).

The latest edition of VOResource 1.1 can be found at:

Incremental updates (possibly referenced by revision numbers below) will be made available through the Volute document directory; a formatted version as of the current commit should be available at http://docs.g-vo.org/VOResource.pdf.

Reference Interoperable Implementations

VOResource 1.1 takeup until May 2017 has been discussed in a talk at the Shanghai interop.

Features relevant for discovery can be tried out in the GAVO-operated RegTAP registries, which already implement a draft version of RegTAP 1.1; TAP access URL is http://reg.g-vo.org/tap.

Implementations Validators

VOResource 1.1 records can be validated using standard XSD tools.

Support for VOResource 1.1 validation in the RofR should come soon; this will probably not yet include validation of vocabulary-constrained elements, but this should be easily addable.

Comments from the IVOA Community during RFC/TCG review period: 2017-06-01 through 2017-07-15

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

  • Sample comment by WikiName
  • My comment is about the connections between DataCite and the new VOResource schema. Is the goal that one should be possible to map between the two standards? One limitation that I have noticed with DataCite and compatibility with astronomy data resources is with the relatedIdentifiers type. In DataCite, a relatedIdentifier must have a relatedIdentifierType associated with it, which come from a fixed list. In VOResource there is the vr:relationship type, which has a relatedResource element that appears to always be a vr:ResourceName, which as I understand it is always an IVOA identifier URI. This represents an incompatibility with DataCite in two ways. One, an IVOA identifier URI is not one of the types in the relatedIdentifierType enumeration in DataCite. Two, DataCite allows a wider range of types of identifiers that may be related to the current described resource. Has there been any thought of trying to get astronomy-specific identifier types into the allowed list for DataCite or of expanding the types of identifiers that can be specified as a relatedResource for the vr:relationship type in the VOResource schema? -- SarahWeissman - 2017-06-07

TCG Chair & Vice Chair

Applications Working Group

I approve this document. The substance of the changes look fine.

I have a couple of editorial nit picks:

  • In the last sentence of 2.3.2, was "vr:WebService" supposed to be mentioned twice?
    • No -- one of them should have been vr:WebBrowser and now is. -- MarkusDemleitner - 2018-02-01

  • In a holdover from the previous version, the second to last paragraph of 3.1 has "(?)" in the sentence below. It seems to indicate a lingering open question, but should probably just be removed.
    • That's a placeholder for the eventual reference to the XML versioning note, which is still in the pipeline (but now approved by all WGs, so I hope it's a matter for a few weeks (i.e., happens before the next Exec session) until it's in ADS) -- MarkusDemleitner - 2018-02-01
-- TomDonaldson - 2018-01-31

Data Access Layer Working Group

We strongly recommend this specification well designed an fully useful for DAL service implementers and applications willing to access them. However it could be interesting that authors take into account following remarks.

[Content problems addressed in Volute rev. 4777, rephrasing in Volute rev. 4778 -- MarkusDemleitner - 2018-02-27]

  • Content problems:
    • Acknowledgments "The vocabulary management closely follows what Norman Gray has developed for DataLink". ---> this is fuzzy. Should have a reference to appropriate DataLink section (or DataLink semantics page and thanking Norman for his input after that.)
    • Section 1 : The paragraph on DataCite is unclear to us : where do we align vocabularies ? It should be written where it really applies in the text.
      • The elements for which this is relevant have already mentioned DataCite, but I've put in "the alignment of the vocabularies for date roles and relationships" in the introduction, too. -- MarkusDemleitner - 2018-02-27
    • Section 2 : The two last paragraph are hard to use in practice. What kind of namespaces should be used ? Maybe an example would clarify this ?
      • Umm -- what text exactly does this reference? -- MarkusDemleitner - 2018-02-27
    • 2.2.5 : The three "examples" should be fully developed (including associated xml code) to be better understood.
      • Since the XSD code discussed here is actually part of the specification I'd rather save the space and XML nerve (XSD is verbose, and all XML mentioned here would be about two pages if unabridged). Also, this is v1.0 text. I don't think we've had questions on this on the mailing list, so perhaps improvement of this section can wait until we refactor the prose in a future version. -- MarkusDemleitner - 2018-02-27
    • 3.1.4 . It seems to us (looking at the xml schema piece at the end of the subsection) that in second paragraph "Validation" instead of "ValidationLevel" requires the validatedBY attribute.
      • No, it's validationLevel, indeed. It's just validationLevel's type that's called vr:Validation. Retrospectively, we probably shouldn't have done it this way, but it's been REC for about 10 years, so there's no way we can fix it now. -- MarkusDemleitner - 2018-02-27

  • Rephrasing :
    • Abstract : This schema is primarily intended to support metadata exchange between interoperable registries and resource discovery inside them (the original phrasing looked very odd to us ?
    • Note in 1 : The name "VoResource" has had two meanings in practice within IVOA discussions.
      • Well, when I looked at that sentence I figured one can just write present tense here: "The term ``VOResource'' is used to denote two different concepts within the IVOA community" -- MarkusDemleitner - 2018-02-27
    • 1.1 architecture : "generic definitions for data services". (Plante and Stébé)
      • I'd argue that the "for the description of..." in the opening text is still governing the phrase here; if we started to put in more nouns, w'e at least have to go on with "description of TAP services", and that would become clumsy. So, I've left the text as is -- MarkusDemleitner - 2018-02-27
    • 2.2.1 "... names that are capitalized". Isn't that "names where initial letters are capitalized " ?
      • Not originally my text, but I'd say "capitalised" here means "first letter is uppercase"; that opinion is apparently shared by the authors of the python standard library, where string.capitalize("abc") is Abc. So, I've left it as is -- MarkusDemleitner - 2018-02-27
    • In 3 , when one enumerates vocabulary terms, we should put a column after "contained the terms" and put a comma between each of those.
      • As usual, getting commas "in between" is a bit tricky when generating stuff, but there's little you can't do with a bit of sed, so the commas are there now. -- MarkusDemleitner - 2018-02-27
    • 3.1 in "updated" attribute: "any time fields considered insignificant should be set to zero"
      • Again not my text (so I'm a bit more reluctant to change it), but I think this really is intended to be "not significant" in the sense of, essentially, "not given". I've made this "non-significant" in hopes that what I read as the original meaning is clearer -- MarkusDemleitner - 2018-02-27
-- FrancoisBonnarel - 2018-02-24

-- MarcoMolinaro - 2018-02-24

Data Model Working Group

(page numbers refer to the PDF)

P3 "Syntax Notation..." end of penultimate section: "the version of the document schema repository" (better to avoid confusion between standard and XML documents)

  • Indeed -- IVOA.Markus Demleitner - 2017-08-31 (OK)
P4 after the citation it is said that VR does not "describe how the terms and values should be encode" and six lines ahead that the document "provides a concrete encoding of the resulting metadata model." The scope of what is encoded here could be clearer.

  • The language with "terms and values" refers to RM (the resource metadata document) as opposed to VOResource itself; what this is trying to say, essentially, is: "VOResource provides the technical details (terms and values) that RM has left open". I'm not quite sure how to improve this passage to perhaps make that clearer. Hints are welcome. -- IVOA.Markus Demleitner - 2017-08-31
    Proposal ...depending on the context. A concrete encoding is given by the document.\n in addition...
Section 2:

General remarks: It is sometime difficult to make a clear distinction between what is normative and what is general consideration on XML schemas or VO versioning. I think that building an VR extension from the doc wouln't be easy t all.

  • I'd like to avoid doing a complete rewrite of major sections of the document without a clear need in a point version of the document. So, while I'm happy to try and fix specific issues, I'm afraid a redesign to make this part more accessible is a bit beyond the scope of this undertaking. -- IVOA.Markus Demleitner - 2017-08-31 (OK, I understand. This was a general comment done by a reader wearing implementer glasses)
The schema of VR extensions can be either in the VR core or in specific XML documents. It would be nice to give a tip for getting the list of available extensions and for locating their schemas (in sec 2.2.5?).

  • I'm not aware of any mechanism that would let you search explicitly for "VOResource extensions"; at least StandardsRegExt, which would be the obvious candidate, doesn't have that. So, if this were found an important use case, I guess we'd have to touch StandarsRegExt. The list of registry extensions endorsed by the IVOA at the time of writing is given in the list of related standards in sect. 1.1. -- IVOA.Markus Demleitner - 2017-08-31. (OK)
P7:
S2: item 2: A pointer to the allowed vocabulary would be nice (ref to section 3.1.4?)
S2:item 5: The VOResource pointer seems to refer to the resource itself, not to another one.
S2:item 7: reference to line 47ff (typo)
S2.1:last paragraph: missing reference to the "versioning policy"

  • ad item 2: as people can in principle define whatever types they desire, there is no closed list of xsi:types; we could say something like "try 'select distinct res_type from rr.resource' in a RegTAP service to see what's in use", but I have a feeling that's making matters even worse. Sect. 3.1.4 is on validationLevel in this copy, so you probably wanted to point somewhere else -- the xsi:type thing is somewhat explained in 2.2.6, so I've added a "as discussed in...". -- IVOA.Markus Demleitner - 2017-08-31 (OK)
  • ad item 5: good catch; this should have been line 17. Fixed. -- IVOA.Markus Demleitner - 2017-08-31 (OK)
  • ad item 7: are you objecting the ff after 47? That's supposed to mean "following lines". Now that you mention it I'm not sure any more if that's common in English-speaking literature. Native speakers, help! -- IVOA.Markus Demleitner - 2017-08-31 (OK Looks like an hexadecimal number to me :=))
  • Versioning policies reference: I've still not given up hopes that the versioning policies will become an endorsed note before VOResource becomes REC (hint, hint). Since I'd rather avoid referencing PENs, this will remain open so I get an error message for it. -- IVOA.Markus Demleitner - 2017-08-31 Actually I do not like the (?). Would (to be endorsed) be better?
P8:
S2.2:The element elementFormDefault is not in the example, is unqualified the default value?

  • Are you referencing the opening example in sect. 2? That's an instance document, but elementFormDefault="unqualified" is only (and can only be) given in the schema (it roughly says: the names I'm defining in the following are outside of any schema, and I can pull that off because the elements are local). If you're referencing another example, could you be specific what it is? -- IVOA.Markus Demleitner - 2017-08-31
    The restriction on empty name spaces, and the whole section actually, is not clear to me. Wouldn't be simpler just to state that "all parts of a document where VOResource schema is in action must be bind with and non empty name space (e.g. xmlns:vor="...")" without bluring the understanding with consideration on elementFormDefault?
P9:
S2.2: Double reference for list items ("corresponding to the section.... in RM" a after "these documents are defined in...")
S2.2: item 1: Identity meta data are not grouped in one block: why are they in a flat list?
S2.2: item 5: A quality flag in the example might help.

  • I don't the the "double reference" part and can't see what's wrong here. (OK my remark was wrong) The observation about title, shortName, and identifier sitting in different parent elements is correct. You're probably right that this is suboptimal design, but it's too late to change that now.(OK) I've added a validationLevel element to the resource itself as an example for the quality-level metadata. In actual use, these probably make a lot more sense on capabilties than on whole resources, but for the sake of example, this may do. (OK) -- IVOA.Markus Demleitner - 2017-08-31
P14:
A table listing both standard capabilities an interfaces would be appreciable, for instance in place of the WSDL considerations.

  • I wouldn't miss the WSDL stuff either, but I don't think we should drop it entirely even in the text (I could be convinced otherwise, though). As to listing the capability and interface types: again, I don't think we should tie this document to a specific set of extensions, as I hope it's longer-lived than them. What I think could be possible is an extension of Theresa's effort RegistryNamespaces or Dave's one at DataTypes20170804. I don't think it would be seriously wrong to reference such a thing in a footnote and hope it'll be maintained. Should we? -- IVOA.Markus Demleitner - 2017-08-31
    (WDSL: OK: capabilities/interface: I'm still thinking that a sample of existing capabilities and interfaces might help)
P15:
Top item 2: is "avoiding <choice>" a good practice or a SHOULD statement? An snippet showing how working around <choice> would help.
After the item list: an example showing the 2 derivation modes would help as well.

  • "avoiding choice": By the "It is recommended" above the enumeration element I'd say it's a SHOULD statement (replace with "xsd:choice elements should be avoided"). As to an example: VOResource doesn't do that unless I'm missing something. So I'm now tentatively pointing towards VODataService's data type system. I feel a bit bad about it because I really want to get rid of that, too. The derivations modes are discussed in the following text, and I've added some words pointing to where the techniques have been used in VOResource. (OK)
Section 3:

P17 (bottom) see vr:ValidationLevel

  • Fixed in schema. Thanks. -- IVOA.Markus Demleitner - 2017-08-31 (OK)
P18: identifier: a ref to http://www.ivoa.net/documents/IVOAIdentifiers/index.html might recall how important is this point

  • That's technically difficult because that piece is directly generated from the schema, and I don't want to have BibTeX markup in there. I could have another reference to the doc in the opening or closing prose, but I'm not convinced that would help the document. -- IVOA.Markus Demleitner - 2017-08-31
after the table:"they describe the resource metadata Description contained"

  • Gone, thanks. -- IVOA.Markus Demleitner - 2017-08-31 (OK)
"XML Schema VersioningPolicies" missing ref
P19: identifierURI: Here is nothing saying to the reader how to set the value of that ID.

  • Well, this is the description of a type, not of a concrete element or attribute. Hence, there's little I can say except "this simply points to a registry record". Whether that's for a publisher or another service depends on what the type is used for. -- IVOA.Markus Demleitner - 2017-08-31 (OK)
P20: "Element creator": useless comment about logos which are introduced later

  • Fair enough; moved the language about first occurrences to the logo element rather than creator itself. -- IVOA.Markus Demleitner - 2017-08-31 (OK)
P23: 1st date comment: URL not readable
P23: 1st date comment: "This includes the the traditional and deprecated"

  • Fixed. -- IVOA.Markus Demleitner - 2017-08-31 (OK)
-- LaurentMichel - 2017-08-21

Corrected document is fine to DM

-- LaurentMichel - 2017-09-06

Grid & Web Services Working Group

  • Do you want to reference the (yet to be endorsed) IVOA note on schema versioning in section 2.1?
  • The changes to security method (commit 4567) look good.
I approve this document.

-- BrianMajor - 2017-12-21

Registry Working Group

I approve this document on behalf of Registry, as of 2018-01-29 (volute revision 4720). These necessary changes include noting that TAP and other service clients may only use the first SecurityMethod element listed, if existent. Several options from service provider and client experience have been proposed during and after the review period for this document, and this one is acceptable.

-- TheresaDower - 2018-01-29

Semantics Working Group

Comments on the PR 1.1 VOResource 1.1 2017-04-25 document PDF version and the html version:

page 7 : not sure the line numbers fit the content of the example provided. The line numbers appear in PDF, but not on the html version of the document.

  • Bug/missing feature in ivoatex, fixed there in volute rev. 4484. Thanks for catching this. -- MarkusDemleitner - 2017-10-11
errors and typos in line numbers appear as 5f , 47ff...

  • Well, these were intended to mean "following line" and "following lines", but since it seems this convention is uncommon, I'm now using actual line ranges. -- MarkusDemleitner - 2017-10-11
Fig. 1 the architecture diagram is just a Specimen. Should be updated to show the IVOA specs related to VOResource ...

  • Ah well, I had hoped I'd get around to building an ivoatex infrastructure to build one. Looks like that won't happen, getting out to fetch one. -- MarkusDemleitner - 2017-10-11
Section 2.2 defines clearly how to use vr:Interface in capability but a real example in XML would be very welcome.

  • I've added an example. Not sure it's altogether helpful, but it also serves the purpose of stressing that you can register browser-based services. -- MarkusDemleitner - 2017-10-11
Subsection 2.3.2 : Footnote (3) should mention the xml schemata' page at http://ivoa.net/xml/index.html to show the xml schemata extended for VOResource in practice

Page 18:
Element identifier : use the font for types as in xs:token for vr:IdentifierURI for best reading

  • I'm not quite sure what this refers to -- could you be more specific? Note, however, that markup in the generated sections is limited in that the text must work both in the schema file and the LaTeX documentation. The ability to autogenerate these parts appars to me more important than the last typographic detail. Still, it should, of course, work as documentation as well as we can reasonably make it. -- MarkusDemleitner - 2017-10-11
Missing reference (?) for "XML schema versioning policies"

  • I know -- I'm still hoping we can get this document endorsed before VOResource (hint! hint!) -- MarkusDemleitner - 2017-10-11
3.1.2 Curation Metadata
Easier reading could be provided by grouping the elements and types descriptions in subsubsections as for instance
a) vr:Curation Metadata elements
b) Vr types involved for curation
b.1) vr:Resource Name type
b.2) vr:Creator type
etc ...
this will help readers of the html version very much

  • I've added additional headings in that section. Does that help? -- MarkusDemleitner - 2017-10-11
p.20 a logo need only be provided ...--> a logo needs only ... ?

Definition of VOResource vocabulary terms.

The list mentioned in the specification will be available soon under http://ivoa.net/, the current link is broken but the 3 vocabulary files can be accessed currently under http://docs.g-vo.org/vocab-test
There are several files for allocating a value to VOresource element fields :
- content_level
- content_type
- date_role
- relationship_type

Theses terms are defined for the scope of the VOResource usage.
Having a few examples of VOresources records using the main vocabulary terms would help to figure out the relevance.

By externalising the literal values expected in VOresource documents, we may allow various dialects of VOresource v1.1 to co-exist in the VO ecosystem if we do not synchronize the version of the standard ( V1.1) with the version of the vocabularies used by VOResource.

  • That is by design. We want to allow new terms in the vocabularies to allow for new features without having to touch the standard. For the four fields we give here, new terms will not break existing usage (example: If people wanted to denote "launch of the instrument" as a date in the registry, they can do that; clients looking for "Updated" dates will not be concerned by that). For advanced usage, it would be great if we could exploit synonyms and hyperonyms here (so people could define major-update and minor-update and clients looking for updated data would still catch both). But that's far beyond current use cases. -- MarkusDemleitner - 2017-10-11
I suppose the validators for VOResource1.1 XML records operate for checking the validity of terms defined in the vocabulary and then this implies that the vocabulary is also versionned as belonguing to the VOResource 1.1 spec.

  • No. The standard takes care to make the use of terms from the vocabularies shoulds, not musts. Hence, validators should at worst give warnings for non-vocabulary terms. -- MarkusDemleitner - 2017-10-11
The relationship_type literals rely on the current version of the DataCite vocabulary. what kind of synchronicity do we expect with the Datacite vocabulary?

  • When upstream adds terms, we'd manually check them for utility and have them added by whatever procedure semantics eventually forsees. -- MarkusDemleitner - 2017-10-11
While validating the registry records produced, it would be interesting to store the statistics for the terms used belonguing to these vocabularies.

If the approved vocabulary has to stick to some version of the specification, the XML schema for these terms could also be provided in addition to RDF TTL. and then this can be checked and validated in an XML parser.

  • That would defeat the purpose of externalising these word list to vocabularies, and as I discussed above is not necessary for interoperability. Having validators emit warnings for non-vocabulary terms, however, is something I would appreciate, mainly to ward against typos. -- MarkusDemleitner - 2017-10-11
-- MireilleLouys - 2017-09-01

  • Changes promised should be in in volute rev. 4487
Thanks for corrections and comments . The document in the revised version is approved for the Semantics WG point of view.

-- MireilleLouys - 2017-10-11

Solar System Interest Group

A small comment on the altIdentifer element that has been added in this version. The example given proposes a syntax for ORCID, but if you go to the ORCID website, they specifically define how a valid ORCID should be formed: https://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier

Example: https://orcid.org/0000-0001-7915-5571

-- BaptisteCecconi - 2018-02-01

  • Indeed. As much as I regret giving up URI schemes for things they were really designed for in exchange for "everything in the browser", that's what we have to live with. Removed the bad example in the schema and added a fixed example in the standard text in volute rev. 4733.

Data Curation & Preservation Interest Group

Education Interest Group

Knowledge Discovery in Databases Interest Group

Theory Interest Group

Time Domain Interest Group

Operations

Standards and Processes Committee

TCG Vote : 2018-06-01 through 2018-06-30

If you have minor comments (typos) on the last version of the document please indicate it in the Comments column of the table and post them in the TCG comments section above with the date.

Group Yes No Abstain Comments
TCG        
Apps X     -- TomDonaldson - 2018-04-17
DAL X     -- FrancoisBonnarel - 2018-05-17
DM X     -- MarkCresitelloDittmar - 2018-07-27
GWS X     -- BrianMajor - 2018-07-03
RoR        
Semantics X     -- MireilleLouys - 2018-05-17
DataCP        
KDD        
Theory        
TD        
Ops        
StdProc        

Edit | Attach | Watch | Print version | History: r29 < r28 < r27 < r26 < r25 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r29 - 2018-07-27 - MarkCresitelloDittmar
 
This site is powered by the TWiki collaboration platform Powered by Perl This site is powered by the TWiki collaboration platformCopyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback