doc/admin/workbench2-vocabulary.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: admin
   4 title: Workbench2 Vocabulary Format
   5 ...
   6
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 Many Arvados objects (like collections and projects) can store metadata as properties that in turn can be used in searches allowing a flexible way of organizing data inside the system.
  14
  15 The Workbench2 user interface enables the site adminitrator to set up a properties vocabulary formal definition so that users can select from predefined key/value pairs of properties, offering the possibility to add different terms for the same concept.
  16
  17 h2. Workbench2 configuration
  18
  19 Workbench2 retrieves the vocabulary file URL from the cluster config as shown:
  20
  21 <notextile>
  22 <pre><code>Cluster:
  23   zzzzz:
  24     Workbench:
  25       VocabularyURL: <span class="userinput">https://site.example.com/vocabulary.json</span>
  26 </code></pre>
  27 </notextile>
  28
  29 h2. Vocabulary definition format
  30
  31 The JSON file describes the available keys and values and if the user is allowed to enter free text not defined by the vocabulary.
  32
  33 Keys and values are indexed by identifiers so that the concept of a term is preserved even if vocabulary labels are changed.
  34
  35 The following is an example of a vocabulary definition:
  36
  37 {% codeblock as json %}
  38 {% include 'wb2_vocabulary_example' %}
  39 {% endcodeblock %}
  40
  41 If the @strict_tags@ flag at the root level is @true@, it will restrict the users from saving property keys other than the ones defined in the vocabulary. Take notice that this restriction is at the client level on Workbench2, it doesn't limit the user's ability to set any arbitrary property via other means (e.g. Python SDK or CLI commands)
  42
  43 Inside the @tags@ member, IDs are defined (@IDTAGANIMALS@, @IDTAGCOMMENT@, @IDTAGIMPORTANCES@) and can have any format that the current application requires. Every key will declare at least a @labels@ list with zero or more label objects.
  44
  45 The @strict@ flag inside a tag definition operates the same as the @strict_tags@ root member, but at the individual tag level. When @strict@ is @true@, a tag’s value options are limited to those defined by the vocabulary.
  46
  47 The @values@ member is optional and is used to define valid key/label pairs when applicable. In the example above, @IDTAGCOMMENT@ allows open-ended text by only defining the tag's ID and labels and leaving out @values@.
  48
  49 When any key or value has more than one label option, Workbench2's user interface will allow the user to select any of the options. But because only the IDs are saved in the system, when the property is displayed in the user interface, the label shown will be the first of each group defined in the vocabulary file. For example, the user could select the property key @Species@ and @Homo sapiens@ as its value, but the user interface will display it as @Animal: Human@ because those labels are the first in the vocabulary definition.
  50
  51 Internally, Workbench2 uses the IDs to do property based searches, so if the user searches by @Animal: Human@ or @Species: Homo sapiens@, both will return the same results.