Json ld docs (#326)

* adds structured data section to configuration documentation * adds json-ld support button/badge
2019-12-25 01:51:54 +13:00
parent db2185696a
commit 2e6f9abcb0
2 changed files with 51 additions and 3 deletions
@@ -4,6 +4,8 @@

 pygeoapi provides an API to geospatial data

+[![JSON-LD support](https://json-ld.org/images/json-ld-button-88.png)](https://json-ld.org/images/)
+
 ## Installation

 ```bash
@@ -70,7 +72,7 @@ https://github.com/geopython/demo.pygeoapi.io.

 Best/easiest way to run `pygeoapi` is to use Docker. On DockerHub [pygeoapi Docker Images](https://hub.docker.com/r/geopython/pygeoapi) are available.

-Please read the [docker/README](https://github.com/geopython/pygeoapi/blob/master/docker/README.md) for details of the Docker implementation. 
+Please read the [docker/README](https://github.com/geopython/pygeoapi/blob/master/docker/README.md) for details of the Docker implementation.

 ### Unit Testing

@@ -18,5 +18,51 @@ Using ``pygeoapi-config.yml`` as reference we will have the following sections:
   * `metadata` server and content metadata (information used to populate multiple content)
   * `datasets` data content offered by server (collections in WFS3.0)

-   
-   
+Structured data
+---------------
+
+.. image:: https://json-ld.org/images/json-ld-logo-64.png
+    :width: 64px
+    :align: left
+    :alt: JSON-LD support
+
+pygeoapi supports structured metadata about a deployed instance, and is also capable of presenting feature data as structured data. `JSON-LD <https://json-ld.org/>`_ equivalents are available for each HTML page, and are embedded as data blocks within the corresponding page for search engine optimisation (SEO). Tools such as the `Google Structured Data Testing Tool <https://search.google.com/structured-data/testing-tool#url=https%3A%2F%2Fdemo.pygeoapi.io%2Fmaster>`_ can be used to check the structured representations.
+
+The metadata for an instance is determined by the content of the `metadata` section of the configuration YAML. This metadata is included automatically, and is sufficient for inclusion in major indices of datasets, including the `Google Dataset Search <https://developers.google.com/search/docs/data-types/dataset>`_.
+
+For collections, at the level of an item or items, by default the JSON-LD representation adds:
+
+- The GeoJSON JSON-LD `vocabulary and context <https://geojson.org/geojson-ld/>`_ to the ``@context``.
+- An ``@id`` for each feature in a collection, that is the URL for that feature (resolving to its HTML representation in pygeoapi)
+
+.. note:: While this is enough to provide valid RDF (as GeoJSON-LD), it does not allow the *properties* of your features to be unambiguously interpretable.
+
+pygeoapi currently allows for the extension of the ``@context`` to allow properties to be aliased to terms from vocabularies. This is done by adding a ``context`` section to the configuration of a `dataset`.
+
+The default pygeoapi configuration includes an example for the ``obs`` sample dataset:
+
+.. code-block:: yaml
+
+  context:
+      - datetime: https://schema.org/DateTime
+      - vocab: https://example.com/vocab#
+        stn_id: "vocab:stn_id"
+        value: "vocab:value"
+
+This is a non-existent vocabulary included only to illustrate the expected data structure within the YAML configuration. In particular, the links for the ``stn_id`` and ``value`` properties do not resolve. We can extend this example to one with terms defined by schema.org:
+
+.. code-block:: yaml
+
+  context:
+      - schema: https://schema.org/
+        stn_id: schema:identifer
+        datetime:
+            "@id": schema:observationDate
+            "@type": schema:DateTime
+        value:
+            "@id": schema:value
+            "@type": schema:Number
+
+Now this has been elaborated, the benefit of a structured data representation becomes clearer. What was once an unexplained property called ``datetime`` in the source CSV, it can now be `expanded <https://www.w3.org/TR/json-ld-api/#expansion-algorithms>`_ to `<https://schema.org/observationDate>`_, thereby eliminating ambiguity and enhancing interoperability. Its type is also expressed as `<https://schema.org/DateTime>`_.
+
+This example demonstrates how to use this feature with a CSV data provider, using included sample data. The implementation of JSON-LD structured data is available for any data provider but is currently limited to defining a ``@context``. Relationships between features can be expressed but is dependent on such relationships being expressed by the dataset provider, not pygeoapi.