Field and Object Guidance

Note

This page is non-normative, which means that it doesn’t form part of the standard; if there is any ambiguity, the standard takes precedence. This page may be updated at any time in response to community demand.

This page contains guidance on various topics specific to the properties and structures within HSDS.

Names and Descriptions

Locations, Services and Organizations each have name, alternate_name, and description properties that can contain free text.

name and alternate_name should only ever include plain text, without formatting.

description may include HTML elements or Markdown, with special characters escaped or encoded.

Consuming applications should be aware of this and behave appropriately in accordance with their aims. This may involve stripping HTML tags, rendering (or not rendering) Markdown, or simply storing the contents as-is.

Publishers should be aware that consuming applications may wish to extract a ‘short description’ from the description field, and may do so by looking for the first full sentence or first line-break.

Schedules

schedules contain information about when a service is available. They can be linked to service, location, and service_at_location.

Each schedule entry contains the following information:

Its identifier
Any affiliated service, location, or service_at_location objects (JSON) or their ids (Tabular Data Packages)
The opening times that are referred to
Validity of the data expressed as a time period
iCal RRULE-style fields that describe how often the opening times repeat.

Opening Times

opens_at and closes_at fields are straightforward ISO 8601 times; for example “10:00Z”. They should include timezone information.

The description field should be a human-readable description of the opening hours, but shouldn’t add any more information, such as exceptions.

Validity

The valid_from and valid_to fields are ISO 8601 date-times that indicate the period for which the data should be considered valid. For example, if an organisation that collects data on local services carries out checks once a year, then setting valid_to to 1 year after valid_from would be appropriate. This helps ensure that older data can be identified.

Recurrence

The rest of the fields in the schedule are based on RRULEs from the iCal standard in order to express the way in which the opening times repeat. RRULES are very expressive, and are familiar to many people, as they’re widely used in calendar software.

HSDS doesn’t contain all of the nuance of RRULE, and the schema doesn’t check that your RRULEs are valid. This documentation provides only basic guidance on RRULE; please consult the iCal documentation for in-depth explanations.

There are several key properties for expressing RRULEs in HSDS:

A dtstart (starting date-time); when the instance in the rule starts
A freq (frequency); the unit of the recurrence; e.g. days, weeks, months
A byday, byweekno,bymonthday,byyearday; the value of the recurrence; e.g. 5

Together, these allow events to be expressed in the form “The first instance is on the 8th of August 2020, and it then happens every 2 weeks”.

There’s also an until field, which gives an end point to the recurrence. This might be appropriate to use when describing a service that’s only available for a season.

Exceptional Schedules

It’s common for a service to operate different hours over a certain period - such as a holiday.

If the service is offering additional opening hours to their regular hours, then a second entry can be added, with valid_from and valid_to set to indicate the limited range of dates that the additional hours apply for.

If the service is changing its hours, then set the valid_to value to the last day that the regular schedule is in operation, and add new entries for the service’s exceptional opening hours.

24h opening

HSDS doesn’t have a way to model this explicitly. If a service operates 24 hours a day, setting the opens_at and closes_at to 00:00 and 23:59 is a strong signal to any data users that the opening hours are known and 24h.

Worked Example

In this example we look at the schedule data of a service which is available from 0900 to 1200 and 1500 to 1700, Monday to Thursday, every week. They know that they’ll change to a Christmas schedule in mid-December, so the schedule will be valid until then.

During the year, they decide to open on the first Saturday of each month from July until November. So, they add another schedule.

JSON

{
    "services": [
        {
            "id": "ac148810-d857-441c-9679-408f346de14b",
            "name": "Community Counselling",
            "description": "Counselling Services provided by trained professionals. Suitable for people with mental health conditions such as anxiety, depression, or eating disorders as well as people experiencing difficult life events and circumstances. ",
            "status": "active",
            "schedules": [
                {
                    "id": "ceee812e-6ed2-4fe1-87d1-2c88c2d6b8b3",
                    "description": "Monday to Thursday, 9am to 12pm",
                    "dtstart": "2020-04-01",
                    "valid_from": "2020-04-01",
                    "valid_to": "2020-12-20",
                    "freq": "WEEKLY",
                    "byday": "MO,TU,WE,TH",
                    "opens_at": "09:00:00Z",
                    "closes_at": "12:00:00Z"
                },
                {
                    "id": "887404d7-6479-48da-bb86-b1592da85aef",
                    "description": "Monday to Thursday, 3pm to 5pm",
                    "dtstart": "2020-04-01",
                    "valid_from": "2020-04-01",
                    "valid_to": "2020-12-20",
                    "freq": "WEEKLY",
                    "byday": "MO,TU,WE,TH",
                    "opens_at": "15:00:00Z",
                    "closes_at": "17:00:00Z"
                },
                {
                    "id": "23f3f9c6-431d-4e85-b59b-309d6d70274e",
                    "description": "First Saturday of the month from July-Nov, 9am-5pm",
                    "dtstart": "2020-07-04",
                    "until": "2020-11-07",
                    "freq": "MONTHLY",
                    "byday": "1SA",
                    "opens_at": "09:00:00Z",
                    "closes_at": "17:00:00Z"
                }
            ]
        }
    ]
}

Tabular Data Package

services.csv

id	name	description	status
ac148810-d857-441c-9679-408f346de14b	Community Counselling	Counselling Services provided by trained professionals. Suitable for people with mental health conditions such as anxiety, depression, or eating disorders as well as people experiencing difficult life events and circumstances.	active

schedules.csv

id	service_id	description	dtstart	until	valid_from	valid_to	freq	byday	opens_at	closes_at
ceee812e-6ed2-4fe1-87d1-2c88c2d6b8b3	ac148810-d857-441c-9679-408f346de14b	Monday to Thursday, 9am to 12pm	2020-04-01	null	2020-04-01	2020-12-20	WEEKLY	MO,TU,WE,TH	09:00:00Z	12:00:00Z
887404d7-6479-48da-bb86-b1592da85aef	ac148810-d857-441c-9679-408f346de14b	Monday to Thursday, 3pm to 5pm	2020-04-01	null	2020-04-01	2020-12-20	WEEKLY	MO,TU,WE,TH	15:00:00Z	17:00:00Z
23f3f9c6-431d-4e85-b59b-309d6d70274e	ac148810-d857-441c-9679-408f346de14b	First Saturday of the month from July-Nov, 9am-5pm	2020-07-04	2020-11-07	null	null	MONTHLY	1SA	09:00:00Z	17:00:00Z

In the first two schedule objects the non-iCal fields valid_from and valid_to have been provided to signify that this is the period that these opening hours are valid for. Consuming systems may infer from this that as the valid_to date approaches, they should seek to find out what future opening hours are for the service; they shouldn’t necessarily infer that a service has ended – just that they don’t have any more opening time information. This is in contrast to defining the service’s opening hours by use of the until iCal field, which explicitly defines the end of a recurring event, and therefore a consuming system may infer that the service is no longer available after that time.

The final schedule object in the array omits the valid_from and valid_tobecause the RRULE is limited by its nature and it specifies when the series of events starts and ends.

Classifications, Attributes, and Taxonomies

HSDS is focused on providing information about services; it is not designed to be a taxonomy interchange format. Therefore, the features provided by HSDS are intended to be sufficient for users to transfer enough information about a taxonomy to make the data about services be useful. They are not intended to replace or stand in for existing taxonomy and classification system datasets, which should be defined externally.

HSDS provides a way to flexibly attach attributes including classifications and taxonomies to various types of object.

Terminology

Classification and description is an area in which terms are used inconsistently across domains and applications. Therefore, we define here certain terms which are used in the standard.

These definitions may be different from those that you’d use in your context, in which case we’d suggest prepending the term “OpenReferral” or “HSDS” to disambiguate. For example, if you’d call an “attribute” a “property”, then you might refer to an “HSDS Attribute”.

Vocabulary

A vocabulary is the set of words that are used in a language, which may have multiple meanings.

For example, the English language has around 170,000 terms in its vocabulary. The word “crane” can refer to a piece of machinery, a type of bird, or the action of overextending one’s neck in an attempt to see something that is otherwise obscured.

Alternatively a vocabulary of codes might be created for a particular purpose - such as “ES1098” and “87HG42”

Taxonomy

A taxonomy is a structure of terms drawn from a vocabulary which can be used to describe attributes of something.

For example, a taxonomy designed for use in the construction industry, called “construction machinery” might say that a particular piece of machinery is a “crane”, or an “86HG4”

In such a case, to say that a particular machine is a “construction machinery”->”crane” is meaningful.

Embedded Taxonomy

An embedded taxonomy is a taxonomy where the dataset contains the definition of the taxonomy terms used in the data; ie, to find out what a term means, you look within the dataset. It can be a clone of an external taxonomy, if licensing allows.

Data packages using HSDS shouldn’t contain any unused taxonomy terms, in particular if providing those terms would result in a package that comprises more taxonomy data than service data.

External Taxonomy

An external taxonomy is where the taxonomy is held outside of the data and the dataset ships with just references to the taxonomy; ie, to find out authoritatively what a term means, you look elsewhere.

Taxonomy Term

A taxonomy term is a particular instance of a term from a vocabulary which is given a particular meaning by a taxonomy.

For example, a taxonomy term might be “86HG4”, which the taxonomy describes as lifting equipment. It might be a child of “ES1098”, which is heavy machinery.

Attribute

An attribute is some property, fact, or assertion that is made of a thing.

For example, a particular piece of machinery might have some attributes:

Painted yellow
Has a government-issued plate declaring it to be ID “JG36QAK” and allowed to be driven on public roads
Is of type “crane”, from the taxonomy “construction machinery”

Attributes in HSDS are asserted by applying a taxonomy term to an object.

Applying data to objects

HSDS provides several objects which store this data:

attribute – see Attribute, a object representing a link between a service and one or more classifications that describe the nature of the service provided.
taxonomy_term – see Taxonomy Term, an object representing a single term within the taxonomy.
taxonomy – see Taxonomy, an object representing an entire taxonomy from which individual taxonomy_terms are taken.

An attribute is a catch-all holder which can be used to apply either a taxonomy_term to an object, or an arbitrary value via the value property if the attribute is not derived from a taxonomy. Most objects in HSDS have an attributes property, which is an array containing attribute objects. To attach an attribute to another object (e.g. a service) then simply include it in this array.

A taxonomy_term specifically models a term drawn from a taxonomy. It has a code property which represents the term identifier as used in the taxonomy, as well as a name (required) for the term itself and a description (required) which should be used to provide a human-readable description of the term. Some taxonomies are hierarchical, so there’s also an option to include a parent_id for another taxonomy_term. In the official JSON serialization, the entire taxonomy object from which the term is drawn can be included in the taxonomy_detail object whereas taxonomy_id refers to the id property of the taxonomy object elsewhere in the HSDS dataset (useful for Tabular Datapackages). The taxonomy_term object is designed to be included via an attribute object underneath an object’s attributes array.

A taxonomy object is a simple object describing a taxonomy. It must have a name which describes the taxonomy, as well as a description which provides a human-readable description of the taxonomy. There are also spaces for a uri which is desirable. In an ideal world, the value of taxonomy/uri would resolve to a URI which provides either a canonical reference to the taxonomy or a canonical machine-readable serialization of the taxonomy.

Worked Example

The following examples demonstrates how attributes and taxonomies look in practice.

The example will define two services:

A “Kitten Time” service which is a workplace service designed to reduce stress
A “Puppy Time” service which is also a workplace service, designed to reduce stress

It will then define some taxonomy terms:

“stress”, which is drawn from a fictional Health Service Taxonomy taxonomy
“WORKPLACE”, which is drawn from a separate fictional taxonomy called Service Location Descriptor Taxonomy

JSON

{
    "services": [
        {
            "id": "72422080-aa96-418c-9ef3-f77d3e60aed7",
            "name": "Kitten Time",
            "description": "Time with Kittens!",
            "status": "active",
            "attributes": [
                {
                    "id": "cb59e062-6e3f-451a-ab4f-5cc96bfdc172",
                    "taxonomy_term": {
                        "id": "8ba8f6d2-06d5-4a03-91c6-b87d99e3bbb9",
                        "name": "stress",
                        "description": "A Health Service for supporting people deal with stress, or aimed at reducing stress",
                        "taxonomy": "Fictional Health Service Taxonomy",
                        "taxonomy_details": {
                            "id": "34027579-8e06-4440-94d3-ea9fccf10d3f",
                            "name": "Fictional Health Service Taxonomy",
                            "description": "An example taxonomy for describing different types of health services",
                            "uri": "https://fictional-health-service.example/taxonomies/health-service"
                        }
                    }
                },
                {
                    "id": "502b3383-de46-4b07-b110-76963acc4798",
                    "taxonomy_term": {
                        "id": "7856923f-2d44-4513-a239-29723b5350e5",
                        "name": "WORKPLACE",
                        "description": "A service which operates an outreach entering people's workplaces",
                        "taxonomy": "Fictional Service Location Descriptor Taxonomy",
                        "taxonomy_details": {
                            "id": "cba285aa-5ebc-43c8-909f-02c2ce128143",
                            "name": "Fictional Service Location Descriptor Taxonomy",
                            "description": "An example taxonomy for desribing different types of service location",
                            "uri": "https://fictional-service-location-descriptor-taxonomy.example/taxonomy.json"
                        }
                    }
                }
            ]
        },
        {
            "id": "ae761ee1-73ba-44aa-b3d8-db7aa2d7394b",
            "name": "Puppy Time",
            "description": "Time with Puppies!",
            "status": "active",
            "attributes": [
                {
                    "id": "3748b88b-2bcd-4294-8fcb-3e18e7158528",
                    "taxonomy_term": {
                        "id": "8ba8f6d2-06d5-4a03-91c6-b87d99e3bbb9",
                        "name": "stress",
                        "description": "A Health Service for supporting people deal with stress, or aimed at reducing stress",
                        "taxonomy": "Fictional Health Service Taxonomy",
                        "taxonomy_details": {
                            "id": "34027579-8e06-4440-94d3-ea9fccf10d3f",
                            "name": "Fictional Health Service Taxonomy",
                            "description": "An example taxonomy for describing different types of health services",
                            "uri": "https://fictional-health-service.example/taxonomies/health-service"
                        }
                    }
                },
                {
                    "id": "101db525-2159-4f70-ba77-c4cf0aaa59bf",
                    "taxonomy_term": {
                        "id": "7856923f-2d44-4513-a239-29723b5350e5",
                        "name": "WORKPLACE",
                        "description": "A service which operates an outreach entering people's workplaces",
                        "taxonomy": "Fictional Service Location Descriptor Taxonomy",
                        "taxonomy_details": {
                            "id": "cba285aa-5ebc-43c8-909f-02c2ce128143",
                            "name": "Fictional Service Location Descriptor Taxonomy",
                            "description": "An example taxonomy for desribing different types of service location",
                            "uri": "https://fictional-service-location-descriptor-taxonomy.example/taxonomy.json"
                        }
                    }
                }
            ]
        }
    ]
}

Tabular Data Package

services.csv

id	name	description	status
72422080-aa96-418c-9ef3-f77d3e60aed7	Kitten Time	Time with Kittens!	active
ae761ee1-73ba-44aa-b3d8-db7aa2d7394b	Puppy Time	Time with Puppies!	active

taxonomies.csv

id	name	description	uri
34027579-8e06-4440-94d3-ea9fccf10d3f	Fictional Health Service Taxonomy	An example taxonomy for describing different types of health services	https://fictional-health-service.example/taxonomies/health-service
cba285aa-5ebc-43c8-909f-02c2ce128143	Fictional Service Location Descriptor Taxonomy	An example taxonomy for desribing different types of service location	https://fictional-service-location-descriptor-taxonomy.example/taxonomy.json

taxonomy_terms.csv

id	name	description	taxonomy	taxonomy_id
8ba8f6d2-06d5-4a03-91c6-b87d99e3bbb9	stress	A Health Service for supporting people deal with stress, or aimed at reducing stress	Fictional Health Service Taxonomy	34027579-8e06-4440-94d3-ea9fccf10d3f
7856923f-2d44-4513-a239-29723b5350e5	WORKPLACE	A service which operates an outreach entering people’s workplaces	Fictional Service Location Descriptor Taxonomy	cba285aa-5ebc-43c8-909f-02c2ce128143

attributes.csv

id	link_id	link_entity	taxonomy_term_id
cb59e062-6e3f-451a-ab4f-5cc96bfdc172	72422080-aa96-418c-9ef3-f77d3e60aed7	service	8ba8f6d2-06d5-4a03-91c6-b87d99e3bbb9
502b3383-de46-4b07-b110-76963acc4798	72422080-aa96-418c-9ef3-f77d3e60aed7	service	7856923f-2d44-4513-a239-29723b5350e5
3748b88b-2bcd-4294-8fcb-3e18e7158528	ae761ee1-73ba-44aa-b3d8-db7aa2d7394b	service	8ba8f6d2-06d5-4a03-91c6-b87d99e3bbb9
101db525-2159-4f70-ba77-c4cf0aaa59bf	ae761ee1-73ba-44aa-b3d8-db7aa2d7394b	service	7856923f-2d44-4513-a239-29723b5350e5

Please note that the above example omits a number of fields for the sake of brevity, some of which may be required by the HSDS Schemas.

Metadata

HSDS also provides a general-purpose Metadata object which allows publishers to include a record of changes associated with individual records. Aside from the Metadata object itself, every object defined by HSDS has a metadata property which can hold an array of metadata objects.

It’s intended that each Metadata object represents a single change, so therefore multiple metadata objects may be added at once when different things have changed in a record. For this reason as well, most of the fields within each metadata object are required.

Worked Example

In this example, a service is provided and then various elements of it are updated in the record over time.

Note that many fields have been omitted for brevity, some of which may be required by the HSDS Schemas.

JSON

{
    "services": [
        {
            "id": "ddfec080-be89-404d-a44b-4f1e98dbeed2",
            "name": "Kitten Time",
            "description": "Therapeutic visits by Kitten Time Teams can bring comfort and companionship to people living in local communities who may feel isolated and lonely, help young people to improve their literacy and concentration in the classroom and can aid a patient's recovery, rehabilitation and help improve mental health and wellbeing in the workplace.",
            "status": "active",
            "metadata": [
                {
                    "id": "1704bcb7-d4a8-424f-9d5b-96211f20e590",
                    "last_action_date": "2022-01-01",
                    "last_action_type": "update",
                    "field_name": "description",
                    "previous_value": "Kitten Time is a fun way to combat stress at work! Take some time out in your day to come by and play with our fun-loving cute-as-a-button kittens and feel your stress melt away.",
                    "replacement_value": "Therapeutic visits by Kitten Time Teams can bring comfort and companionship to people living in local communities who may feel isolated and lonely, help young people to improve their literacy and concentration in the classroom and can aid a patient's recovery, rehabilitation and help improve mental health and wellbeing in the workplace.",
                    "updated_by": "A. D. Ministrator"
                },
                {
                    "id": "d84f8a6c-a93c-4653-96a6-e588f51d250d",
                    "last_action_date": "2021-06-01",
                    "last_action_type": "update",
                    "field_name": "name",
                    "previous_value": "Pet Therapy: Kitten Edition",
                    "replacement_value": "Kitten Time",
                    "updated_by": "A. User"
                },
                {
                    "id": "4e8da98f-33b9-48aa-9109-1677a327df9d",
                    "last_action_date": "2021-01-01",
                    "last_action_type": "update",
                    "field_name": "status",
                    "previous_value": "temporarily closed",
                    "replacement_value": "active",
                    "updated_by": "A. D. Ministrator"
                }
            ]
        }
    ]
}

Tabular Data Package

services.csv

id	name	description	status
ddfec080-be89-404d-a44b-4f1e98dbeed2	Kitten Time	Therapeutic visits by Kitten Time Teams can bring comfort and companionship to people living in local communities who may feel isolated and lonely, help young people to improve their literacy and concentration in the classroom and can aid a patient’s recovery, rehabilitation and help improve mental health and wellbeing in the workplace.	active

metadata.csv

id	resource_id	resource_type	last_action_date	last_action_type	field_name	previous_value	replacement_value	updated_by
1704bcb7-d4a8-424f-9d5b-96211f20e590	ddfec080-be89-404d-a44b-4f1e98dbeed2	service	2022-01-01	update	description	Kitten Time is a fun way to combat stress at work! Take some time out in your day to come by and play with our fun-loving cute-as-a-button kittens and feel your stress melt away.	Therapeutic visits by Kitten Time Teams can bring comfort and companionship to people living in local communities who may feel isolated and lonely, help young people to improve their literacy and concentration in the classroom and can aid a patient’s recovery, rehabilitation and help improve mental health and wellbeing in the workplace.	Ministrator
d84f8a6c-a93c-4653-96a6-e588f51d250d	ddfec080-be89-404d-a44b-4f1e98dbeed2	service	2021-06-01	update	name	Pet Therapy: Kitten Edition	Kitten Time	User
4e8da98f-33b9-48aa-9109-1677a327df9d	ddfec080-be89-404d-a44b-4f1e98dbeed2	service	2021-01-01	update	status	temporarily closed	active	Ministrator