From a4acbb530189c301ee6be7d7501fa0ea5fdaed52 Mon Sep 17 00:00:00 2001 From: Rob Atkinson Date: Fri, 26 Jul 2024 09:51:49 +1000 Subject: [PATCH] Improved overview with principles. --- _pages/index.markdown | 19 +++++++---- _pages/overview/principles.md | 60 +++++++++++++++++++++++++++++++++++ _pages/overview/whatis.md | 2 +- _pages/qr.markdown | 8 +++++ 4 files changed, 81 insertions(+), 8 deletions(-) create mode 100644 _pages/overview/principles.md create mode 100644 _pages/qr.markdown diff --git a/_pages/index.markdown b/_pages/index.markdown index 5b49684..9923013 100644 --- a/_pages/index.markdown +++ b/_pages/index.markdown @@ -1,16 +1,21 @@ --- -title: OGC Building Blocks +title: OGC Specification Building Blocks 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. -![](../assets/bblocks-qr.png) +[drawing QR code](/qr) -Building Blocks may be various [types](overview/types) - however the emphasis is semantically annotated schemas for use in OGC API definitions. +This is the documentation for the OGC Building Blocks framework, a **specification component** packaging approach. -A key application is the [register of OGC Specification Building blocks](https://opengeospatial.github.io/bblocks/register/) +This supports the FAIR principles for **specifications** - with every specification being a component that can be re-used. For more discussion see [Design Principles](/overview/principles) -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. +Building Blocks can be used to **add documentation** to existing specification components, or to **design** and **assemble** reusable specification components cost-effectively using a test-driven approach. -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. +Building Blocks are _"technology agnostic"_ - i.e. may be various [types](overview/types) - however a emphasis is support for semantically annotated JSON schemas for use in OGC API definitions. + +Building Blocks can be organised into [registers](overview/registers) for convenience, each repository creating a local register that can be integrated with other application domain registers. + +Published OGC API specifications are, or will be, described in the [register of OGC Specification Building blocks](https://opengeospatial.github.io/bblocks/register/). The framework can be used for development of specifications or publication of specifications in your own application domain. The framework supports transparent **federation of Building Block registers.** + +The framework 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. diff --git a/_pages/overview/principles.md b/_pages/overview/principles.md new file mode 100644 index 0000000..55e8158 --- /dev/null +++ b/_pages/overview/principles.md @@ -0,0 +1,60 @@ +--- +title: Design Principles +permalink: /overview/principles +--- + +The OGC Building Block framework addresses the gap between the FAIR principles and traditional approaches to designing and publishing interoperability specifications. + +The focus is on **Reusability**, as the point at which value is achieved for both specification creators and specification consumers. + +Resuability of common components enhances specification development speed and quality. + +Identification of commonalities reduces effort for consumers to understand and exploit specifications. + +A range of specific design goals addressed by the OGC Building Blocks are discussed below. + +## Abstraction Neutrality +Specifications may apply to different levels of abstraction - i.e. conceptual vs. physical. +The design principles described here apply to all levels of abstraction. In particular it must be possible to describe and navigate (Findability) the relationships between specifications at different levels of abstraction. + +## Technology Neutrality +Specifications may be tied to a specific technology (e.g. JSON schema), which may be appropriate to a given level of abstraction. The core principles of Building Blocks are independent of the specification technology used. + +That said, higher levels of support may be provided for key technologies. A particular focus is on the emerging generation of JSON based APIs and data formats and the challenges of semantic interoperability. Building Blocks may be defined for ontologies, UML models, XML schemas, database schemas or any other technology. + +## Transparency of Dependencies and Commonality +Explicit dependencies between Building Blocks support Findability and understanding (Re-use), and in some cases can directly support interoperability at run-time. + +Many specification languages or target technologies are poor at exposing such dependencies, particularly between different levels of abstraction using different specification languages. Building Blocks allow a **common canonical expression of specification relationships**. These relationships can be published as a Knowledge Graph, + +## Federation + +Building Blocks must support re-use of components across different governance domains. This is supported by [Transparency](#transparency-of-dependencies-and-commonality). + +Managing distributed development and evolution cycles is supported by [Regression Testing](#testing.) + +## Profiling + +Building Blocks should be simple to specialise. + +See [Profiles](profiles.md) + +## Testing + +Testing is automated, and functions in at least four modes: + +1) Basic syntax checking of components and descriptions +2) Unit tests of example implementations for individual components, including positive and negative tests +3) Integration testing, including inheritance of tests from dependencies +4) Regression testing to ensure continual compliance with dependent components. + + + + + + + + + + + diff --git a/_pages/overview/whatis.md b/_pages/overview/whatis.md index 3600104..16fefeb 100644 --- a/_pages/overview/whatis.md +++ b/_pages/overview/whatis.md @@ -2,7 +2,7 @@ title: What is a Building Block? permalink: /overview/whatis --- -An Building Block is a way of packaging a component of a specification that can be re-used in other specifications. +An Building Block is a way of packaging a component of a **specification** that can be re-used in other specifications. For various reasons specifications have often made statements in text regarding how they relate to other specifications, and created implementation artefacts such as schemas that may not make these intentions explicit. The following diagram shows how Building Blocks form a value-added packaging option for such specification elements that can then be exploited as part of a comprehensive knowledge base to support discovery and re-use (FAIR principles). diff --git a/_pages/qr.markdown b/_pages/qr.markdown new file mode 100644 index 0000000..6937d1f --- /dev/null +++ b/_pages/qr.markdown @@ -0,0 +1,8 @@ +--- +title: QR link OGC Specification Building Blocks +permalink: / +--- +Find documents online at https://ogcincubator.github.io/bblocks-docs/ + +![](../assets/bblocks-qr.png) +