Use of Taxonomies with Open Referral UK services data

• Purpose
• What is a taxonomy?
• Candidate taxonomies for services data
• Tagging service directory records
• Targeting services at specific user groups
• Referencing Local Government Association taxonomies and mappings
• Taxonomies to describe service coverage
• Querying APIs by taxonomy terms

Purpose

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 LGA’s Services List - a list of types of service relevant to English local government. It includes, as a subset, the Local Government Services List which is a detailed list of service types that English local authorities are required or empowered to deliver according to UK legislation. The list is mapped against the needs and circumstances of people whom these services might be particularly suitable.

• OpenActive Activity List - a list of types of sports and wellbeing activity

• Snomed Clinical Terminologies (see also NHS Digital Snomed CT Browser) - a list of clinical terms which can be associated with clinical services

• OpenEligibility list - described as a “way to categorize human services and human situations”, the human services part of this list provides broad categorisations of service types

Eligibility

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:

• The LGA’s Eligibility Circumstances List - a subset of all circumstances defined by the LGA. Many of the circumstances correspond with those used by the UK Office for National Statistics and other public organisations for classifying statistics. Hence service provision can be correlated with statistics pertaining to specific communities

• OpenEligibility list - described as a “way to categorize human services and human situations”, the human situations part of this list provides broad categorisations of types of individual

Accessibility for disabilities

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

This vocabulary may be considered describing service types:

• OpenActive accessibility support taxonomy

We are currently trying to identify a fuller vocabulary.

Circumstances

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:

• They can be recorded against services to indicate intended audience for services

• They can be mapped against service types so services of types relevant to a user’s circumstances can be found

These vocabularies are suitable for describing circumstance types:

• The LGA’s Personal Circumstances List - a subset of all circumstances defined by the LGA. Many of the circumstances correspond with those used by the UK Office for National Statistics and other public organisations for classifying statistics. Hence service provision can be correlated with statistics pertaining to specific communities.

• OpenEligibility list - described as a “way to categorize human services and human situations”, the human situations part of this list provides broad categorisations of types of individual

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.

Needs

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:

• The LGA’s Needs List - this is mapped against the LGA’s Service Types List to show which types of service might be suitable for someone with specific 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.

Examples:

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

• CURIE:  bccservicetype

• Sample taxonomy term identifier: bccservicetype:78 (for Autism)

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

• CURIE: esdServiceType

• Sample taxonomy term identifier: esdServiceType:242 (for “Care at home”)

Open Referral UK 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:

• esdCircumstance: - the LGA’s Circumstances List from “electronic service deliver” work. This is used for individual circumstances. We’d normally only expect this to be used for service eligibility. The CURIE esdCircumstance can be expanded to the URI stub http://id.esd.org.uk/circumstance/

• esdCircumstanceCollection: - the LGA’s Circumstances List from “electronic service deliver” work. This is used for collections of circumstances like a set of age ranges or chronic illnesses, so shoukld only be used if you’re describing the whole collection. The CURIE esdCircumstanceCollection can be expanded to the URI stub http://id.esd.org.uk/circumstanceCollection/

• esdNeed: the LGA’s Needs List from “electronic service deliver” work. We would not normally expect this to be used to tag individual records. The CURIE esdNeed can be expanded to the URI stub http://id.esd.org.uk/need/

• esdServiceType: - the LGA Services List from “electronic service deliver” work. The CURIE esdServiceType can be expanded to the URI stub http://id.esd.org.uk/service/

• openEligibility: - OpenEligibility list  of “human services” and “human situations”

• openActiveActivity: - OpenActive Activity List 

• snomedCT: - Snomed Clinical Terminologies (see also NHS Digital Snomed CT Browser)

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:

• Text, which may be drawn from a service’s name and description with whatever relevance prioritisation a search engine deploys

• Minimum and maximum ages of service users

• The geographical scope for which service users are eligible, eg residents of a given borough

• Taxonomy terms associated with each service

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.

It includes filter parameters for:

• text - used for a general text search of service name and other fields implemented by the service directory search engine

• minimum_age

• maximum_age

• coverage - for checking the any service area eligibility criteria

• postcode and proximity - for limiting service found to those within a given proximity of the centroid of a specific postcode

• taxonomy_type, vocabulary and taxonomy_id

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:

/services/?taxonomy_id=esdServiceType:242&taxonomy_type=service&vocabulary=esdServiceTypes

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.

Hence:

/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

Personas

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

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

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:

• Service types - http://id.esd.org.uk/list/services with mappings from personal circumstances and needs

• Needs - http://id.esd.org.uk/list/needs with mappings to service types

• Personal circumstances - http://id.esd.org.uk/list/circumstancesPersonal  with mappings to service types

• Eligibility circumstances - http://id.esd.org.uk/list/circumstancesEligibility

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:

• /lists - giving the properties of all LGA taxonomies (lists) and their subsets

• /lists/{listId} - giving the full properties of a single taxonomy (list) and all its items

• /lists/{listId}/verbose - giving the full properties of a single taxonomy (list) and all its items and their mappings to all other lists

• /lists/{listId}/{identifier} - full properties of a single taxonomy (list) item

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:

/services/?&taxonomy_id=TaxonomyTerm&taxonomy_type=TaxonomyType&vocabulary=VocabularyIdentifier

Where:

• TaxonomyTerm is term identifier prefixed by its CURIE, eg esdServiceType:242

• TaxonomyType is one of Area, Cost, Eligibility, Organization, Service or “Any” representing any of these

• VocabularyIdentifier is the vocabulary from which the term comes