Table of contents

Taxonomy

GOV.UK’s “single subject taxonomy” will describe all content on GOV.UK. It is being developed theme-by-theme, starting with education.

1. Editing taxonomy

The taxonomy is managed in content-tagger.

The topics in the taxonomy (we call them “taxons” in code) are persisted in the publishing-api as content items. For an example see the “Education” taxon.

The link type parent_taxons is used to store the relationship between taxons. Link expansion makes sure that the taxons will have a child_taxons link type too.

2. Tagging

All pages can be tagged to the taxonomy, currently in content-tagger too.

In the future, editors will also be able to tag to the taxonomy in publishing apps like Whitehall.

The relationship between a page and a taxon is persisted in the publishing-api “links hash”. For example, see the taxons link in the content item for this guidance document.

3. Accessing the taxonomy

This is the content item for the top-level “Education” taxon:

https://www.gov.uk/api/content/education

You can use this to find the structure of the taxonomy by following the child_taxons links.

To manipulate and browse taxonomies in ruby code, use the govuk_taxonomy_helpers gem.

4. Accessing tagged content

All content tagged to a particular taxon you fetch from the search API (rummager).

This works with a content_id rather than URL. To find all content tagged to the above mentioned “Education taxon”:

https://www.gov.uk/api/search.json?filter_taxons[]=c58fdadd-7743-46d6-9629-90bb3ccc4ef0

You can also access all content tagged to a taxon and the part of the taxonomy below it. The following will give you everything tagged to topics in the “Education” taxonomy:

https://www.gov.uk/api/search.json?filter_part_of_taxonomy_tree[]=c58fdadd-7743-46d6-9629-90bb3ccc4ef0&fields=title,taxons,part_of_taxonomy_tree

You can see the number of documents in each topic by using taxons as a facet:

https://www.gov.uk/api/search.json?filter_part_of_taxonomy_tree=c58fdadd-7743-46d6-9629-90bb3ccc4ef0&facet_taxons=1000&count=0

This page is owned by @tijmen and needs to be reviewed