diff --git a/_data/navigation.yml b/_data/navigation.yml index 7b76ee6..9e65c1a 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -11,15 +11,18 @@ docs: url: /overview/types - title: Types (Patterns) url: /overview/types#patterns - + - title: Quick Start + children: + - title: Local Build + url: /build/local - title: Using the Building Blocks children: - title: Finding Building Blocks url: /use/finding - title: Reusing schemas - - title: Reusing schemas - url: /use/ftc + url: /use/reusing-schemas - title: Linked Data / JSON-LD Context + url: /use/linked-data - title: Creating Building Blocks children: - title: Overview diff --git a/_pages/build/local.md b/_pages/build/local.md new file mode 100644 index 0000000..25b1ce3 --- /dev/null +++ b/_pages/build/local.md @@ -0,0 +1,27 @@ +--- +title: Quick Start - local build +permalink: /build/local +--- + + +## Quick how-to create + +1. Install docker +2. Check out any valid Building Block implementation (e.g. [bblocks-examples](https://ogcincubator.github.io/bblocks-examples/)) +3. cd to the new directory +4. run build.sh or build.bat if present + - this will access the current build scripts and compile the building block locally + - if not present run the command + ```shell +# Process building blocks +docker run --pull=always --rm --workdir /workspace -v "$(pwd):/workspace" \ + ghcr.io/opengeospatial/bblocks-postprocess --clean true +``` +5. run the view.sh or view.bat to preview the local build + - if not present run + ```shell +docker run --rm --pull=always -v "$(pwd):/register" -p 9090:9090 ghcr.io/ogcincubator/bblocks-viewer +``` +You can now experiment with the source material - or proceed to [create your own building blocks](../create). + +(create a fork if you want to update the the repository so you can submit pull requests. The local build outputs will be ignored automatically on updates.) \ No newline at end of file diff --git a/_pages/create/index.md b/_pages/create/index.md index c1a9ba3..e5b3dae 100644 --- a/_pages/create/index.md +++ b/_pages/create/index.md @@ -2,13 +2,15 @@ title: How to create Building Blocks permalink: /create --- -Building Blocks can be reused by either: +## starting point options: -- 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 +1. Create from scratch using a template - see below +2. Fork an existing repository to update or add new building blocks, and generate a Pull Request to submit to the register owner +2. Copy any building block repository and edit `bblocks-config.yaml` and the `_sources/*` to create a new register -## Quick how-to +In all cases follow the [local build process](../build/local) to test before committing to an online repository. + +## Quick how-to create 1. Navigate to the [bblock-template](https://github.com/opengeospatial/bblock-template) repository. 2. Click on "Use this template" on GitHub (do not fork this repository, or you will have to manually enable the diff --git a/_pages/create/metadata.md b/_pages/create/metadata.md index 2631e56..0e177c3 100644 --- a/_pages/create/metadata.md +++ b/_pages/create/metadata.md @@ -4,4 +4,4 @@ permalink: /create/metadata --- Building block metadata provides context information about the item in the building blocks register. It is based on [ISO 19135](https://www.iso.org/standard/54721.html), the standard for item registration of geographic information, from which it extracted its six mandatory items (flagged with *). The ISO schema is extended with other properties (in green), which account for things such as the visual representation in the register, item validation or relation with other building blocks. -[![building block](/assets/bblock.png)](/assets/bblock.png) +[![building block](../assets/bblock.png)](../assets/bblock.png) diff --git a/_pages/create/rdf-only.md b/_pages/create/rdf-only.md index 6bb1394..6fbfb12 100644 --- a/_pages/create/rdf-only.md +++ b/_pages/create/rdf-only.md @@ -5,8 +5,8 @@ permalink: /create/rdf-only Building Blocks can be defined that use RDF only. An RDF building block can: 1. Define RDF (TTL) examples how to use the Semantic model -2. Apply SHACL Rules to [validate examples](TESTING.md#SHACL) -3. [Perform transforms](TXFORMS.md) and validate results +2. Apply SHACL Rules to [validate examples](validation#shacl-validation) +3. [Perform transforms](transforms) and validate results Test cases and examples as either TTL or JSONLD will undergo syntax and SHACL validation. diff --git a/_pages/create/schema.md b/_pages/create/schema.md index 18855b3..0055af3 100644 --- a/_pages/create/schema.md +++ b/_pages/create/schema.md @@ -39,7 +39,7 @@ this is done in a two-step process: 2. use the `bblocks:://{id}` syntax as href in schema $ref elements. - This means your building block will inherit all json-ld contexts and SHACL rules from the referenced building block automatically and apply during [testing](TESTING.md). + This means your building block will inherit all json-ld contexts and SHACL rules from the referenced building block automatically and apply during [testing](../create/validation). # Profiling JSON Schemas diff --git a/_pages/create/structure.md b/_pages/create/structure.md index fdcb332..9b161c7 100644 --- a/_pages/create/structure.md +++ b/_pages/create/structure.md @@ -5,7 +5,7 @@ permalink: /create/structure The following image summarizes the general usage of a building block: -[![Usage](/assets/usage.png)](/assets/usage.png) +[![Usage](../assets/usage.png)](../assets/usage.png) ## Building Block sources diff --git a/_pages/index.markdown b/_pages/index.markdown index 890f3be..5b49684 100644 --- a/_pages/index.markdown +++ b/_pages/index.markdown @@ -4,11 +4,13 @@ permalink: / --- This is the documentation for OGC Building Blocks, a specification component packaging approach that can be used to **add documentation** to existing specification components, or to assemble specifications cost-effectively using a test-driven approach. -This packaging supports testing of examples, and validation using rules inherited from other Building Blocks that are re-used (by aggregation or profiling) to create compatible specifications for specific applications. +![](../assets/bblocks-qr.png) + +Building Blocks may be various [types](overview/types) - however the emphasis is semantically annotated schemas for use in OGC API definitions. -Building Blocks make various different [types](/overview/types) of specification component accessible in a common, convenient form and registers. A key innovation is support for **semantically annotated schemas**, suitable for use in OpenAPI definitions. +A key application is the [register of OGC Specification Building blocks](https://opengeospatial.github.io/bblocks/register/) -The Building Block documentation framework is the basis of the [register of OGC Specification Building blocks](https://opengeospatial.github.io/bblocks/register/). +This packaging supports testing of examples, and validation using rules inherited from other Building Blocks that are re-used (by aggregation or profiling) to create compatible specifications for specific applications. -OGC BuildingBlocks can be organised into [registers](/overview/registers) for convenience, each repository creating a local register that can be aggregated into another application domain register. +OGC BuildingBlocks can be organised into [registers](overview/registers) for convenience, each repository creating a local register that can be aggregated into another application domain register. diff --git a/_pages/overview/profiles.md b/_pages/overview/profiles.md index f498e16..d3d5600 100644 --- a/_pages/overview/profiles.md +++ b/_pages/overview/profiles.md @@ -28,6 +28,17 @@ Because many technologies like JSON and RDF are permissive (by default) about ad Profiles can be designed as separate re-usable sets of constraints that can be reused - for example a time-series of water-quality monitoring observations could be specified as a profile of both a time-series profile of Observations and a water-quality profile for the results of such observations. In turn the time-series profile could defined as data structure using GeoJSON, or Coverage JSON. The water-quality content requirements could be described using constraints independent of the data structure. +## Profiles for infrastructure compatibility + +Profiles can be layered to meet different needs. The typical usage is for applications that are compatible with shared infrastructures, where applications may be designed to interact with other applications, but the supporting infrastructures for these applications may also be designed to interoperate with other infrastructures. + +Underlying standards allow reusable software and libraries to be used at all levels. + +This can be visualised as a layered model of typical profiles, identifying the types of constraints typically present at each layer. + +![Profile layers](profiles.png) + + ## What forms of constraints are possible? The **OGC BuildingBlock** model supports a range of possible constraint approaches. The goal is to make such constraints **_machine-readable_** to the extent possible. @@ -40,7 +51,7 @@ Built-in support is provided for automatic validation of the following forms: - JSON schema (for JSON examples) for **structure** - SHACL (Shapes Constraint Language for RDF) for **content** and **logical consistency** -In addition [custom validators](VALIDATORS) can be added to the validation workflow. +In addition [custom validators](../create/validation) can be added to the validation workflow. Using a JSON-LD context "semantic uplift" of JSON to RDF supports use of SHACL and other forms of validators to diff --git a/_pages/overview/profiles.png b/_pages/overview/profiles.png new file mode 100644 index 0000000..e99578d Binary files /dev/null and b/_pages/overview/profiles.png differ diff --git a/_pages/use/finding.md b/_pages/use/finding.md index 379c658..8bbe3bf 100644 --- a/_pages/use/finding.md +++ b/_pages/use/finding.md @@ -8,7 +8,7 @@ Whilst components described as Building Blocks may be referenced by individual s The OGC Building Block Framework provides three improved approaches for discovery: -1. [Registers](/overview/registers) +1. [Registers](../overview/registers) 1. [RAINBOW (OGC Knowledge Graph)]() 1. Transparent Dependencies diff --git a/_pages/use/linked-data.md b/_pages/use/linked-data.md new file mode 100644 index 0000000..45e030b --- /dev/null +++ b/_pages/use/linked-data.md @@ -0,0 +1,6 @@ +--- +title: Linked Data / JSON-LD Context +permalink: /use/linked-data +--- + +# TBD \ No newline at end of file diff --git a/_pages/use/reusing-schemas.md b/_pages/use/reusing-schemas.md new file mode 100644 index 0000000..31e5cc5 --- /dev/null +++ b/_pages/use/reusing-schemas.md @@ -0,0 +1,12 @@ +--- +title: Reusing schemas +permalink: /use/reusing-schemas +--- + +Building Blocks can be reused in several ways: + +- if creating a JSON schema based BuildingBlock then use the $ref: bblocks://{block id} to make a JSON schema reference to any building block in the import list [see imports](../create/imports) +- for other [types of Building Blocks](../overview/types) declare as an entry in the dependsOn element of a `block.json` metadata file +- cut and paste "ready to use" forms from the `build/` directory of any building block repository into a some other form of application (not a reusable Building Block itself) +- directly reference the artefacts in the `build` directory using the URL pattern specified in the building block + description (noting this may be affected by changes if a building block is moved from one register to another - bblocks:// references will still work if imports approach is used.) diff --git a/assets/bblocks-qr.png b/assets/bblocks-qr.png new file mode 100644 index 0000000..aca6c15 Binary files /dev/null and b/assets/bblocks-qr.png differ