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
, orservice_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 startsA
freq
(frequency); the unit of the recurrence; e.g. days, weeks, monthsA
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.
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 |
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_to
because 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 aservice
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 individualtaxonomy_term
s 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
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 |
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 |
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 |
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.
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 |
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. |
|
d84f8a6c-a93c-4653-96a6-e588f51d250d |
ddfec080-be89-404d-a44b-4f1e98dbeed2 |
service |
2021-06-01 |
update |
name |
Pet Therapy: Kitten Edition |
Kitten Time |
|
4e8da98f-33b9-48aa-9109-1677a327df9d |
ddfec080-be89-404d-a44b-4f1e98dbeed2 |
service |
2021-01-01 |
update |
status |
temporarily closed |
active |
|