Add an Authority

How to Add an Authority

Choosing which kind of authority

1. External (Geonames, LC etc.) - where someone else maintains the authority and provides an API
2. Local File-Based - where the list of terms is short and relatively static
3. Local Table-Based – where the list of terms is longer than sensibly supported by YAML file (eg. languages); and/or where new terms need to be added dynamically
4. Local Object-based – where we want to store the referenced resource as a repository object

External

Questioning Authority provides support for querying a range of external authorities, and can be used as a template for writing your own code for other external auths.

Local Table-Based

Consult Questioning Authority to see how to create a Table-Based authority.

See also the Hyrax Rake Task for adding languages from Lexvo as a Table-Based authority:

rake hyrax:controlled_vocabularies:language

Local File-Based Authorities

New File-Based authorities can be added into the generator very easily.

1. Create a yml file for the authority terms, following the following structure:

terms:
  - id: http://london.ac.uk/qualification_levels#masters-pg
    term: Masters (Postgraduate)
    active: true
  - id: http://london.ac.uk/qualification_levels#diploma-pg
    term: Diploma (Postgraduate)
    active: true
  - id: http://london.ac.uk/qualification_levels#bachelors-ug
    term: Bachelors (Undergraduate)
    active: true
  - id: http://london.ac.uk/qualification_levels#doctoral-pg
    term: Doctoral (Postgraduate)
    active: true

2. add the new file into lib/generators/dog_biscuits/templates/config/authorities following the pluralized naming convention (terms.yml rather than term.yml)
3. re-run the generator in the calling app with the -f flag to pull in the new authority

Note: id, term and active are required; other elements can be added into the list and will be retrieved by qa's json response without affecting current functionality.

Local Object-Based Authorities

For a new object-based authority list:

1. (a) If the Class of the terms in the list match one of the existing authority models, you don't need to add any new models:

• Agent
• Person
• HistoricPerson
• Group
• Organisation
• Place
• Concept ("an idea or notion; a unit of thought" SKOS ... something abstract, like a subject heading)
• Project
• Event

1. (b) If you need a new model, extend one of the existing ones (agent, concept) and add it into the 'has_many' list in ConceptScheme.

has_many :my_new_things, class_name: 'DogBiscuits::MyNewThing', inverse_of: :concept_scheme

2. Add a block like the following to /lib/dog_biscuits/services/terms.rb following the exact convention of using plural forms.

	class ThingsTerms < TermsService
		def terms_list
			'things'
		end
	end

3. In the application using dog_biscuits, re-run the auths generator with the -f flag to force overwriting

rails generate dog_biscuits:auths -f

The new authority list can be used to generate a pick list or autosuggest in a view in the calling application.

Note: The name of the Terms list does not need to match the Model name. Retrieving the terms relies on the existend of a ConceptScheme called 'things'.

What does this mean?

It means that in order to generate a list of things, we need a ConceptScheme object with a preflabel of 'things'. All MyNewThing objects should be added to this ConceptScheme with

concept_scheme_object.my_new_things << my_new_thing

Both File-based and Object-based authorities use the questioning authority gem. The same gem allows us to query external services like library of congress and FAST:

Have a look at lib/dog_biscuits/services/terms_service.rb to see the methods you can use to query the local terms lists, eg. get value from id, get id from value, search

And have a look at the qa documentation to see how you can use them more generally: https://github.com/projecthydra-labs/questioning_authority