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. Users must have the “GDS Editor” permission in content-tagger in order to see the relevent pages.

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.

This means that taxons inherit the publishing-api workflow, and can be in either draft state or published.

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.

Pages that belong to selected organisations (like those related to the education theme) can be tagged to the taxonomy in 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

The top level taxons are associated with the GOV.UK home page through the root_taxons link type.

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

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

It is visible on gov.uk/education

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

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 #taxonomy and needs to be reviewed