Creating a custom controlled vocabulary via YAML

Overview

When the custom controlled vocabulary is small and does not change often, the easiest approach is to define the set of terms by listing them in a YAML file. The states vocabulary is an example of this kind of custom controlled vocabulary that is provided by QA.

Prerequisites

Define the terms in a YAML file in the config/authorities directory. The name of the file becomes the subauthority name used under the local authority.

Supported formats

List of id and term keys and, optionally, active key

The following is an example custom controlled vocabulary and is assumed to be defined in config/authorities/full_example.yml for the purpose of examples in this documentation.

terms:
	- id: id1
	  term: Term 1
	  active: true
	- id: id2
	  term: Term 2
	  active: false
	- id: id3
	  term: Term 3
	- id: id4
	  term: Another term
	- id: id5
	  term: Something else

NOTE: If a term is marked active: false, that term will not be returned by search, but will be in the listing of all terms. If active is not defined, it is assumed to be true.

List of terms

The following is an example custom controlled vocabulary and is assumed to be defined in config/authorities/min_example.yml for the purpose of examples in this documentation.

terms:
	- Term 1
	- Term 2
	- Term 3
	- Another term
	- Something else

NOTE: In this simple form, the id and term are the same.

Accessing via QA

Authority:	local

Subauthorities:

• name_of_the_yml_file (e.g. full_example.yml has the subauthority name full_example)

---

Example search queries

Example search subauthority full_example:

/qa/search/local/full_example?q=Term

Result:

[
  {"id":"id1","label":"Term 1"},
  {"id":"id2","label":"Term 2"},
  {"id":"id3","label":"Term 3"},
  {"id":"id4","label":"Another term"}
]

NOTES:

• Search searches terms, but not IDs. If you search for q=id, the result set will be empty.
• Search is NOT case-sensitive. The result set is the same when searching for q=term.
• Inactive terms ARE included in the result set, which is why the result set includes {"id":"id2","label":"Term 2"}.

Example search subauthority min_example:

/qa/search/local/min_example?q=Term

Result:

[
  {"id":"Term 1","label":"Term 1"},
  {"id":"Term 2","label":"Term 2"},
  {"id":"Term 3","label":"Term 3"},
  {"id":"Another term","label":"Another term"}
]

---

Example term fetch request

Example fetch an active term from subauthority full_example:

/qa/show/local/full_example/id1

Result:

{"id":"id1","term":"Term 1","active":true}

Example fetch an inactive term from subauthority full_example:

/qa/show/local/full_example/id2

Result:

{"id":"id2","term":"Term 2","active":false}

Example fetch from subauthority full_example when active is not set:

/qa/show/local/full_example/id3

Result:

{"id":"id3","term":"Term 3"}

Example fetch from subauthority min_example:

/qa/show/local/min_example/Term 3

Result:

{"id":"Term 3","term":"Term 3"}

---

Example list all terms

List of terms for custom vocabulary full_example

/qa/terms/local/full_example

Result:

[
  {"id":"id1","label":"Term 1","active":true},
  {"id":"id2","label":"Term 2","active":false},
  {"id":"id3","label":"Term 3","active":true},
  {"id":"id4","label":"Another term","active":true}
  {"id":"id5","label":"Something else","active":true}
]

List of terms for custom vocabulary min_example

/qa/terms/local/min_example

Result:

[
  {"id":"Term 1","label":"Term 1","active":true},
  {"id":"Term 2","label":"Term 2","active":true},
  {"id":"Term 3","label":"Term 3","active":true},
  {"id":"Another term","label":"Another term","active":true}
  {"id":"Something else","label":"Something else","active":true}
]

---

Documentation

This is a locally defined controlled vocabulary and does not have any associated documentation.