Skip to main content
Open Referral UK

Developer documentation and tools

Open Referral UK Data Standard Guidance

Version 1.0 This will be the version when it is finalised in March 2020.


This document provides guidance on using the Open Referral UK data standard for locally delivered services.

It is the successor to the Local Government Association’s (LGA’s) comma separated values (CSV) schema developed by iStandUK and published published on LG Plus in February 2017. It constitutes the official schema developed in partnership by the LGA, iStandUK and partners involved in the Local Digital OpenCommunity programme.

The Standard conforms to and extends the international Open Referral standard.


Open Referral UK defines the structure of data expected in interfaces between standards compliant software. It also gives ranges of expected values for some fields.

The standard determines the structure of responses to application programming interface (API) web methods that return service and related data. The API is defined here.

Design Principle for Open Referral UK

The standard provides for recording sufficient data to be able to identify a small target set of services that closely meet the needs of a prospective service user, as given by the user’s location and circumstances.

Open Referral UK and Open Referral

The OpenReferral schema defines a structure for human services data - that is, a directory of services that meet human needs. Open Referral UK extends Open Referral to support richer data where needed. It then constrains the resultant schema by means of an application profile which says what fields are recommended for English use and what external vocabularies to reference.

Schema Extension And Constraint

The application profile reflects user needs identified by LGA work with pilot councils and proposed changes recommended by OpenCommunity discovery work. The document Community Services Data as an Application Profile of Open Referral assigns MoSCoW (Must, Should, Could, Won’t) prioritisations to the proposed changes.

The standard defined here reflects LGA findings combined with some “Must have” changes recommended by OpenCommunity. Further recommendations will be incorportaed in later releases in line with feedback from people implementing the standard. Issues and proposed changes are logged in the Github Issues list.

This Entity Relation Diagram shows the structure of data, distinguishing parts of the core Open Referral standard used from extensions introduced for Open Referral UK.

LGA Application Profile Basic Entity Relationship Diagram
Open a high-resolution version of the raw image in a new tab

Data structure

The Open Referral UK standard is defined here in JSON format compliant with the Open Knowledge Foundation’s tabular data package format.

It comprises:

  • Tables, which may also be seen as classes in a data structure
  • Table fields, which may be seen as class properties

Service directories supporting the standard may keep their data in the structure given or may just transform it to that structure for API requests. The tabular data package format can also be used for bulk import/export between directories.

Each table and field is described below.