Handling codelists

Frequently one or more Aspects of a dataset will take values from a controlled list of terms. The controlled list might be flat or hierarchical. This is supported by the Data Services API as follows.

Linking an Aspect to a codelist Dataset

An Aspect declaration can declare a dataset which contains the set of legal values for that Aspect. This may be any dataset or one which represents a concept scheme or other hierarchy.

This has two impacts.

Firstly, the name of the constraining dataset is included in the Aspect structure report. This allows a UI to consult the range dataset to obtain legal values to select from.

Secondly, if the range dataset is hierarchical then the data query can constrain the values for this Aspect by use of the @below filter.

Hierarchical datasets

A hierarchical dataset represents the contents of a code list - the code list must be one of a skos:ConceptScheme, skos:Collection or qb:HierarchicalCodeList. A skos:Collection is a somewhat degenerate hierarchy in that it only has one level.

This is represented in the structure description JSON by the presence of a hierarchy key in the dataset description whose value is an object describing the code list. The description will include the URI and the type of the code list.

A hierarchical dataset also supports the @childof filter which makes it possible to traverse the hierarchy from top to bottom ("@childof":null lists the roots of the hierarchy).

A hierarchical dataset is declared by supplying a dsapi:codeList in the data set declaration whose value is the code list resource (ConceptScheme, Collection or HierarchicalCodeList).

It is also possible to implicitly declare a hierarchical dataset by attaching the dsapi:codeList value directly to the Aspect. This both creates an implicit hierarchical dataset for the code list and sets the rangeDataset for the Aspect to point to that implicit dataset. If a data set is defined by a Data Cube DSD then the same effect is achieved by declaring a qb:codeList value on a component property.

Note that qb:HierarchicalCodeList allows any hierarchy to be used, not purely SKOS ones. Use it to define a set of roots and a parent-child (or child-parent) relationship.

There is not yet any support for subsetting a concept-scheme into a set of collections (whether scheme levels or arbitrary collections).

Example

As an example here's a declaration of a hierarchical corresponding to the EA regions and areas data on http://environment.data.gov.uk/registry/def/ea-organization/ea_areas. It declares minimal Aspects to describe each entry and an explicit in-line code list definition using qb:HierarchicalCodeList.

:areas a dsapi:Dataset;
    rdfs:label "Areas";
    dct:description "EA areas and regions";
    dsapi:codeList :ea-areas-hcl;
    dsapi:aspect 
        [ dsapi:property skos:notation; dsapi:optional true ],
        [ dsapi:property skos:prefLabel; ];
    .
    
:ea-areas-hcl a qb:HierarchicalCodeList;
    qb:hierarchyRoot 
        <http://environment.data.gov.uk/registry/def/ea-organization/ea_areas/1>,
        <http://environment.data.gov.uk/registry/def/ea-organization/ea_areas/2>,
        <http://environment.data.gov.uk/registry/def/ea-organization/ea_areas/3>,
        <http://environment.data.gov.uk/registry/def/ea-organization/ea_areas/4>,
        <http://environment.data.gov.uk/registry/def/ea-organization/ea_areas/10>,
        <http://environment.data.gov.uk/registry/def/ea-organization/ea_areas/6>;
    qb:parentChildProperty org:hasSubOrganization ;        
    .