/[volute]/trunk/projects/semantics/vocabularies/README
ViewVC logotype

Contents of /trunk/projects/semantics/vocabularies/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5582 - (show annotations)
Thu Aug 15 09:59:37 2019 UTC (23 months, 1 week ago) by msdemlei
File size: 6109 byte(s)
Vocabularies management software: First stage of vocinvo2 update.

That is: Basic features for CSV-based grammars work.


1 This directory contains "generic" vocabularies not (or no longer)
2 associated to a single standard, as well as the recommended
3 infrastructure to build and maintain vocabularies (you *can*
4 use other RDF tools as well, of course).
5
6
7 Repository Organisation
8 =======================
9
10 In this repository, each vocabulary is in a subdirectory of its own; the
11 directory structure copies what is eventually on ivoa.net; vocabulary
12 names with several segments ("datalink/core", "voresource/relationship")
13 are supported but discouraged.
14
15 In each subdirectory, a file terms.csv contains the actual terms.
16
17 Per-vocabulary metadata is given in a single file in the root of the
18 repository called vocabs.conf. This, in particular, controls the
19 versioning of the vocabularies. See below for a discussion of its
20 format.
21
22
23 Defining Vocabularies
24 =====================
25
26 By default, our vocabularies are kept in CSV files. The CSV separator
27 is ";". Since our descriptions will have lots of commas in them, this
28 helps to keep the necessity for quoting low.
29
30 The columns or the CSVs are:
31
32 subject; level; label; description; more_relations
33
34 The fields mean:
35
36 :term:
37 This is the actual, machine-readable vocabulary term. Please only use
38 letters, digits, underscores, and dashes here. It is *not* intended
39 for human consumption as such, although in the VO we prefer terms that
40 make sense in English.
41 :level:
42 This is used for simple input of wider/narrower relationships.
43 It must be 1 for “root” terms. Terms with level of 2 that follow a
44 root term becomes its children (“narrower”); you can nest, i.e., have
45 terms of level 3 below terms of level 2. Note that this means the
46 order of rows must be preserved in our CSV files: Do *not* sort them
47 and then save them.
48 :label:
49 This is a short, human-readable label for the term. In the VO, this
50 is generally derived fairly directly from subject, ususally by
51 inserting blanks at the right places and fixing capitalisation.
52 :description:
53 This is a longer explanation of what the term means. We do not
54 support any markup here, not even paragraphs, so there is probably a
55 limit how much can be communicated here.
56 :more_relations:
57 This column enables the declaration of non-hierarchical relationships
58 and contains whitespace-separated declarations. Each declaration has
59 the form property[(term)]. See below for the common properties
60 supported here. Plain terms are references within the vocabulary, but
61 CURIEs with known prefixes or full URIs are admitted, too.
62
63 Non-ASCII characters are allowed in label and description; files must be
64 in UTF-8.
65
66 It is recommended to have, in addition to the terms.csv, a README in
67 each vocabulary directory; this can contain internal notes, todo items,
68 backwards compatibility considerations, and the like.
69
70
71 Defining Vocabulary Metadata
72 ============================
73
74 Vocabularies maintained in our CSV format are converted to standard RDF
75 formats and directory structures deployable on apache web servers
76 (typically, on the IVOA semantics repository, http://ivoa.net/rdf) using
77 the little python program convert.py. It is configured using
78 vocabs.conf, which in turn is a simple INI-style file containing one
79 section per vocabulary. Here is an example section::
80
81 [reference_positions]
82 timestamp: 2019-03-15
83 title: Interoperable VO reference positions
84 type:rdfclass
85 description: This vocabulary enumerates reference positions for
86 which positions and times in the Virtual Observatory can be given.
87 It is intended that clients, on encountering such a declaration, can
88 transform coordinates automatically on behalf of the user, or,
89 failing that because of missing data or implementation limitations,
90 at least adjust the systematic error of the associated values.
91 authors: Rots, A.; Demleitner, M.; Cresitello-Dittmar, M.
92
93 The section header gives the name of the directory from which to read
94 the terms.csv. It can contain multiple path segments if absolutely
95 necessary. Each segments should only contain lowercase letters and
96 underscore characters.
97
98 The configuration items have the following meanings:
99
100 :timestamp:
101 A manually maintained date of the last modification. This is
102 essentially a version marker and should be changed only in preparation
103 for a release. If is recommended to set it to the intended release
104 date during development and not change it for every edit.
105 :title:
106 A human-readable short phrase saying what the vocabulary describes.
107 :type:
108 One of rdfclass, rdfproperty, or skos (where the toolset currently
109 does not support skos)
110 :description:
111 A longer text (about a paragraph) stating what the vocabulary should
112 used for. No markup is supported here.
113 :authors:
114 Persons involved with the creation of the standard. These are *not*
115 the persons to ask for maintenance; all requests for changes should be
116 directed to the semantics working group.
117 :draft:
118 While a vocabulary is still being reviewed in its entirety, you should
119 add a key draft set to ``True``. This will add language to the effect
120 that terms may still vanish from the vocabulary. Once the vocabulary
121 is approved, delete the draft key.
122
123
124 Deployment
125 ==========
126
127 To have a local installation, decide on a location from where you'll
128 serve your vocabularies; since we currently generate apache .htaccess
129 files only, this should be served by an apache HTTP server. Then, call
130 ``make local`` with ROOT_URI set to that root URL, e.g.,::
131
132 python convert.py --root-uri http://docs.g-vo.org/rdf vocabs.conf
133
134 The result of this is a file local.tar.gz. Move that to the directory
135 corresponding to the ROOT_URI and ``tar -xvzf`` it.
136
137 In order for the .htaccess configuration to work, that directory (or one
138 of its ancestors) has to be configured to interpret FileInfo
139 content. This would look like this::
140
141 <Directory /var/www/docs/rdf>
142 AllowOverride FileInfo
143 </Directory>
144
145 Also, mod_rewrite must be enabled.
146
147 You will then see the hierarchy of the vocabularies. Clicking on a link
148 to a vocabulary you should be taken to its latest version.

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