Package: django-controlled-vocabulary
Advanced topics (Wiki)Django Controlled VocabularyThis app provides models and admin interface to link your data to standard vocabularies (e.g. ISO language codes, Wikidata). Benefits: increases the consistency and understandability of your project data.Requirements: Python 3.5+, Django 2.2+Development Status:BetaA ControlledTerm field in the Django admin interface. The user selects the vocabulary (here: Wikidata), then starts typing a term in the text box. Suggestions are brought from Wikidata. When the user saves the changes, information about the selected term is copied into the database (url, identifier, label).Featurescreate your own controlled lists of terms (i.e. alocallists, project-specific)look up terms fromstandard vocabularies(i.e.authority filesmaintained by other organisations)extensibleplug-in architecturefor lookups into particular vocabularies (see table below for built-in plugins)storesused terms from remote vocabularies into your database:space efficient (doesn't clutter the database with unused terms)self-contained (i.e. can still works offline & DB always 'semantically' complete)autocompletewidget for Django admin; reusable ControlledTermField for your modelscommand line toolto download vocabulary files from authoritative sources[TODO] possibility to store additionalmetadata(e.g. geographic coordinates)[TODO] simplerest APIto publish your own termsStandard vocabularies includedBuilt-in plugins for the following authority files:VocabularyDescriptionSchema.orgHigh-level categories of contentWikidataHigh level concepts or specific instances (e.g. places, people)ISO 639-2Language codesDCMI TypeDublin Core Format TypeMIMEMedia/File typesFAST TopicsTopic categorisationFAST Forms and GenresGenres of a piece of workVIAFVarious: regions, people, companies, ...Data Model & Software DesignDjango modelsVocabulariesTermsControlledVocabularyprefix: the vocabulary standard prefix, seehttp://prefix.cc/wikidatalabel: the short name of the vocabularybase_url: the url used as a base for all terms in the vocabularyconcept: the type of terms this vocabulary represents (e.g. language, people)description: a longer descriptionControlledTermtermid: a unique code for the term within a vocabulary, it is case sensitivelabel: standard name for the term, as provided by the authorityvocabulary: a reference to the ControlledVocabulary this term belongs toConventions:joining base_url (e.g.http://schema.org) with termid (e.g. Movie)mustgive the exact standard/canonical URI for the term, e.g.http://schema.org/MovieVocabulary plug-ins / managersA Vocabularyplug-in/manageris a python class that provides services for a vocabulary:autocomplete terms from local or remote datasets (see ControlledTermField)supplies metadata for the vocabulary (see ControlledVocabulary)Managers can provide terms from a CSV file downloaded from an authoritative source.Some vocabularies can contain thousands of terms or more. A plugin will
only insert the terms used by your application. The rest will be accessed on
demand from a file on disk or in a third-party server. This approach saves
database space and keeps your application data self-contained.This project comes with built-in plugins such a Wikidata or Schema.org. Those plugins areenabledby default; see below how to selectively enable them.This architecture allows third-party plugins to be supplied via separate
python packages.Limitationscontrolled listrather than fully fledged vocabularies, (i.e. just a bag of terms with unique IDs/URIs, no support for taxonomic relationships among terms like broader, narrower, synonyms, ...)no notion of granularity (e.g. geonames country, region, city, street are all treated as part of the same vocabulary)SetupInstallationInstall into your environment:pipinstalldjango-controlled-vocabularyAdd the app to the INSTALLED_APPS list in your Django settings file:INSTALLED_APPS=[...'controlled_vocabulary',...]Add the following path to your project urls.py:fromdjango.urlsimportpath,include...urlpatterns=[...path('vocabularies/',include('controlled_vocabulary.urls')),...]Run the migrations:./manage.pymigrateDownload vocabulary data and add metadata to the database:./manage.pyvocabinitConfigurationEnabling specific vocabulary plug-ins (optional)Currently all built-in plugins / managers are enabled by default. Add the following code in your settings.py to enableonlyspecific vocabularies based on the import path of their classes. You can also use this to enable your own or third-party plugins.# List of import paths to vocabularies lookup classesCONTROLLED_VOCABULARY_VOCABULARIES=['controlled_vocabulary.vocabularies.iso639_2','controlled_vocabulary.vocabularies.dcmitype',]After enabling a new plug-in / manager, always run./manage.py vocab init.ControlledTerm(s)FieldUse theControlledTermFieldfield to define a field with anautocompleteto controlled terms in your Django Model:fromcontrolled_vocabulary.modelsimportControlledTermField...classMyModel(models.Model):...language_code=ControlledTermField('iso639-2',null=True,blank=True)Whereiso639-2is the prefix of a controlled vocabulary in your database.ControlledTermField is essentially syntactic sugar for aForeignKeyFieldwith an adaptedSelectwidget.For multiple values, you can useControlledTermsField(note the 's' in the name), which inherits from ManyToManyField with an adapted SelectMultiple widget. The useage is identical but obviouslynull=Trueshould be omitted.By default the widget proposes the given vocabulary to the end user, but they can use the dropdown to switch to any other available vocabulary (see screenshot at the top of this page). Tolockthe selection to a single vocabulary, use this expression instead:language_code=ControlledTermField(['iso639-2'],null=True,blank=True)You can have more than one prefix in that list if you want. The first item is always the one proposed by default on page load.vocab (command line tool)vocab is a django command line tool that lets you manipulate the vocabularies
and the plugins. To find out more use the help:./managevocabhelp