Custom vocabularies¶

The custom-vocabulary:* commands manage the controlled lists of the Custom Vocab module: a fixed list of terms, a list of URIs with labels, or the items of an item set. You export a vocabulary to a JSON file and import that file into another installation, so the lists stay the same across environments.

Install the Custom Vocab module¶

The commands need the Custom Vocab module to be installed and active; without it they fail with This action requires the 'CustomVocab' module.

omeka-s-cli module:download customvocab --install

See modules for more about installing modules.

Import a vocabulary¶

custom-vocabulary:import reads a JSON file (or a URL) in the format of the module's own export. A vocabulary of plain terms lists them in o:terms:

{
    "o:label": "Condition",
    "o:lang": "en",
    "o:terms": [
        "Excellent",
        "Good",
        "Fair",
        "Poor"
    ]
}

omeka-s-cli custom-vocabulary:import conditions.json

A vocabulary of URIs maps each URI to its label in o:uris:

{
    "o:label": "Language",
    "o:lang": "en",
    "o:uris": {
        "http://id.loc.gov/vocabulary/iso639-2/dut": "Dutch",
        "http://id.loc.gov/vocabulary/iso639-2/eng": "English",
        "http://id.loc.gov/vocabulary/iso639-2/fre": "French"
    }
}

omeka-s-cli custom-vocabulary:import languages.json

Vocabularies are matched by label, case-insensitively. If a vocabulary with the same label exists, the import is skipped with a warning (exit code 0); add --update to replace its terms, URIs and language with those of the file:

omeka-s-cli custom-vocabulary:import conditions.json --update

To update a specific vocabulary, name it (by ID or label) after the file; that implies --update. --label sets the label, overriding the one in the file, so this renames the vocabulary:

omeka-s-cli custom-vocabulary:import conditions.json Condition --label "Object condition"

Import an item set vocabulary¶

A vocabulary can also offer the items of an item set. Item set IDs differ between installations, so the file refers to the item set by a property value, here its dcterms:identifier:

{
    "o:label": "Collection",
    "o:lang": "en",
    "o:item_set": {
        "property": "dcterms:identifier",
        "value": "urn:example:item-set:photographs"
    }
}

omeka-s-cli custom-vocabulary:import collections.json

The item set must exist before the import, and exactly one item set may have that value: the import fails if none or several match.

List vocabularies¶

omeka-s-cli custom-vocabulary:list
omeka-s-cli custom-vocabulary:list --json | jq -r '.[].label'

+----+------------+------+----------+-------+
| Id | Label      | Lang | Type     | Owner |
+----+------------+------+----------+-------+
| 1  | Condition  | en   | literal  | Admin |
| 2  | Language   | en   | uri      | Admin |
| 3  | Collection | en   | resource | Admin |
+----+------------+------+----------+-------+
Condition
Language
Collection

The type is literal for terms, uri for URIs and resource for an item set. --json and --csv give the same columns in machine-readable form.

Export a vocabulary¶

custom-vocabulary:export prints the vocabulary as JSON, or writes it to the file you name. The output is the import format, so you can import it on another installation:

omeka-s-cli custom-vocabulary:export Condition
omeka-s-cli custom-vocabulary:export Language "$SCRATCH_DIR/languages.json"

An item set vocabulary is exported with a reference to its item set, by default by its dcterms:identifier. o:title is informational; the import ignores it.

omeka-s-cli custom-vocabulary:export Collection

{
    "o:label": "Collection",
    "o:lang": "en",
    "o:item_set": {
        "property": "dcterms:identifier",
        "value": "urn:example:item-set:photographs",
        "o:title": "Photographs"
    }
}

If your item sets are identified by another property, choose it with --item-set-property. The export fails when the item set has no value for that property.

omeka-s-cli custom-vocabulary:export Collection --item-set-property dcterms:title

Delete a vocabulary¶

custom-vocabulary:delete takes an ID or a label. It does not ask for confirmation.

omeka-s-cli custom-vocabulary:delete "Object condition"

id=$(omeka-s-cli custom-vocabulary:list --json | jq -r '.[] | select(.label == "Language") | .id')
omeka-s-cli custom-vocabulary:delete "$id"

A vocabulary that does not exist is an error, unless you pass --ignore-not-found; then the command only notes it and exits with 0, which makes the deletion safe to repeat:

omeka-s-cli custom-vocabulary:delete Collection --ignore-not-found
omeka-s-cli custom-vocabulary:delete Collection --ignore-not-found

Reference¶

All commands also accept the global options.

custom-vocabulary:list¶

List available custom vocabularies

omeka-s-cli custom-vocabulary:list [options]

custom-vocabulary:import¶

Import a custom vocabulary

omeka-s-cli custom-vocabulary:import [options] <source> [identifier]

custom-vocabulary:export¶

Export a custom vocabulary

omeka-s-cli custom-vocabulary:export [options] <identifier> [filename]

custom-vocabulary:delete¶

Delete a custom vocabulary

omeka-s-cli custom-vocabulary:delete [options] <identifier>