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

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{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 554 Compound object 555 557 559 561 A composite object is made of at least two 562 distinct astronomical objects 563 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 632 A serialisation of an array used to subtract 633 the detector offset level. 634 Bias calibration data 635 637 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 648 A serialisation of an array used to subtract 649 the detector offset level. 650 Bias calibration data 651 652 653 655 657 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 734 736 FK5 737 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 742 744 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|#| 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|/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}