Support GeoJSON-LD templating (#1927)

* Support JSON-LD template for items

* Create `item_list.jsonld` template

Create `item_list.jsonld` template to backport current /items json-ld content offerings

* Reduce number of times templated geojsonld is serialized

* Add test for linked_data.py

* Use json serializer in test

* Run test in CI

* Add test for single item

* Use single quotes

* Fix flake8

* Use collection level template for GeoJSON-LD

* Un-nest JSON-LD context from resource config

* Respond to PR feedback

* Update test_linked_data.py

* Revert "Un-nest JSON-LD context from resource config"

This reverts commit 5b371b2.

* Update documentation

Author: webb-ben

.github/workflows/main.yml

@@ -128,6 +128,7 @@ jobs:
         pytest tests/test_esri_provider.py
         pytest tests/test_filesystem_provider.py
         pytest tests/test_geojson_provider.py
+        pytest tests/test_linked_data.py
         pytest tests/test_mongo_provider.py
         pytest tests/test_ogr_csv_provider.py
         pytest tests/test_ogr_esrijson_provider.py

docs/source/configuration.rst

@@ -197,7 +197,6 @@ default.
               - observations
               - monitoring
           linked-data: # linked data configuration (see Linked Data section)
-              item_template: tests/data/base.jsonld
               context:
                   - datetime: https://schema.org/DateTime
                   - vocab: https://example.com/vocab#
@@ -646,23 +645,19 @@ This relationship can further be maintained in the JSON-LD structured data using
             ssn: "http://www.w3.org/ns/ssn/"
             Datastream: sosa:isMemberOf
 
-Sometimes, the JSON-LD desired for an individual feature in a collection is more complicated than can be achieved by
-aliasing properties using a context. In this case, it is possible to specify a Jinja2 template. When ``item_template``
-is defined for a feature collection, the json-ld prepared by pygeoapi will be used to render the Jinja2 template
-specified by the path. The path specified can be absolute or relative to pygeoapi's template folder. For even more
-deployment flexibility, the path can be specified with string interpolation of environment variables.
+Sometimes, the JSON-LD desired for an individual feature in a collection is more complicated than can
+be achieved by aliasing properties using a context. In this case, it is possible to implement a custom 
+Jinja2 template. GeoJSON-LD is rendered using the Jinja2 templates defined in ``collections/items/item.jsonld``
+and ``collections/items/index.jsonld``. A pygeoapi collection requiring custom GeoJSON-LD can overwrite these
+templates using dataset level templating. To learn more about Jinja2 templates, see :ref:`html-templating`.
 
 
 .. code-block:: yaml
 
     linked-data:
-      item_template: tests/data/base.jsonld
       context:
         - datetime: https://schema.org/DateTime
 
-.. note::
-   The template ``tests/data/base.jsonld`` renders the unmodified JSON-LD. For more information on the capacities
-   of Jinja2 templates, see :ref:`html-templating`.
 
 Validating the configuration
 ----------------------------

pygeoapi/api/itemtypes.py

@@ -648,6 +648,8 @@ def get_collection_items(
             api, content, dataset, id_field=(p.uri_field or 'id')
         )
 
+        return headers, HTTPStatus.OK, content
+
     return headers, HTTPStatus.OK, to_json(content, api.pretty_print)
 
 
@@ -930,6 +932,8 @@ def get_collection_item(api: API, request: APIRequest,
             api, content, dataset, uri, (p.uri_field or 'id')
         )
 
+        return headers, HTTPStatus.OK, content
+
     return headers, HTTPStatus.OK, to_json(content, api.pretty_print)
 
 

pygeoapi/linked_data.py

@@ -31,11 +31,10 @@
 Returns content as linked data representations
 """
 
-import json
 import logging
 from typing import Callable
 
-from pygeoapi.util import is_url, render_j2_template
+from pygeoapi.util import is_url, render_j2_template, url_join
 from pygeoapi import l10n
 from shapely.geometry import shape
 from shapely.ops import unary_union
@@ -189,30 +188,22 @@ def geojson2jsonld(cls, data: dict, dataset: str,
     :returns: string of rendered JSON (GeoJSON-LD)
     """
 
-    LOGGER.debug('Fetching context and template from resource configuration')
-    jsonld = cls.config['resources'][dataset].get('linked-data', {})
-    ds_url = f"{cls.get_collections_url()}/{dataset}"
-
-    context = jsonld.get('context', []).copy()
-    template = jsonld.get('item_template', None)
+    LOGGER.debug('Fetching context from resource configuration')
+    context = cls.config['resources'][dataset].get('context', []).copy()
+    templates = cls.get_dataset_templates(dataset)
 
     defaultVocabulary = {
         'schema': 'https://schema.org/',
+        'gsp': 'http://www.opengis.net/ont/geosparql#',
         'type': '@type'
     }
 
     if identifier:
-        # Single jsonld
-        defaultVocabulary.update({
-            'gsp': 'http://www.opengis.net/ont/geosparql#'
-        })
-
         # Expand properties block
         data.update(data.pop('properties'))
 
         # Include multiple geometry encodings
         if (data.get('geometry') is not None):
-            data['type'] = 'schema:Place'
             jsonldify_geometry(data)
 
         data['@id'] = identifier
@@ -224,6 +215,7 @@ def geojson2jsonld(cls, data: dict, dataset: str,
             'FeatureCollection': 'schema:itemList'
         })
 
+        ds_url = url_join(cls.get_collections_url(), dataset)
         data['@id'] = ds_url
 
         for i, feature in enumerate(data['features']):
@@ -233,9 +225,15 @@ def geojson2jsonld(cls, data: dict, dataset: str,
             if not is_url(str(identifier_)):
                 identifier_ = f"{ds_url}/items/{feature['id']}"  # noqa
 
+            # Include multiple geometry encodings
+            if feature.get('geometry') is not None:
+                jsonldify_geometry(feature)
+
             data['features'][i] = {
                 '@id': identifier_,
-                'type': 'schema:Place'
+                'type': 'schema:Place',
+                **feature.pop('properties'),
+                **feature
             }
 
     if data.get('timeStamp', False):
@@ -248,17 +246,21 @@ def geojson2jsonld(cls, data: dict, dataset: str,
         **data
     }
 
-    if None in (template, identifier):
-        return ldjsonData
+    if identifier:
+        # Render jsonld template for single item
+        LOGGER.debug('Rendering JSON-LD item template')
+        content = render_j2_template(
+            cls.tpl_config, templates,
+            'collections/items/item.jsonld', ldjsonData)
+
     else:
-        # Render jsonld template for single item with template configured
-        LOGGER.debug(f'Rendering JSON-LD template: {template}')
+        # Render jsonld template for /items
+        LOGGER.debug('Rendering JSON-LD items template')
         content = render_j2_template(
-            cls.config, cls.config['server']['templates'],
-            template, ldjsonData)
+            cls.tpl_config, templates,
+            'collections/items/index.jsonld', ldjsonData)
 
-        ldjsonData = json.loads(content)
-        return ldjsonData
+    return content
 
 
 def jsonldify_geometry(feature: dict) -> None:
@@ -271,6 +273,8 @@ def jsonldify_geometry(feature: dict) -> None:
     :returns: None
     """
 
+    feature['type'] = 'schema:Place'
+
     geo = feature.get('geometry')
     geom = shape(geo)
 
@@ -287,7 +291,11 @@ def jsonldify_geometry(feature: dict) -> None:
     }
 
     # Schema geometry
-    feature['schema:geo'] = geom2schemageo(geom)
+    try:
+        feature['schema:geo'] = geom2schemageo(geom)
+    except AttributeError:
+        msg = f'Unable to parse schema geometry for {feature["id"]}'
+        LOGGER.warning(msg)
 
 
 def geom2schemageo(geom: shape) -> dict:

pygeoapi/schemas/config/pygeoapi-config-0.x.yml

@@ -366,9 +366,6 @@ properties:
                             type: object
                             description: linked data configuration
                             properties:
-                                item_template:
-                                    type: string
-                                    description: path to JSON-LD Jinja2 template
                                 context:
                                     type: array
                                     description: additional JSON-LD context

pygeoapi/templates/collections/items/index.jsonld

@@ -0,0 +1,23 @@
+{
+    "@context": [
+        {
+            "schema": "https://schema.org/",
+            "type": "@type",
+            "features": "schema:itemListElement",
+            "FeatureCollection": "schema:itemList"
+        }
+    ],
+    "type": "FeatureCollection",
+    "@id": "{{ data["@id"] }}",
+    {%- if data.features %}
+    "features": [
+        {%- for ft in data.features %}
+        {
+            "@type": "{{ ft.type }}",
+            "@id": "{{ ft["@id"] }}"
+        }
+        {%- if not loop.last -%},{%- endif -%}
+        {%- endfor %}
+    ]
+    {%- endif %}
+}

pygeoapi/templates/collections/items/item.jsonld

@@ -0,0 +1 @@
+{{ to_json(data, config.server.pretty_print) | safe }}

tests/api/test_itemtypes.py

@@ -548,8 +548,8 @@ def test_get_collection_items_json_ld(config, api_):
     assert '@context' in collection
     assert all((f in collection['@context'][0] for
                 f in ('schema', 'type', 'features', 'FeatureCollection')))
-    assert len(collection['@context']) > 1
-    assert collection['@context'][1]['schema'] == 'https://schema.org/'
+    assert len(collection['@context']) == 1
+    assert collection['@context'][0]['schema'] == 'https://schema.org/'
     expanded = jsonld.expand(collection)[0]
     featuresUri = 'https://schema.org/itemListElement'
     assert len(expanded[featuresUri]) == 2

tests/data/base.jsonld

@@ -293,8 +293,6 @@ resources:
               title: data source
               href: https://en.wikipedia.org/wiki/GeoJSON
               hreflang: en-US
-        linked-data:
-            item_template: tests/data/base.jsonld
         extents:
             spatial:
                 bbox: [-180,-90,180,90]