/data and /data/:series route should return dh:hasRelease summary for releases #369
Description
We should adjust the granularity of requests a little, so you can follow your nose when walking data in the API.
Currently if you hit /data or /data/:series-slug you know nothing of the releases within it:
curl -X 'GET' \
'https://dluhc-pmd5-prototype.publishmydata.com/data' \
-H 'accept: application/ld+json'
{
"contents": [
{
"dcterms:title": "Permanent dwellings completed, England, District By Tenure",
"@type": "dh:DatasetSeries",
"dcterms:modified": "2024-02-01T14:48:16.422002278Z",
"dcterms:issued": "2024-02-01T14:48:16.422002278Z",
"dcterms:description": "House building data are collected at local authority district level, but it is important to treat figures at this level with care. House building is unevenly distributed both geographically and over time and patterns of housing development can produce clusters of new homes which make the figures at a low geographic level volatile and difficult to interpret. For detailed definitions of all tenures, see definitions of housing terms on Housing Statistics The district level and county figures are as reported by local authorities and the NHBC. Where a local authority has not submitted a quarterly return to DCLG, no figure has been presented for this local authority (and when relevant its county) for any 12-month period that includes the missing quarter. England total figures include estimates for missing data returns from independent Approved Inspectors and Local Authorities, so the sum of district values may be slightly less than the England totals. *House building completion* – In principle, a dwelling is regarded as complete when it becomes ready for occupation or when a completion certificate is issued whether it is in fact occupied or not. In practice, the reporting of some completions may be delayed and some completions may be missed if no completion certificate was requested by the developer or owner, although this is unusual. *Tenure* – For the purposes of these statistics, the term tenure refers to the nature of the organisation responsible for the development of a new housing start or completion. It does not necessarily describe the terms of occupancy for the dwelling on completion.",
"dh:baseEntity": "https://ldapi-prototype.gss-data.org.uk/data/Permanent-dwellings-completed",
"@id": "Permanent-dwellings-completed"
}
...]}It would be helpful if these documents contained the property dh:hasRelease with a subset of properties relevant to each nested release entity (it should be a minimum of dcterms:title and @id):
"dh:hasRelease: [{"@id":"2019", "dcterms:title": "2019"},,,,]
However the above isn't quite sufficient because the URI's for those @id's will come out wrong. Instead we need to do something like the following to fix #349:
{
"@context": {
"@base": "https://services-base-url-goes-here.org/data/" ;; 1
},
"contents": [
{
// ...
"@id": "English-Indices-of-Deprivation",
"dh:hasRelease": {
"@context":{"@base": "./English-Indices-of-Deprivation/release/"}, ;; 2
"@set": [{"@id":"2019", "dcterms:title": "2019"}]}
}
]
}The @context's at 1 and 2 ensure within their respective scopes that the @id of each dataset in contents follows the form https://services-base-url-goes-here.org/data/:id, whilst each release when expanded will have the URI https://services-base-url-goes-here.org/data/:series-id/release/:release-id.
This also balances the requirement that @id's are relative to your position in the graph/tree, so you can feed them into the API without having to parse them.
Unfortunately it does trade off having a deeper path to access the release data contents -> dh:hasRelease -> @set with the less descriptive @set key.
(From a UX perspective a nicer alternative would be to dynamically generate a portion of the @context itself. This would mean having a dynamically generated context per entity (series/release/revision) which would include the @id slugs in the paths; the static portion of the context could be held in a separate static context document, and we could import/cascade the contexts appropriately. This would allow the more succinct syntax whilst ensuring the IRI expansion was the same.)