This PR addresses issue #348 and forces the dh:hasRevision and dh:hasChange keys to always be arrays in the API responses, even when they only contain a single item.
Fixes #348 and fixes #359.
Approach
The issue could have been fixed by simply adding these lines to the simple-collection-context function:
However, @RickMoynihan suggested that the JSON-LD context should be stored in a separate file and ideally hosted externally.
The file jsonld_context.json has been updated to include the context required to fix dh:hasRevision and dh:hasChange, as well as the other predicates originally included in simple-context (e.g. appropriate-csvw)
The function json-ld/context has been added to provide a link to the context file and add in the dynamically generated @base. The syntax used in the @context is described in the JSON-LD context documentation, where it discusses combining external and local contexts. json-ld/context replaces the simple-context and simple-collection-context functions.
All handler functions that used simple-context or simple-collection-context have been updated to use json-ld/context
Some tests explicitly checked properties of the context, but now that the context is loaded externally it isn't returned in the response so it doesn't make sense to check any properties other than maybe @base.
Notes / Questions
Context file hosting
As described in the new context function, the context file cannot be pulled from Github, because raw.githubusercontent.com serves all files as text/plain, and the com.apicatalog.jsonld library requires that the file has the correct header. jsdelivr has been used instead.
Currently the context file URL points to a specific commit, however this should be updated to track the dluhc-integratiob branch, once the file has been merged into that branch.
One potential downside of using jsdelivr is that we might not have much control over the cache policy. There is some information in the documentation but I haven't looked through it in detail yet.
Presumably in the future the context file would be hosted by us?
Context returned from create/update endpoints
Currently the API endpoints that do creating/updating return their own context with a subset of the default predicates. Should these endpoints be updated to return the same context from json-ld/context that is used in the GET endpoints?
External context & hasRevision/hasChange arrays
This PR addresses issue #348 and forces the
dh:hasRevisionanddh:hasChangekeys to always be arrays in the API responses, even when they only contain a single item. Fixes #348 and fixes #359.Approach
The issue could have been fixed by simply adding these lines to the simple-collection-context function:
However, @RickMoynihan suggested that the JSON-LD context should be stored in a separate file and ideally hosted externally.
The file jsonld_context.json has been updated to include the context required to fix
dh:hasRevisionanddh:hasChange, as well as the other predicates originally included insimple-context(e.g.appropriate-csvw)The function
json-ld/contexthas been added to provide a link to the context file and add in the dynamically generated@base. The syntax used in the@contextis described in the JSON-LD context documentation, where it discusses combining external and local contexts.json-ld/contextreplaces thesimple-contextandsimple-collection-contextfunctions.All handler functions that used
simple-contextorsimple-collection-contexthave been updated to usejson-ld/contextSome tests explicitly checked properties of the context, but now that the context is loaded externally it isn't returned in the response so it doesn't make sense to check any properties other than maybe
@base.Notes / Questions
Context file hosting
As described in the new context function, the context file cannot be pulled from Github, because
raw.githubusercontent.comserves all files astext/plain, and thecom.apicatalog.jsonldlibrary requires that the file has the correct header. jsdelivr has been used instead.Currently the context file URL points to a specific commit, however this should be updated to track the
dluhc-integratiobbranch, once the file has been merged into that branch.One potential downside of using jsdelivr is that we might not have much control over the cache policy. There is some information in the documentation but I haven't looked through it in detail yet.
Presumably in the future the context file would be hosted by us?
Context returned from create/update endpoints
Currently the API endpoints that do creating/updating return their own context with a subset of the default predicates. Should these endpoints be updated to return the same context from
json-ld/contextthat is used in theGETendpoints?