[Volute] r5259 - trunk/projects/semantics/genericvoc
Volute commit messages
volutecommits at g-vo.org
Thu Dec 6 09:58:31 CET 2018
Date: Thu Dec 6 09:58:31 2018
New Revision: 5259
semantics vocabularies: Started a readme.
--- trunk/projects/semantics/genericvoc/README Thu Dec 6 09:30:28 2018 (r5258)
+++ trunk/projects/semantics/genericvoc/README Thu Dec 6 09:58:31 2018 (r5259)
@@ -3,3 +3,92 @@
infrastructure to build and maintain vocabularies (you *can*
use other RDF tools as well, of course).
+By default, our vocabularies are kept in CSV files. The CSV separator
+is ";". Since our descriptions will have lots of commas in them, this
+helps to keep the necessity for quoting low.
+The columns or the CSVs are:
+subject; level; label; description; synonym
+The fields mean:
+ This is the actual, machine-readable vocabulary term. Please only use
+ letters, digits, underscores, and dashes here. It is *not* intended
+ for human consumption as such, although in the VO we prefer terms that
+ make sense in English.
+ This is used for simple input of wider/narrower relationships.
+ It must be 1 for “root” terms. Terms with level of 2 that follow a
+ root term becomes its children (“narrower”); you can nest, i.e., have
+ terms of level 3 below terms of level 2. Note that this means the
+ order of rows must be preserved in our CSV files: Do *not* sort them
+ and then save them.
+ This is a short, human-readable label for the term. In the VO, this
+ is generally derived fairly directly from subject, ususally by
+ inserting blanks at the right places and fixing capitalisation.
+ This is a longer explanation of what the term means. We do not
+ support any markup here, not even paragraphs, so there is probably a
+ limit how much can be communicated here.
+ If given, it references the “canonical” term for the concept. This is
+ used when vocabularies evolve and terms are deprecated. If a term has
+ a natural successor, it is given here. Synonyms should not be used
+ outside of that very special situation.
+Non-ASCII characters are allowed in label and description; files must be
+Building Web Resources
+Vocabularies maintained in our CSV format are converted to standard RDF
+formats and directory structures deployable on apache web servers
+(typically, on the IVOA semantics repository, http://ivoa.net/rdf) using
+the little python program convert.py. It is configured using
+vocabs.conf, which in turn is a simple INI-style file containing one
+section per vocabulary. Here is an example section::
+ baseuri: http://www.ivoa.net/rdf/voresource/content_level
+ timestamp: 2016-08-17
+ title: Content levels for VO resources
+ description: This vocabulary enumerates the intended audiences
+ for resources in the Virtual Observatory. It is designed to
+ enable discovery queries like "only research-level data" or
+ "resources usable in school settings".
+ authors: Ray Plante; Markus Demleitner
+The section header is largely arbitrary, but it should be identical to
+the vocabulary name, which in turn is the last element of the baseuri.
+The configuration items have the following meanings:
+ The vocabulary URI. These should always be of the form
+ ``http://www.ivoa.net/rdf/<vocabname>`` – please do *not* follow the
+ example in introducing another level for, e.g., the related standard.
+ Vocabularies are very typically applicable in multiple standards and
+ should not be bound to one, not even by URI. Please only use
+ lowercase characters and underscores in your vocabulary names.
+ A manually maintained date of the last modification. This is
+ essentially a version marker and should be changed only in preparation
+ for a release. If is recommended to set it to the intended release
+ date during development and not change it for every edit.
+ A human-readable short phrase saying what the vocabulary describes.
+ A longer text (about a paragraph) stating what the vocabulary should
+ used for. No markup is supported here.
+ Persons involved with the creation of the standard. These are *not*
+ the persons to ask for maintenance; all requests for changes should be
+ directed to the semantics working group.
More information about the Volutecommits