Adding a Default Vocabulary Validator

What is a Vocabulary Validator?

Vocabulary Validators allow users to check a broad range of properties that fall under a single property category with minimal work. Generally these are used for default checks, because there are many possible specific properties with the exact same valid values. For example, 'Creator,' 'Composer,' 'Designer,' and 'Translator' are all under the 'Creator' property category. Accordingly, they share the same 'Creator' controlled vocabulary, which itself has various vocabularies that make up the valid URIs possible for the 'Creator' controlled vocabulary and field. In other words, multiple properties correspond to a single controlled vocabulary, which is made up of multiple valid vocabularies.

By creating a vocabulary validator, you're choosing which properties correspond to a controlled vocabulary, and which vocabularies are valid URI formats for that controlled vocabulary. The program (process.py) will use this to check any fields that match the ones you've chosen against the vocabularies you've associated with the controlled vocabulary.

So it looks like: Properties --> Controlled Vocabulary / Property Category --> Vocabularies --> Specific Vocabulary URI format

Important Note: If you want the validator to run by default, you must add the check to default.yaml

How Do I Set Up a Vocabulary Validator?

1. Add Property Category to validation_mappings.yaml

Under config/validation_mappings.yaml, add a new key to the field_validators key. It should be named your whatever your Property Category / Controlled Vocabulary is. Under it, use a dashed list (each item starts with '-') to list all possible fields that correspond to the property category.

2. Add vocabulary mapping to validation_mappings.yaml

Still in config/validation_mappings.yaml, add a new key to the controlled_vocab_map key. It should be your Property Category / Controlled Vocabulary name, just like in Step 1. Under it, use a dashed list again, but this time write out all the valid vocabularies for your controlled vocab.

3. Add a validator to vocabularies.py if necessary

If all the vocabularies you listed in Step 2 are present in VOCABULARY_VALIDATORS at the bottom of vocabularies.py, you're done and can skip this step.

If not, you need to write a regex check for a new vocabulary. First, add it to the VOCABULARY_VALIDATORS dictionary in the form the others are, as "validator : validator function" where validator is a string.

Then create a function that matches the name you just wrote in the dictionary. The function should take 1 string input. You should write a regex check to match the expected vocabulary values. If the input doesn't match what you expect, return false. If it does, return true. Preferably follow the formatting conventions used in the rest of the file.

Once you've written this function, you're done. The program now has the ability to validate a new controlled vocabulary and associate it with various fields. If you want it to do this by default, you'll need to add the check to default.yaml. For more information on how to do this, check out Custom Checks in Headers Config, but make sure to add the checks to default rather than a specific headers config.