Open Referral UK Data Standard

Setting the open standard for community data

OpenreferralUk Logo

Use of Taxonomies with OpenCommunity services data



This guidance describes how the Open Referral UK data schema for services (the Schema) and the associated API standard supports use of taxonomies. It indicates how taxonomies can be used to tag services and help target searches.

What is a taxonomy?

A taxonomy (also known as a vocabulary, a concept scheme or just a list of terms) defines terms used to describe a subject area. Each term (also known as a concept or list item) has an identifier, a label and other properties, which may include alternative labels.

Inherited from the Open Referral standard, the Schema uses the the word “taxonomy” to describe a taxonomy term and “vocabulary” to describe the whole taxonomy.

Candidate taxonomies for services data

Service types

The schema (and the base Open Referral standard on which it is built) allows for any number of taxonomy terms to be associated with each service entry. Typically such terms will be drawn from vocabularies that describe types of service.

These vocabularies are suitable for describing service types:


The Schema extends the international Open Referral standard to allow definition of the types of individual eligible for a service.

These vocabularies are suitable for describing eligibility types:

Accessibility for disabilities

The Schema currently only provides for a limited set of accessibility entries. Proposals have been made (see here) for switching to use of taxonomies for accessibility terms.

This vocabulary may be considered describing service types:

We are currently trying to identify a fuller vocabulary.


The Schema does not make explicit provision for recording the circumstances of users for whom a service is suitable. However user circumstances are relevant in two ways:

These vocabularies are suitable for describing circumstance types:

The LGA’s Personal Circumstance List is mapped against its Service Types List to show which types of service might be suitable for someone with specific circumstances.


The Schema does not make explicit provision for recording the needs of users for whom a service is suitable. However needs can be mapped against service types so services of types relevant to a user’s needs can be found.

This vocabulary is suitable for describing needs:

Tagging service directory records

What to tag with terms from taxonomies

So that searches for services can be well targeted, it is useful to tag each service with one or more service types and with any relevant eligibility terms.

Personal circumstances can sometimes be assigned to services to denote “intended audience”.

It should not be necessary to tag individual services with the needs and circumstances of potential users. These can be derived from mappings to service types built into service finder and/or service directory software, as described below.

Syntax for use of taxonomy terms

Use a CURIE (or Compact URI) as a kind of namespace to identify from which vocabulary a term comes.


A local vocabulary, such as Bristol City Council’s service types list, has

The LGA’s electronic service delivery list of service types has

OpenCommunity will establish a register of CURIEs that have a common meaning across community members. Where a CURIE references a taxonomy with a formal URI, the register will give the taxonomy’s URI and the URI prefix for individual taxonomy terms.

CURIEs to use

All directories should use these CURIEs for national/international vocabularies:

Publishers are free to devise their own CURIEs for local lists. They may use the authority name abbreviated eg “BCC:” or “Bristol:”, “Hull:”.

We normally expect CURIEs to be in the singular, so  “esdServiceType”, not “esdServiceTypes”.

Targeting services at specific user groups

The Schema and, in particular, its extensions to Open Referral is designed to target quite accurately the services relevant to someone who is searching a directory.

You can store information and search according to:

The Schema supports use of any given taxonomy, including taxonomies local to an installation as well as national and international ones, such as those given above.

Using taxonomies with the API

The standard API’s web method for getting services is defined here.

It includes filter parameters for:

The taxonomy search looks for a given taxonomy term (eg service type 298 - Carers support groups) from a given vocabulary (eg the LGA’s Service Types list) associated with a particular type of data (eg service, service eligibility, organization).

Hence this call is used to find all services of service type 298 in the LGA Service Type list:


Note that all the above filter parameters are applied with a Boolean AND operator. Hence the above syntax cannot be used to find services with one of a number of given service types via a single API call.

Selecting services for particular service types, circumstances and needs

The service_type, circumstance and need parameters are special calls implemented by some instances of the services API to allow selection using a Boolean AND of taxonomy terms.

These parameters allow arrays of service type, need and circumstance identifiers from the LGA’s taxonomies to be called.


/services/?service_types=esdServiceType:298service_types=esdServiceType:1755 finds services of types 298 - Carers support groups and/or 1755 - Carers assessment.

/services/?circumstance=esdCircumstance:Gender_Female&circumstance=esdCircumstance:AddictSubstanceAbuser_Smoking finds services of types associated with circumstance Gender_Female - Female and/or AddictSubstanceAbuser_Smoking - Smoker.

/services/?need=esdNeed:69&esdNeeds=need:71 finds services of types associated with needs 69 - Social inclusion and/or 71 - Community facilities


Service Finder utilities can be configured to filter services according to their target groups.

The sample service finder here (see here for source code) illustrates how “personas” can be used for quick filtering according to target groups.

ServiceFinder homepage

A Service Finder tool can either be with a set of service types applicable to the personas it supports or configured directly with the needs as circumstances associated with those personas, as described below.

Configuring personas with service types

Owners of service finder tools are usually best placed to understand the service types that are applicable to the personas of their audience. These may come from one or more service type vocabularies. The service types chosen may be informed by external mappings, such as those maintained by the LGA from lists of needs and circumstances.

A JSON configuration of a persona by service types might look like this:

"persona": [{
  "value": 0,
  "label": "Lonely",
  "data": {
    "service_types": [
      "esdServiceType:1149", "esdServiceType:296", "esdServiceType:297", "Snowmed:228553007", "OAActivity:angling"

Configuring personas with needs and service types

Some service directories may implement means of making API queries for a specified list of needs and/or circumstances. In such cases, the directory itself needs to host and maintain mappings from needs and circumstances to service types.

The LGA’s illustrative open source service directory does this usings mappings from LGA defined needs and circumstances to LGA service types. Hence the illustrative open source service finder can configure personas based on needs and circumstances, relying on the directory to lookup service types and retrieve corresponding services.

The service finder’s config.js JSON format file gives named sets filter criteria to be applied to a search for services. The example below shows how it associates the “Lonely” persona with relevant needs and circumstances.

"persona": [{
  "value": 0,
  "label": "Lonely",
  "data": {
    "needs": [
      "69", "71", "111", "115", "67", "36", "66", "68"
    "circumstances": [
      "Gender_Female", "AddictSubstanceAbuser_Smoking"

Referencing Local Government Association taxonomies and mappings

The LGA supports these relevant taxonomies:

The URIs for these taxonomies and for their taxonomy items resolve to web pages where more information can be found, including a “Downloads” tabbed page for each list and each mapping to another list in CSV of XML format. Signed in users of the standards pages can subscribe to any list and so be informed of updates and consulted on major changes.

The content of lists and their mappings can be also be obtained in JSON format via the LG Inform Plus API, specifically these web methods:

Taxonomies to describe service coverage

“Service areas” define the geographical polygons for coverage of services. They are particularly useful for denoting where a service is limited to residents of a particular area (eg a local authority boundary) irrespective as to how close the service is to a potential user.

UK geographies can be referenced by URIs from UK geographies can be referenced in ONS statistical geographies. Geographies anywhere in the world that are not represented by ONS geographies can be referenced in Natural Neighbourhoods where you can add your own areas if necessary. Each area has a polygon, represented in GeoJSON, which should be recorded the the service_area.extent field.

Searches on coverage take a postcode as a parameter and return services where the centroid of the given postcode falls within the service area (or where no service area is defined).

Eg, /services?coverage=BS3 4AQ

Querying APIs by taxonomy terms

The standard API’s web method for getting services provides a syntax for retrieving services that correspond with a given taxonomy term.

The syntax is: