[Volute] r5259 - trunk/projects/semantics/genericvoc

Volute commit messages volutecommits at g-vo.org
Thu Dec 6 09:58:31 CET 2018


Author: msdemlei
Date: Thu Dec  6 09:58:31 2018
New Revision: 5259

Log:
semantics vocabularies: Started a readme.

Modified:
   trunk/projects/semantics/genericvoc/README

Modified: trunk/projects/semantics/genericvoc/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).
 
+
+Defining vocabularies
+=====================
+
+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:
+
+:term:
+  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.
+:level:
+  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.
+:label:
+  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.
+:description:
+  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.
+:synonym: 
+  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
+in UTF-8.
+
+
+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::
+
+  [content_level]
+  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:
+
+:baseuri:
+  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.
+:timestamp:
+  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.
+:title:
+  A human-readable short phrase saying what the vocabulary describes.
+ description:
+  A longer text (about a paragraph) stating what the vocabulary should
+  used for.  No markup is supported here.
+:authors:
+  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 mailing list