ogcincubator / bblock-prov-schema

A JSON schema and context for the PROV-O vocabulary. This provides a pathway to incorporate provenance data into OGC API and other OAS environments - and a baseline for spatio-temporal data operation provenance specialisations

OGC Building Block template

This repository defines a "building block" for use of PROV-O Vocabulary using a schema valid for either JSON or JSON-LD implementation. (See "Other Prov JSON serialisations" )

The "ready-to-use" form is generated here:

The JSON schema allows for either nested instances of PROV classes, or for arrays of objects linked by identifiers, and the use of external URI identifiers for PROV objects.

Such a schema is complex, and the purpose of this building block is to provide a canonical implementation supported by validation and examples.

The JSON-LD context binds these structures to the PROV-O vocabulary.

If provided SHACL rules perform consistency checking above and beyond schema validation.

Other Prov JSON serialisations

NB. The W3C PROV working group published two early project drafts for JSON and JSON-LD serialisations, however these are not ideal solutions because:

• the JSON is not directly mappable to the PROV-O ontology via JSON-LD
• the JSON-LD serialisation is -LD specific and not compatible with normal JSON schemas.
• neither is supported by a formally published JSON Schema.
• neither schema supports annotation of existing objects as prov:Entities - requiring specialised structures to register all entities under a "entities" property.

This building block defines a schema that avoids all these limitations. Users may choose to define a building block that allows either one of the published JSON forms or this schema for backwards compatibility, however there is little evidence of significant usage of the published drafts.

General

OGC Building Blocks are defined by the Open Geospatial Consortium to support implementation of customised applications consistent with OGC specifications.

Building Blocks are supported by git actions to post-process the components, testing the structure, examples and test-case data. This post-processing handles the complex task of integrating references to other building blocks into a ready-to use form, allowing building blocks to be composed into complete applications.

Many such BuildingBlocks define bindings to the object structures supported by APIs (such as GeoJSON Features).

The PROV building block defines a "datatype" - i.e. a sub-schema that can be used to annotate such features or any other schema.

Build (local) shortcut

docker run --rm --workdir /workspace -v "$(pwd):/workspace" --pull=always ghcr.io/opengeospatial/bblocks-postprocess --clean true --base-url https://test.org/ --generated-docs-path build-local/generateddocs --annotated-path build-local/annotated --register-file build-local/register.json --test-outputs build-local/tests

OGC Building Block structure

Building Blocks can be reused by either:

• cut and paste "ready to use" forms from the "build/" directory

• directly reference the artefacts in the "build" directory using the URL pattern specified in the building block description

• including as source using git submodule add {building block repository} and referencing reused components directly. (in which case the build/ resources of the submodule will referenced in the build/ outputs, but the source definitions will be used for consistency checking and optimisation)

Building Block development

You can find information how Building Blocks are constructed in USAGE.md.