/[volute]/trunk/projects/semantics/vocinvo2/vocinvo2.tex
ViewVC logotype

Contents of /trunk/projects/semantics/vocinvo2/vocinvo2.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5568 - (show annotations)
Wed Jul 31 11:15:52 2019 UTC (2 years ago) by msdemlei
File MIME type: application/x-tex
File size: 52154 byte(s)
vocinvo2: RDF-X is really called RDF/XML, so that's what we now write.


1 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
3
4 \lstloadlanguages{XML}
5 \lstset{flexiblecolumns=true,tagstyle=\ttfamily, showstringspaces=False,
6 basicstyle=\footnotesize}
7
8 \definecolor{termcolor}{rgb}{0.6,0.1,0.1}
9 \newcommand{\vocterm}[1]{\emph{\color{termcolor}#1}}
10
11 \title{Vocabularies in the VO}
12
13 % see ivoatexDoc for what group names to use here
14 \ivoagroup{Semantics}
15
16 \author[https://wiki.ivoa.net/twiki/bin/view/IVOA/MarkusDemleitner]{Markus
17 Demleitner}
18
19 \editor{Markus Demleitner}
20
21 % \previousversion[????URL????]{????Concise Document Label????}
22 \previousversion{This is the first public release}
23
24
25 \begin{document}
26 \begin{abstract}
27 In this document, we discuss practices related to the use of RDF-based
28 vocabularies in the VO. This primarily concerns the creation,
29 publication, and maintenace of vocabularies agreed upon within the IVOA.
30 We also discuss recommended ways clients should use these vocabularies,
31 as well as other, externally maintained ones, in various scenarios.
32 Non-normative appendices detail the current vocabulary-related tooling.
33 \end{abstract}
34
35
36 \section*{Acknowledgments}
37
38 While this is a complete rewrite of the specification how vocabularies
39 are treated in the VO, we gratefully acknowlegde the groundbreaking work
40 of the authors of version 1 of Vocabulary in the VO, S\'ebastien
41 Derriere, Alasdair Gray, Norman Gray, Frederic Hessmann, Tony Linde,
42 Andrea Preite Martinez, Rob Seaman, and Brian Thomas.
43
44 In particular, the vocabulary for datalink semantics done by Norman Gray
45 was formative for many aspects of what is specified here.
46
47 \section*{Conformance-related definitions}
48
49 The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
50 ``OPTIONAL'' (in upper or lower case) used in this document are to be
51 interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
52
53 The \emph{Virtual Observatory (VO)} is a
54 general term for a collection of federated resources that can be used
55 to conduct astronomical research, education, and outreach.
56 The \href{http://www.ivoa.net}{International
57 Virtual Observatory Alliance (IVOA)} is a global
58 collaboration of separately funded projects to develop standards and
59 infrastructure that enable VO applications.
60
61
62 \section{Introduction}
63
64 The W3C's Resource Description Framework RDF \citep{note:rdfprimer} is a powerful
65 and very generic means to represent, transmit, and reason on highly
66 structured, ``semantic'' information. With both its power and
67 generality, however, comes a high complexity for consumers of this
68 information if no further conventions are in force. Also, the generic
69 W3C standards understandably do not cover how semantic resources (e.g.,
70 vocabularies or ontologies) are to be managed, let alone developed
71 within organisations like the IVOA.
72
73 Based on a set of use cases (sect.~\ref{sect:usecases}) and requirements
74 (sect.~\ref{sect:requirements}), this standard will therefore define
75 conventions for
76 vocabularies based on either SKOS or RDFS in
77 sect.~\ref{sect:voccontent}. Where these vocabularies -- and hence, in
78 particular, the permanent URIs of their terms -- are managed by the
79 IVOA, they need to be reviewed and consensus be found. A process to
80 ensure this is described in
81 sect.~\ref{sect:management}. In order
82 to provide certain guarantees to clients, sect.~\ref{sect:deployment}
83 defines minimal standards for how IVOA-managed vocabularies must be made
84 available.
85
86 The non-normative appendices~\ref{app:tools} and \ref{app:curtech}
87 describe the tooling
88 currently used or recommended for building and managing vocabularies in the
89 IVOA.
90
91
92 \subsection{Role within the VO Architecture}
93
94 \begin{figure}
95 \centering
96
97 % As of ivoatex 1.2, the architecture diagram is generated by ivoatex in
98 % SVG; copy ivoatex/archdiag-full.xml to archdiag.xml and throw out
99 % all lines not relevant to your standard.
100 % Notes don't generally need this. If you don't copy archdiag.xml,
101 % you must remove archdiag.svg from FIGURES in the Makefile.
102
103 \includegraphics[width=0.9\textwidth]{role_diagram.pdf}
104 \caption{Architecture diagram for this document}
105 \label{fig:archdiag}
106 \end{figure}
107
108 Fig.~\ref{fig:archdiag} shows the role the Vocabulary in VO standard
109 plays within the IVOA architecture \citep{note:VOARCH}.
110
111 This standard provides the glue between several W3C standards and VO
112 standards that use them within the VO, including:
113
114 \begin{bigdescription}
115 \item[Datalink \citep{2015ivoa.spec.0617D}] Datalink includes a
116 vocabulary letting clients work out the kind of artefact a row pertains
117 to.
118
119 \item[VOResource \citep{2018ivoa.spec.0625P}] VOResource 1.1 comes with
120 several (rather flat) vocabularies enumerating, for instance, the types
121 of relationships between VO resources, their intended audiences, or
122 classes of actions performed on them.
123
124 \item[VOEvent \citep{2006ivoa.spec.1101S}] VOEvent defines \emph{Why}
125 and \emph{What} elements which, while not formally required to be drawn
126 from a specific vocabulary in version 1.11, certainly become much more
127 useful if they are.
128
129 \item[VOTable \citep{2013ivoa.spec.0920O}] VOTable, in its version 1.4,
130 introduces vocabularies for time scales and reference positions.
131
132 \item[SimDM \citep{2012ivoa.spec.0503L}] The Simulation Data Model has
133 several fields the values of which are required to be \vocterm{skos:narrower}
134 than certain top-level concepts; this includes things like the computational
135 methods employed, the physics simulated, or classes of objects
136 simulated.
137
138 \item[UCDs \citep{2007ivoa.spec.0402M}] UCDs are related to vocabularies in
139 that they provide machine-readable semantics. Because the terms listed
140 in the document can be combined and have an underlying grammar, however,
141 they go beyond standard RDF.
142 \end{bigdescription}
143
144 \subsection{Relationship to Vocabularies in the VO Version 1}
145
146 Published in 2009, version 1.19 of the IVOA Recommendation on
147 Vocabularies in the VO had an outlook fairly different from the present
148 document: The big use case was VOEvent's Why and What, and so its focus
149 was on large, general-purpose vocaularies, of which several existed even
150 back then, while an overhaul of a thesaurus of general astronomical
151 terms approved by the IAU in 1993 was underway as part of IVOA's
152 activities. Mapping between vocabularies maintained by different VO
153 and non-VO parties seemed to be the way to ensure interoperability and
154 therefore played a large role in the document. Also, the use cases
155 called for ``soft'' relations, which is why the standard confined itself
156 to SKOS as the vocabulary formalism.
157
158 Since then, ``the'' large astronomy thesaurus is being maintained
159 outside of the IVOA (the UAT\footnote{\url{http://astrothesaurus.org}}),
160 and there is hope that its takeup will be sufficient to make mapping
161 between it and, say, legacy journal keyword systems an exercise general
162 clients will not have to perform.
163
164 Instead, in 2010, a fairly formal vocabulary of what
165 should be properties (in the RDF sense) rather than \vocterm{skos:Concept}-s
166 was required during the development of the datalink standard. The
167 vocabulary was (and still is) small in comparison to, say, the UAT. In
168 contrast to the expectations of Vocabularies~1, the plan had been that
169 most data providers would work with this small vocabulary, and terms
170 from external vocabularies would only be used as temporary stand-ins
171 until the consensus vocabulary was updated. Of course, this required a
172 process for managing such vocabularies. The lack of such a process
173 became even more noticeable when VOResource 1.1 and VOTable 1.4
174 introduced vocabularies of their own.
175
176 On the other hand, we are not aware of a single attempt to map
177 between different vocabularies in a VO context, and the SKOS versions of
178 some vocabularies that Vocabularies 1 declared as normative in its
179 section~4 were largely unused and have been unmaintained for a while now.
180
181 Since large parts of the original specification turned out to be
182 irrelevant or unsustainable as the VO ecosystem evolved,
183 while some core requirements found later
184 were not addressed, it was decided to prepare a new major version of the
185 Vocabularies in the VO standard.
186
187 \subsection{Terminology and Conventions}
188
189 Readers unfamiliar with RDF should read \citet{local:normanspaper} before
190 this specification. In particular, we assume familiarity with all RDF
191 terminology discussed there. Concepts not covered by Gray's
192 essay will be informally introduced here. Of course, the
193 underlying W3C standards are normative where applicable.
194
195 When we speak of \emph{term} here, this means a \vocterm{skos:Concept}
196 in SKOS vocabularies, an \vocterm{rdfs:Class} in RDFS class vocabularies,
197 and an \vocterm{rdf:Property} in RDF property vocabularies.
198
199 We refer to classes and properties by CURIEs. The prefixes in this
200 document correspond the the following URIs:
201
202 \begin{compactitem}
203 \item dc -- \url{http://purl.org/dc/terms/}
204 \item rdf -- \url{http://www.w3.org/1999/02/22-rdf-syntax-ns#}
205 \item rdfs -- \url{http://www.w3.org/2000/01/rdf-schema#}
206 \item owl -- \url{http://www.w3.org/2002/07/owl#}
207 \item skos -- \url{http://www.w3.org/2004/02/skos/core#}
208 \item ivoasem -- \url{http://www.ivoa.net/rdf/ivoasem#}
209 \end{compactitem}
210
211
212 \section{Derivation of Requirements}
213
214 \subsection{Use Cases}
215 \label{sect:usecases}
216
217 The normative content of this document is guided by a set of
218 requriements derived from the following use cases.
219
220 \subsubsection{Controlled Vocabulary in VOResource}
221 \label{uc:simplevoc}
222
223 In VOResource, clients have to find services for data collections. This
224 is indicated by DataCite-compatible \vocterm{isServedBy} relationship.
225 Its concrete literal needs to be reliably defined in order to let
226 clients find such relationships by a simple string comparison in RegTAP
227 queries.
228
229 A related use case is that validators can flag errors (or at least
230 warnings) when resource records use terms that are not part of some
231 controlled vocabulary (e.g., content levels or types of events in a
232 resource's history) , which very typcially indicates mistakes on the
233 part of the resource record author that will quite typically lead to
234 hard-to-debug issues when the resource record is being searched or used.
235
236 \subsubsection{Controlled Vocabularies in VOTable}
237 \label{uc:votvoc}
238
239 VOTable 1.4 will have vocabularies of reference positions and time
240 scales. While with time scales the situation is not fundamentally
241 different from the VOResource case discussed in
242 sect.~\ref{uc:simplevoc} -- a simple enumeration of agreed-upon strings
243 is enough to uniquely determine what operations need to be performed to
244 combine times given in different time scales --, the situation for
245 reference positions is probably different. There, even if a client does
246 not exactly know the location of, say, the Hubble Space Telescope at any
247 given time, several important use cases can already be satisfied if a
248 client knows that it is in lower Earth orbit (e.g., assuming a reference
249 position Geocenter and adjusting the systematic error estimates). For
250 this, a client needs information of the type ``\vocterm{HST}
251 \vocterm{is-close-to} \vocterm{GEOCENTER}\/'' (or similar).
252
253 There is also another difference between this and at least the
254 VOResource relationship vocabulary from use case~\ref{uc:simplevoc}
255 in that the latter is property-like, as
256 in ``Resource-1 \vocterm{isServedBy} Resource-2\/''. In constrast with
257 this, a time scale would be used like ``Time-coordinate \vocterm{uses}
258 \vocterm{TT}\/''. In RDFS terminology, they are therefore better modelled
259 as classes rather than properties.
260
261 \subsubsection{Datalink Link Selection}
262 \label{uc:links}
263
264 In Datalink \citep{2015ivoa.spec.0617D}, clients receive a set of links
265 to pieces of data (e.g., previews, additional metadata, progenitors or
266 derived data) and need to present to the user only those pieces of data
267 relevant to the task at hand. For instance, in a discovery phase, only
268 previews should be offered, while scientific exploitation would call for
269 cutout services, alternate formats, or related data. For debugging,
270 progenitors should be made accessible, and so on.
271
272 Operators of datalink services, on the other hand, want to be precise in
273 their annotation of datasets. For instance, they may want to discern
274 among progenitors the raw image, a dark frame, and a flat field. While
275 doing that, clients should still be able to work out that all these
276 artefacts are progenitors.
277
278 \subsubsection{VOEvent Filtering, Query Expansion}
279 \label{uc:filtering}
280
281 In VOEvent, an event stream can contain a classification of what the
282 observers believe was observed, for instance ``supernova Ia explosion''.
283 While an event stream from one project might provide a classification on
284 that level for some event, it might not (yet) be able to do that in
285 another event, while a different event stream might not be able to
286 distinguish between different sorts of supernovae at all.
287
288 In this situation, an event broker looking for supernovae of type Ia
289 will filter out anything not related to supernovae; however, since for
290 one reason or another a Ia supernova might only be tagged as supernova,
291 it will want to widen its filter somewhat, where some backend process
292 might prioritise events classified as Ia upstream over those only tagged
293 as a generic supernova, and those, again, over those tagged explicitly
294 as some different type of supernova.
295
296 Similar use cases exist, for instance, in the discovery of simulations
297 and possibly for subjects of VO resources.
298
299
300 \subsubsection{Vocabulary Updates in VOResource}
301 \label{uc:deprecation}
302
303 In VOResource 1.0, relationship types like \vocterm{served-by} or
304 \vocterm{service-for} were defined. Later, DataCite defined equivalent
305 terms \vocterm{IsServedBy} and \vocterm{IsServiceFor}. Arguably, the VO should,
306 as far as sensible, take up standards in the wider data management
307 community, and so VOResource 1.1 adopts the DataCite terms. In a minor
308 version, it cannot forbid the old terms. It can, however, say not only
309 ``\vocterm{served-by} is the same as \vocterm{isServedBy}'' but also
310 ``Use the latter term in preference to the former''. If this information is
311 available machine-readably, validators can warn against the use of
312 deprecated terms and user interfaces can transparently replace
313 deprecated terms with current ones. This latter use case is is
314 currently prescribed in RegTAP 1.1 \citep{TODO}.
315
316 \subsubsection{Discovering Meanings}
317 \label{uc:discovering}
318
319 Software developers or researchers should in general be able to work out
320 what some term mentioned ``means'' (where we are agnostic as to what
321 ``means'' should mean here). If the term URI alone is insufficient,
322 they can simply paste the resource URI of the term into a web browser
323 and read (at least) its description and perhaps find out even more using
324 relationships between terms.
325
326 \subsubsection{Simple Review Process}
327 \label{uc:simplereview}
328
329 As vocabularies evolve, new terms are being added to
330 vocabularies. To facilitate their review and enable rapid uptake
331 of the proposed terms, it is desirable that new terms and even
332 new vocabularies are immediately visible to users and tools.
333 Note that since terms under review might be modified or removed later,
334 this use case is somewhat in conflict with the basic requirement
335 of stable vocabularies (i.e., a document valid once will not
336 become invalid later because of changes in vocabularies).
337
338 \subsection{Requirements}
339 \label{sect:requirements}
340
341 \subsubsection{Lists of Terms}
342 \label{req:lists}
343
344 We need to be able to represent simple lists of terms even for the most
345 basic use case~\ref{uc:simplevoc}. As per
346 use case~\ref{uc:votvoc}, we will have to represent instances of both
347 \vocterm{rdf:Property} and \vocterm{rdfs:Class} (though not necessarily
348 in one vocabulary).
349
350 \subsubsection{Hierarchies of Terms}
351 \label{req:hierarchy}
352
353 Both use case~\ref{uc:links} and use case~\ref{uc:filtering} require a hierarchy
354 of terms, where clients can find wider and potentially narrower terms
355 relative to an original one. There is a difference,
356 however: in the datalink use-case, strict \vocterm{is-a} relationships
357 are what clients need (e.g., ``give me all kinds of previews''). In the
358 VOEvent case, however, a somewhat softer sort of hierarchy is required.
359 For instance, a filter for accretion disks might very well expand to
360 both match quasars and cataclysmic variables. Hence, we want to
361 be able to represent strict class hierarchies as well as thesaurus-like
362 soft knowledge structures.
363
364 \subsubsection{Consensus Vocabularies}
365 \label{req:consensus}
366
367 Essentially all our our use cases will be much easier to implement if
368 clients can work through simple string comparisons. Therefore,
369 whereever feasible IVOA standards should build on IVOA-sanctioned,
370 consensus vocabularies.
371
372 \subsubsection{Deprecating Terms}
373 \label{req:deprecating}
374
375 While we believe at this point that terms once approved by the IVOA
376 should never disappear -- for instance, because validators might
377 otherwise flag previously valid instance documents as invalid --, use
378 case~\ref{uc:deprecation} shows that some way of declaring
379 deprecations must be forseen.
380
381 \subsubsection{Public Availability of Machine-Readable Vocabularies}
382 \label{req:machine}
383
384 In particular in use cases~\ref{uc:links} and \ref{uc:filtering},
385 clients can flexibly incorporate vocabulary updates without code
386 changes, perhaps even without re-deployment, if vocabularies are
387 available at constant, public URIs, where clients can retrieve them in
388 formats reasonably easy to parse.
389
390 Use case~\ref{uc:discovering} implies that at least one representation
391 of the vocabulary should be reasonably human-readable.
392
393 \subsubsection{Minimal Term Metadata}
394 \label{req:mtm}
395
396 To support use case~\ref{uc:discovering}, all terms in IVOA vocabularies
397 must come with a non-trivial description.
398
399 \subsubsection{Simple Cases do not Require RDF Tooling}
400 \label{req:xml}
401
402 (Not derived from any specific use case). Since libraries implementing
403 (some subset of) RDF tend to be rather massive and thus appear
404 unproportional when all a client wants is an up-to date list of terms
405 with their descriptions, this specification tries hard to facilitate
406 some basic operations using just common XML tools (e.g., xpath).
407
408 \subsubsection{Vocabulary Evolution}
409 \label{req:evolution}
410
411 Most use cases make it desirable that terms can be added to existing
412 vocabularies; this is very clear for the reference positions in
413 use case~\ref{uc:votvoc}, where new instruments would imply new
414 terms.
415
416 \subsubsection{Preliminary Vocabularies and Terms}
417 \label{req:preliminary}
418
419 In use case~\ref{uc:simplereview}, it is desirable to admit
420 ``preliminary'' vocabularies and terms. For these, both humans
421 and machines must be able to discern a temporary status, and
422 their use implies that the general rule ``once valid, always
423 valid'' does not apply. Validators and similar software could
424 then add notices to that effect in their outputs.
425
426 \subsection{Non-Requirement}
427
428 This specification is not called ``Semantics in the VO'' or the like
429 because we do \emph{not} intend to prescribe ways to turn any VO
430 artefacts into RDF triples. Indeed, for many existing vocabularies, it
431 is left open what exactly the domain or range of properties might be or
432 what subject and predicate the classes or concepts should be used with.
433
434 This is partly because this would substantially complicate the
435 generation of vocabularies, partly because the information encoded by
436 the triples has traditionally been expressed using techniques developed
437 by the Data Models working group.
438
439 In particular with a view to later use in linked data scenarios,
440 vocabulary authors should neverthess take care that, given appropriate
441 properties or annotation tools, the vocabularies \emph{could} be used in
442 meaningful RDF triples.
443
444 \section{Vocabulary Content}
445 \label{sect:voccontent}
446
447 IVOA vocabularies must be based on W3C's Resource Description Framework.
448 Details on required serialisations are given in
449 sect.~\ref{sect:deployment}. This section deals with what kinds of
450 statements users of IVOA vocabularies SHOULD evaluate to ensure
451 interoperability. Statements of other types are legal in IVOA
452 vocabularies but are not expected to be interpreted interoperably.
453 Clients MAY ignore them.
454
455 In IVOA vocabularies, the concept URI MUST begin with
456 \url{http://www.ivoa.net/rdf}\footnote{In retrospect, the unnecessary
457 ``www'' in this URI is somewhat regrettable, but existing vocabularies
458 have used URIs including it, and it seems a small price to pay for
459 having uniform URIs}. It is recommended to not introduce
460 additional hierarchies, i.e., vocabulary URLs should be direct children
461 of \texttt{rdf}\footnote{Some existing vocabularies do not follow this
462 rule; since vocabulary URL changes will break certain usage scenarios,
463 their URLs are still retained.}.
464
465 Since all vocabularies specified here are
466 single-file, the full vocabulary URI is formed by appending a hash sign
467 and a fragment identifier. In IVOA vocabularies, this fragment
468 identifier MUST consist of ASCII letters, numbers, underscores and
469 dashes exclusively [for requirement~\ref{req:machine}].
470
471 The fragment identifiers in the vocabulary URIs should be
472 human-readable, usually by suitably contracting the
473 preferred label. In the IVOA, we do \emph{not} use natural
474 language-neutral concept identifiers but instead expect that domain
475 experts will already have an impression of a term's meaning from looking
476 at its URI.
477
478 In this specification, we distinguish SKOS-based and RDFS-based
479 vocabularies, which are subject to slightly different requirements.
480 Although the requirements are non-contradicting, each vocabulary must
481 be clearly identified as \emph{either} giving SKOS concepts, RDFS
482 classes or RDF properties so clients know how to extract word lists and
483 hierarchies [by requirement~\ref{req:xml}].
484
485
486 \subsection{SKOS Vocabularies}
487 \label{sect:skosvoc}
488
489 SKOS vocabularies should be used where the terms in the vocabulary
490 enumerate terms in informal (i.e., non necessarily strict is-a)
491 hierarchies. The classic use case here is query expansion, where, for
492 instance, a search for ``AGN'' might be expanded to include matches for
493 ``accretion disk'' (under certain circumstances).
494
495 \subsubsection{Properties in SKOS Vocabularies}
496 \label{sect:skosvoc-prop}
497
498 IVOA SKOS vocabularies use the following properties:
499
500 \begin{itemize}
501 \item \vocterm{skos:Concept} -- all terms in a SKOS vocabulary are
502 \vocterm{skos:Concept}\,s.
503
504 \item \vocterm{skos:narrower} -- interpreted in the standard SKOS sense.
505 The reverse property, \vocterm{skos:broader}, MAY be given, but clients
506 MUST NOT depend on their presence [this satisifies
507 requirement~\ref{req:hierarchy}].
508
509 \item \vocterm{skos:prefLabel} -- all concepts MUST have an
510 English-Language preferred label, which is an RDF plain literal [by
511 requirement~\ref{req:mtm}]. No RDF language label is allowed on the
512 literal, and only one preferred label is permitted
513 [these help requirement~\ref{req:xml}].
514
515 \item \vocterm{skos:definition} -- all concepts MUST have a non-trivial
516 English-language definition. It is obviously impossible to define
517 ``non-trivial'' in a rigorous way; a suggested criterion is that a
518 domain expert would, given the definition, presumably arrive at a
519 similar preferred label. Definitions that contain the preferred label
520 itself are at least suspicious. Definitions in non-English
521 languages are not permitted [again, this helps
522 requirement~\ref{req:mtm}].
523
524 \item General properties discussed in \ref{sect:genprop} [this is
525 for requirements~\ref{req:deprecating} and
526 \ref{req:preliminary}].
527 \end{itemize}
528
529 This specification does not include requirements on the use or the
530 interpretation of \vocterm{skos:related}, \vocterm{skos:exactMatch},
531 \vocterm{skos:closeMatch}, \vocterm{skos:broadMatch},
532 \vocterm{skos:narrowMatch}, \vocterm{skos:ConceptScheme},
533 \vocterm{skos:inScheme}, \vocterm{skos:hasTopconcept},
534 \vocterm{skos:altLabel}, and \vocterm{skos:hiddenLabel}. If use cases
535 are found that require those, this specifiation will be amended. Until
536 then, vocabulary authors should not use them in order to avoid creating
537 practices that might conflict with later usage patterns.
538
539 This specification does not include requirements on the use or the
540 interpretation of the transitive SKOS properties
541 (\vocterm{skos:broaderTransitive}, \vocterm{skos:narrowerTransitive}).
542 At this point, we believe that applications requiring this type of
543 reasoning-friendly semantics should preferably use RDF class
544 vocabularies.
545
546 \subsubsection{Example (non-normative)}
547
548 Here is term from a SKOS vocabulary conforming to this specification
549 in RDF/XML serialisation:
550
551 \begin{lstlisting}[language=XML]
552 <skos:Concept
553 rdf:about="http://www.ivoa.net/rdf/AstronomicalObjects#CompoundObject">
554 <skos:prefLabel>Compound object</skos:prefLabel>
555 <skos:narrower
556 rdf:resource="http://www.ivoa.net/rdf/AstronomicalObjects#AGN"/>
557 <skos:narrower
558 rdf:resource="http://www.ivoa.net/rdf/AstronomicalObjects#AssociationOfStars"/>
559 <skos:narrower
560 rdf:resource="http://www.ivoa.net/rdf/AstronomicalObjects#Galaxy"/>
561 <skos:definition>A composite object is made of at least two
562 distinct astronomical objects</skos:description>
563 </skos:Concept>
564 \end{lstlisting}
565
566 \subsubsection{Usage with Plain XML Tooling}
567 \label{sect:xml-skos}
568
569 To use IVOA SKOS vocabularies with plain XML tooling (i.e., without RDF
570 libraries), retrieve the vocabulary URL with the \verb|accept| header
571 set to \verb|application/rdf+xml|.
572
573 In this file, all \xmlel{skos:Concept} elements with
574 \xmlel{rdf:about} attributes starting with the vocabulary URI define the
575 terms. Clients should collect at least the \xmlel{rdf:about} attribute,
576 and the \xmlel{skos:prefLabel} and \xmlel{skos:definition} children for
577 each term. The terms themselves are the fragment identifiers in the
578 \xmlel{rdf:about} URIs.
579
580 Clients also interested in the hierarchy of terms extract the
581 \xmlel{skos:narrower} children from each concept element. All elements
582 with \xmlel{resource} attributes not starting with the vocabulary URI
583 are discarded, and only the fragment identifiers are used. Clients
584 needing \vocterm{skos:broader} must invert the graph obtained in this
585 way rather than look for \vocterm{skos:broader} elements, as these are not
586 guaranteed in IVOA vocabularies.
587
588
589 \subsection{RDF Properties Vocabularies}
590 \label{sect:refpropvoc}
591
592 RDF properties vocabularies should be used when the terms in the
593 vocabulary are mainly used to state
594 relationships between entities that can sensibly be imagined as
595 resources in the RDF sense. Such terms would naturally be used as
596 predicates in RDF triples. Obvious examples might be something
597 like is-progenitor-for in a provenance chain or, indeed, the properties
598 used to describe IVOA vocabularies.
599
600 \subsubsection{Properties in RDF Properties Vocabularies}
601
602 IVOA RDF properties vocabularies use the following properties (where
603 not specified, the requirements considered essentially match those in
604 sect.~\ref{sect:skosvoc-prop}):
605
606 \begin{itemize}
607 \item \vocterm{rdf:Property} -- all terms in an RDF property vocabulary
608 are properties.
609
610 \item \vocterm{rdfs:label} -- all terms MUST have an English-language
611 label, and clients should prefer it over the term (the fragment of the
612 term URI) for presentation purposes. Only
613 one such label is permitted.
614
615 \item \vocterm{rdfs:comment} -- all concepts MUST have a non-trivial
616 English-language comment serving as a human-oriented definition of the
617 term. The considerations for \vocterm{skos:definition} in
618 sect.~\ref{sect:skosvoc-prop} apply.
619
620 \item \vocterm{rdfs:subPropertyOf} -- interpreted as in RDFS to induce
621 the hierarchy of terms.
622
623 \item General properties discussed in sect.~\ref{sect:genprop}.
624 \end{itemize}
625
626 \subsubsection{Example (non-normative)}
627 \label{sect:rdfpxex}
628
629 \begin{lstlisting}[language=XML]
630 <rdf:Property
631 rdf:about="http://www.ivoa.net/rdf/datalink/core#bias">
632 <rdfs:comment>A serialisation of an array used to subtract
633 the detector offset level.</rdfs:comment>
634 <rdfs:label>Bias calibration data</rdfs:label>
635 <rdfs:subPropertyOf rdf:resource
636 ="http://www.ivoa.net/rdf/datalink/core#calibration"/>
637 </rdf:Property>
638 \end{lstlisting}
639
640 Note that neither RDF nor this specification requires all children
641 pertaining to a term to share a single parent element, and the enclosing
642 element type is unspecified. For instance, the following XML fragment
643 is considered equivalent to the one above:
644
645 \begin{lstlisting}[language=XML]
646 <rdf:Description
647 rdf:about="http://www.ivoa.net/rdf/datalink/core/core#bias">
648 <rdfs:comment>A serialisation of an array used to subtract
649 the detector offset level.</rdfs:comment>
650 <rdfs:label>Bias calibration data</rdfs:label>
651 </rdf:Description>
652
653 <rdf:Description
654 rdf:about="http://www.ivoa.net/rdf/datalink/core/core#bias">
655 <rdfs:subPropertyOf rdf:resource
656 ="http://www.ivoa.net/rdf/datalink/core/core#calibration"/>
657 </rdf:Description>
658 \end{lstlisting}
659
660 See the next section for how to robustly use such vocabularies without
661 RDF tooling.
662
663 \subsubsection{Usage with Plain XML Tooling}
664 \label{sect:xml-rdfprop}
665
666 To use IVOA RDF properties vocabularies with plain XML tooling (i.e.,
667 without RDF libraries), retrieve the vocabulary URL with the
668 \verb|accept| header set to \verb|application/rdf+xml|.
669
670 To obtain a list of terms from an IVOA RDF properties vocabulary,
671 collect all values of \xmlel{rdf:about} attribute in elements having an
672 \xmlel{rdf:type} child with the
673 \xmlel{rdf:resource} attribute set to
674 \nolinkurl{http://www.w3.org/1999/02/22-rdf-syntax-ns#Property}. Any
675 strings obtained in this way that do not begin with the vocabulary URI
676 are discarded.
677
678 To obtain a label for a term, get the contents of an \xmlel{rdfs:label}
679 child of an element with its \xmlel{rdf:about} attribute set to the
680 term's URI.
681
682 To obtain the hierarchy of terms, get all \xmlel{rdfs:subProperyOf}
683 elements and form pairs of the enclosing elements' \xmlel{rdf:about}
684 attributes (the more specific term) and the subPropertyOf elements'
685 \xmlel{rdf:resource} attribute.
686
687 \subsection{RDF Class Vocabularies}
688
689 RDF class vocabularies should be used when the terms in the vocabulary
690 are reasonably class-like, i.e., would usually be either subjects or
691 objects in RDF triples. As opposed to SKOS vocabularies, the hierarchy
692 implied, however, is strict in the sense of \vocterm{rdfs:subClassOf}
693 -- roughly, that statements true for a wider term must be true
694 a more specialised term, too. This lets clients confidently perform
695 inferences.
696
697 For instance, coordinates in the FK4 reference frame are equatorial, and
698 thus even a client unfamiliar with the FK4 frame as such can confidently
699 infer that the coordinates are right ascension and declination, and that
700 right ascensions increase eastwards. Reasoning of this type is
701 impossible within a SKOS vocabulary.
702
703 \subsubsection{Properties in RDF Class Vocabularies}
704
705 IVOA RDF class vocabularies use the following properties:
706
707 \begin{itemize}
708 \item \vocterm{rdfs:Class} -- all terms in an RDF Class vocabulary
709 are classes in the RDFS sense.
710
711 \item \vocterm{rdfs:label} -- all terms MUST have an English-language
712 label, and clients should prefer it over the term (the fragment of the
713 term URI) for presentation purposes. Only
714 one such label is permitted.
715
716 \item \vocterm{rdfs:comment} -- all concepts MUST have a non-trivial
717 English-language comment serving as a human-oriented definition of the
718 term. The considerations for \vocterm{skos:definition} in
719 sect.~\ref{sect:skosvoc-prop} apply.
720
721 \item \vocterm{rdfs:subClassOf} -- interpreted as in RDFS to induce
722 the hierarchy of terms.
723
724 \item General properties discussed in \ref{sect:genprop}.
725 \end{itemize}
726
727 \subsubsection{Example (non-normative)}
728
729 Here is a term from an RDF class vocabulary conforming to this
730 specification in RDF/XML serialisation:
731
732 \begin{lstlisting}[language=XML]
733 <rdf:Description rdf:about="http://www.ivoa.net/rdf/refframe#FK5">
734 <rdf:type rdf:resource
735 ="http://www.w3.org/2000/01/rdf-schema#Class"/>
736 <rdfs:label>FK5</rdfs:label>
737 <rdfs:comment>Positions based on the 5th Fundamental Katalog. If
738 no equinox is defined with this frame, assume J2000.0. Applications
739 not requiring extremely high precision can identify FK5 at J2000
740 with ICRS.
741 </rdfs:comment>
742 <rdfs:subClassOf
743 rdf:resource="http://www.ivoa.net/rdf/refframe#EQUATORIAL"/>
744 </rdf:Description>
745 \end{lstlisting}
746
747 The warnings as to variants of such notations given in
748 sect.~\ref{sect:rdfpxex} apply here as well.
749
750 \subsubsection{Usage with Plain XML Tooling}
751 \label{sect:xml-rdfclass}
752
753 To use IVOA RDF class vocabularies with plain XML tooling (i.e.,
754 without RDF libraries), retrieve the vocabulary URL with the
755 \verb|accept| header set to \verb|application/rdf+xml|.
756
757 To obtain a list of terms from an IVOA RDF class vocabulary,
758 collect all values of \xmlel{rdf:about} attribute in elements having an
759 \xmlel{rdf:type} child with the
760 \xmlel{rdf:resource} attribute set to
761 \nolinkurl{http://www.w3.org/2000/01/rdf-schema#Class}. Any
762 strings obtained in this way that do not begin with the vocabulary URI
763 are discarded.
764
765
766 To obtain a label for a term, get the contents of an \xmlel{rdfs:label}
767 child of an element with its \xmlel{rdf:about} attribute set to the
768 term's URI.
769
770 To obtain the hierarchy of terms, get all \xmlel{rdfs:subClassOf}
771 elements and form pairs of the enclosing elements' \xmlel{rdf:about}
772 attributes (the more specific term) and the subClassOf elements'
773 \xmlel{rdf:resource} attribute.
774
775 \subsection{General Properties}
776 \label{sect:genprop}
777
778 To cover requirements~\ref{req:deprecating} and
779 \ref{req:preliminary}, the Semantics WG defines some properties
780 of its own in the vocabulary
781 \url{http://www.ivoa.net/rdf/ivoasem}. The following properties
782 may be used in all three kinds of vocabularies:
783
784 \begin{itemize}
785 \item \vocterm{ivoasem:preliminary} -- this property indicates
786 that a term is preliminary and might disappear from the
787 vocabulary without warning. The object of clauses using it
788 will be a blank node. Validators need not warn against the use
789 of preliminary terms, but as they encounter them, they should
790 qualify their validation to the effect that it is temporary.
791
792 \item \vocterm{ivoasem:deprecated} -- this property indicates
793 that a term is deprecated. The object of clauses using it will
794 be a blank node. Validators should issue warnings if such terms
795 are encountered. In order to support general RDF tooling,
796 \vocterm{owl:deprecatedProperty} and
797 \vocterm{owl:deprecatedClass} are declared as subproperties of
798 this term.
799
800 \item \vocterm{ivoasem:useInstead} -- for a deprecated term, the
801 object(s) of RDF clause(s) using this property indicate
802 which term(s) should be
803 used instead of the deprecated one. In order to support general
804 RDF tooling, \vocterm{owl:equivalentProperty} and
805 \vocterm{owl:equivalentClass} are declared as subproperties of
806 this this term, although admittedly this might be stretching the
807 owl properties' meanings somewhat.
808
809 \end{itemize}
810
811 \subsubsection{Example}
812
813 TBW
814
815 \subsubsection{Usage with Plain XML Tooling}
816
817 TBW
818
819 \section{Vocabulary Management}
820 \label{sect:management}
821
822 This section discusses the processes in which new vocabularies can be
823 defined and how vocabulary updates are performed in way
824 that ensures community participation and at least a minimal level of consensus.
825 In the following, the phrase ``chair of the semantics WG'' is understood
826 to mean ``chair or vice-chair of the Semantics WG''; in the unlikely
827 situation that chair and vice-chair dissent, the resolution of the
828 problem is up to the TCG chair.
829
830
831 \subsection{New Vocabularies}
832
833 New vocabularies in the VO should be introduced with a document going
834 through the normal IVOA approval process, i.e., intended to become a
835 recommendation or an endorsed note with RFC as described in the IVOA
836 Document Standards \citep{2017ivoa.spec.0517G}.
837
838 At the discretion of the chair or the Semantics WG, the vocabulary is
839 uploaded to the vocabulary repository when a document reaches the state
840 of a Working Draft. At the latest, the vocabulary is uploaded when the
841 document becomes a Proposed Recommendation or a Proposed Endorsed Note
842 in order to support a thorough review and reference implementations.
843
844 The entire vocabulary is marked human-readably as preliminary in the
845 vocabulary index (cf.~sect.~\ref{sect:deployment}). All terms in the
846 vocabulary are marked as preliminary using the
847 \vocterm{ivoasem:preliminary} property (cf.~sect.~\ref{sect:genprop}) in
848 order to satisfy requirement~\ref{req:preliminary}.
849
850 The entrire new vocabulary gets approved as the document introducing it
851 reaches the status of a Recommendation or an Endorsed Note. From then
852 on, it is being managed by the Semantics WG using the process defined in
853 the next section.
854
855 Once approved (i.e., no longer marked as preliminary),
856 terms in IVOA vocabularies cannot be removed. They can,
857 however, be marked as deprecated; if that happens, validators or similar
858 components should flag warnings when they encounter such terms.
859
860 \subsection{Updating Vocabularies}
861
862 IVOA vocabularies can be extended as domain requirements develop
863 [requirement~\ref{req:evolution}]. Clients
864 should therefore be designed such that they gracefully deal with terms
865 that have not been part of the vocabulary at build time, typically by
866 exploiting information in the vocabulary, perhaps by falling back to
867 wider, known terms, or by presenting their users labels and descriptions
868 for terms not explicitly handled.
869
870
871 \subsubsection{Vocabulary Enhancement Proposals}
872
873 To add one or more terms to a vocabulary, to introduce deprecations or
874 to change term labels, descriptions, or relationships,
875 an interested party -- not necessarily affiliated with the Working Group
876 that has originally introduced the vocabulary -- prepares a Vocabulary
877 Enhancement Proposal (VEP). In the interest of thorough review and
878 topical discussion, a single VEP should only cover directly related
879 terms. For instance, in a vocabulary of reference frames, it would be
880 reasonable to add old-style and new-style galactic frames in one
881 VEP, but not, say, azimuthal and supergalactic coordinates. The
882 arguments for both terms in the former pair are rather
883 analogous\footnote{This does not rule out that, in the example, one
884 might argue that old-style galactic coordinates are so ancient that
885 perhaps they should not be supported in the VO at all; the chair of the
886 Semantics WG might then decree that the VEP still needs to be split.}.
887 In the latter case, two very different rationales would have
888 to be put forward, which is a clear sign that two VEPs are in order.
889
890 If during discussion it is found that a VEP should be split, the
891 original VEP must be withdrawn and two new VEPs be prepared.
892
893 \begin{figure}
894 \begin{verbatim}
895 Vocabulary: http://www.ivoa.net/rdf/datalink/core
896 Author: msdemlei@ari.uni-heidelberg.de
897 Date: 2019-07-19
898
899 New Term: IsPreviousVersionOf
900 Action: Addition
901 Label: Newer Version
902 Description: This dataset in a previous edition, e.g., processed
903 with an older pipeline, as part of an older data release.
904 Relationships: rdfs:subProperyOf(this)
905
906 New Term: IsNewVersionOf
907 Action: Addition
908 Label: Previous Version
909 Description: This dataset in a newer edition, e.g., processed
910 with a newer pipeline, as part of a newer data release.
911 Relationships: rdfs:subProperyOf(this)
912
913 Rationale:
914
915 The terms are mainly intended for projects with data releases.
916 IsPreviousVersionOf allows marking up links to (typically
917 datalink documents for) later version(s) of this data set. It
918 allows a client to alert users that a newer, probably improved,
919 rendition of the current dataset is available and should
920 presumably be used instead of what they are looking at. The
921 inverse relationship, IsNewVersionOf, is useful if projects want
922 to keep previous versions of the dataset findable without having
923 them show up in the default queries.
924
925 The terms are taken from the relationship types of DataCite.
926 \end{verbatim}
927
928 \caption{A sample VEP.}
929 \label{fig:vepsample}
930 \end{figure}
931
932 A VEP is a semistructured text file containing the following items:
933
934 \begin{itemize}
935 \item Vocabulary: The URL or the vocabulary
936 \item Author: An e-mail address for a contact person for the author(s) of
937 the VEP.
938 \item Date: The date on which the VEP was posted.
939 \item Term: The identifier of the new term.
940 \item Action: one of \textit{Addition}, \textit{Depreciation}, or
941 \textit{Modification}.
942 \item Label: The English-language, human-readable label of the new term.
943 \item Description: The description that will come with the term.
944 \item Relationships: If applicable, relationships the new
945 term will have to existing terms, using the properties defined in
946 the present document.
947 \item Rationale: A discussion of use cases, the role of the new term in
948 the vocabulary, and the like. In particular, an actual application of
949 the term should be given.
950 \end{itemize}
951
952 The items \textit{Term}, \textit{Action}, \textit{Label},
953 \textit{Description}, and \textit{Relationships} may be repeated if
954 multiple terms are affected by a VEP. In \textit{Addition} VEPs, all items
955 except \textit{Relationships} are mandatory.
956
957 When \textit{Action} is \textit{Depreciation}, \textit{Label},
958 \textit{Description}, and \textit{Relationships} are optional but can be
959 given if useful for understanding the VEP. The rationale must discuss
960 the reasons for a depreciation. Usually, one or more replacement
961 term(s) will be proposed within the same VEP.
962
963 When \textit{Action} is \textit{Modification}, \textit{Label},
964 \textit{Description}, and \textit{Relationships} give the proposed new
965 values of the term. The term itself cannot be modified. The rationale
966 will usually detail the changes proposed while mentioning the previous
967 values.
968
969 We do not expect the VEPs to be evaluated by machines. Therefore, we
970 define no grammar for the markup of sections, section headers, and their
971 content. It is still recommended that authors follow the formatting of
972 the example in Fig.~\ref{fig:vepsample}.
973
974 \subsubsection{Publishing a VEP}
975
976 The Semantics working group maintains a web-based repository for VEPs
977 (see Appendix~\ref{app:curtech} for the technical details). There, a
978 running number is assigned to the VEP at the time of the upload. This
979 will be used to identify the VEP, where the running number is expanded
980 to three digits. The first VEP will thus be VEP-001, the second
981 VEP-002, and so on.
982
983 Once the VEP is uploaded, it is announced to the IVOA Semantics Working
984 Group and all other IVOA Working Groups concerned (again, the technical
985 details are found in Appendix~\ref{app:curtech}). The chair of the
986 Semantics WG can extend the distribution as they see fit. The
987 announcement in particular contains a copy of the VEP in question.
988
989 As soon as possible after the upload, the chair of the Semantics WG adds
990 the term(s) proposed to the vocabulary as a preliminiary term using the
991 \vocterm{ivoasem:preliminary} property. This
992 means that they can immediately be used without raising warnings or
993 errors, but in contrast to approved terms, they may disappear again.
994
995 \subsubsection{Approval Process}
996 \label{sect:approval}
997
998 Discussion of a VEP takes place in the WGs' discussion forums (again,
999 see Appendix~\ref{app:curtech}). The chair of the Semantics WG will
1000 summarise the discussion in the VEP in a \textit{Discussion} section
1001 (that may be updated during the process).
1002
1003 Once the chair of the Semantics WG sees a sufficient consensus reached,
1004 they announce the VEP in the TCG. If, at the next meeting of the TCG,
1005 no Working Group objects to the VEP, it is accepted and the marker that
1006 a term is preliminary is removed from the terms' relationships in the
1007 vocabulary.
1008
1009
1010 \section{Vocabulary Deployment}
1011 \label{sect:deployment}
1012
1013 This section is an adaptation of \citet{note:cooluris} and is
1014 intended to satisfy requirements~\ref{req:machine}
1015 and~\ref{req:mtm}.
1016
1017 All IVOA-approved vocabularies are accessible as children of
1018 \url{http://www.ivoa.net/rdf}. Dereferencing that URL will lead to an
1019 index of current approved and proposed vocabularies.
1020 Vocabularies still under review are clearly marked as such.
1021
1022 When dereferencing a vocabulary URL, clients will receive an HTTP 303
1023 (See Other) code, with the \texttt{Location} header set to the last
1024 version of the vocabulary. The version is written as the date of the
1025 last update in the format YYYY-MM-DD. Depending on the value of the
1026 request's accept header, the redirect will end up at
1027
1028 \begin{itemize}
1029 \item by default, an HTML rendition of the vocabulary. The HTML element
1030 corresponding to a term has a corresponding HTML id; hence a URL
1031 \verb|<vocabulary URI>#<term>| will be immediately visible in common
1032 user agents [requirement~\ref{req:mtm}].
1033
1034 \item a Turtle rendition of the vocabulary if the accept header
1035 indicates that \verb|text/turtle| documents are preferred.
1036
1037 \item an RDF/X rendition of the vocabulary subject to the constraints
1038 implied by Sects.~\ref{sect:xml-skos}, \ref{sect:xml-rdfprop}, or
1039 \ref{sect:xml-rdfclass} as applicable if the accept header indicates that
1040 \verb|application/rdf+xml| documents are preferred.
1041
1042 \end{itemize}
1043
1044 Individual vocabularies may be available in additional formats.
1045 Content negotiation might then consider additional media types.
1046
1047 Clients may record the full versioned URI of the vocabulary used for
1048 debug or provenance purposes. These URIs, however, must not be used
1049 externally. In particular, a URI like
1050 \url{http://www.ivoa.net/rdf/example/2019-07-14/example.html#term} has no
1051 RDF meaning by this standard and must never be used in publicly visible
1052 RDF triples. Always use URIs of the form
1053 \url{http://www.ivoa.net/rdf/example#term}.
1054
1055 \appendix
1056 \section{The 2019 IVOA Vocabulary Toolset (non-normative)}
1057 \label{app:tools}
1058
1059 This appendix describes the recommended toolset for authoring IVOA
1060 vocabularies as of 2019. Vocabulary authors may decide to use other
1061 tools but should consider that that may incur additional work for the
1062 chair of the Semantics WG in later maintenance.
1063
1064 This appendix is non-normative. It will serve as documentation of the
1065 toolset and will occasionally be updated as the tooling evolves;
1066 vocabulary authors are still advised to inspect documentation within the
1067 tools. Even major changes here will not lead to a new major version of
1068 the standard.
1069
1070
1071 \subsection{Input Format}
1072
1073 In the current tooling, RDF class and property
1074 vocabularies are authored in simple CSV files
1075 with five columns. These columns are:
1076
1077 \begin{description}
1078 \item[term]
1079 This is the actual, machine-readable vocabulary term. Only use
1080 letters, digits, underscores, and dashes here. As specified in
1081 sect.~\ref{sect:voccontent}, these identifiers should attempt to be
1082 human-readable, even though they are not directly intended for human
1083 consumption (clients will use the label). In the interest of
1084 reasonably compact URIs we advise to keep the length of the
1085 terms below, say, 30 characters.
1086 \item[level]
1087 This is used for simple input of wider/narrower relationships.
1088 It must be 1 for ``root'' terms. Terms with level of 2 that follow a
1089 root term becomes its children (``narrower''); you can nest, i.e., have
1090 terms of level 3 below terms of level 2. Note that this means the
1091 order of rows must be preserved in the CSV files: Do \emph{not} sort
1092 vocabulary CSVs.
1093 \item[label]
1094 This is a short, human-readable label for the term. In the VO, this
1095 is generally derived fairly directly from subject, ususally by
1096 inserting blanks at the right places and fixing capitalisation.
1097 \item[description]
1098 This is a longer explanation of what the term means. We do not
1099 support any markup here, not even paragraphs, so there is probably a
1100 limit to how much can be communicated.
1101 \item[more\_relations]
1102 This column enables the declaration of non-hierarchical relationships
1103 and contains whitespace-separated declarations. Each declaration has
1104 the form property[(term)]. Omitting the term is allowed for certain
1105 properties; in RDF, this corresponds to a blank node. See below for
1106 the common properties supported here. Plain terms are references
1107 within the vocabulary, but CURIEs with known prefixes or full URIs are
1108 admitted, too.
1109 \end{description}
1110
1111 Non-ASCII characters are allowed in label and description; files must be
1112 in UTF-8.
1113
1114 The following properties are supported in the more\_relationships
1115 column:
1116
1117 \begin{itemize}
1118 \item \vocterm{ivoasem:deprecated} -- see sect.~\ref{sect:genprop}.
1119 \item \vocterm{ivoasem:useInstead} -- see sect.~\ref{sect:genprop}.
1120 \item \vocterm{ivoasem:preliminary} -- see sect.~\ref{sect:genprop}.
1121 \end{itemize}
1122
1123 \subsection{Vocabulary Metadata}
1124 \label{sect:vocmeta}
1125
1126 Global vocabulary metadata is kept an INI-style format. The following
1127 keys are understood:
1128
1129 \begin{description}
1130 \item[timestamp]
1131 A manually maintained date of the last modification. This is
1132 essentially a version marker and should be changed only in preparation
1133 for a release. If is recommended to set it to the intended release
1134 date during development and not change it for every edit.
1135 \item[title]
1136 A human-readable short phrase saying what the vocabulary describes.
1137 \item[type]
1138 One of \textit{rdfclass}, \textit{rdfproperty}, or \textit{skos}
1139 (where skos currently expects RDF/XML serialised SKOS rather than CSV).
1140 \item[description]
1141 A longer text (about a paragraph) stating what the vocabulary should
1142 be used for. No markup is supported here.
1143 \item[authors]
1144 Persons involved with the creation of the standard. These are \emph{not}
1145 the persons to ask for maintenance; all requests for changes should be
1146 directed to the Semantics working group first.
1147 \item[filename]
1148 If the source file is not kept in its standard place,
1149 \verb|<vocabulary name>/terms.csv|, give
1150 the source file name here. This is to support legacy
1151 vocabularies and native SKOS input.
1152 \item[draft]
1153 While a vocabulary is still being reviewed in its entirety, add a key
1154 draft set to \texttt{True}. This will add language to the effect that
1155 terms may still vanish from the vocabulary and mark all terms as
1156 preliminary. Once the vocabulary is approved, this key is deleted.
1157 \end{description}
1158
1159 Currently, the global metadata is maintained in a file
1160 \verb|vocabs.conf| in the root of the vocabulary repository, with one
1161 section per vocabulary. The section name is the vocabulary name.
1162
1163 \subsection{Vocabulary Repository}
1164
1165 Vocabulary authors are encouraged to maintain their vocabularies in the
1166 shared version control system of the IVOA. At the time of writing, this
1167 is a subversion repository at
1168 \url{https://volute.g-vo.org/svn/trunk/projects/semantics/vocabularies}.
1169
1170 Authors of new vocabularies should create a child directory and place
1171 their terms.csv file in there. They should then edit \verb|vocabs.conf|
1172 and add a section named after their directory with the content discussed
1173 in sect.~\ref{sect:vocmeta}.
1174
1175 \section{Current Network Resources (non-normative)}
1176 \label{app:curtech}
1177
1178 This appendix details network resources used in vocabulary management.
1179 It is non-normative and will occasionally be updated as the IVOA's
1180 infrastructure evolves. Even major changes here will not lead to a new
1181 major version of the standard.
1182
1183 The list of vocabulary enhancement proposals is maintained in the IVOA's
1184 wiki at
1185 \url{https://wiki.ivoa.net/twiki/bin/view/IVOA/WebHome?topic=VEPs}.
1186 Approved VEPs will be moved to an archive page linked there.
1187 VEPs may be added as attachments to this page, but authors are
1188 encouraged to maintain them in version controlled repositories instead.
1189 The recommended place to do that is
1190 \url{https://volute.g-vo.org/svn/trunk/projects/semantics/veps}.
1191
1192 The discussion of VEPs (see sect.~\ref{sect:approval}) is to take place
1193 on the appropriate mailing list(s). See
1194 \url{http://ivoa.net/members/index.html} for a directory of IVOA mailing
1195 lists and their addresses.
1196
1197 \section{Changes from Previous Versions}
1198
1199 No previous versions yet.
1200 % these would be subsections "Changes from v. WD-..."
1201 % Use itemize environments.
1202
1203
1204 % NOTE: IVOA recommendations must be cited from docrepo rather than ivoabib
1205 % (REC entries there are for legacy documents only)
1206 \bibliography{local.bib,ivoatex/ivoabib,ivoatex/docrepo}
1207
1208
1209 \end{document}

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26