SchemaDevelopmentWorkflow

Overview

This page provides details on authoring and managing WCMP2 schemas.

JSON Schema

JSON Schema provides a JSON dialect to create annotated schema definitions in support of JSON document validation (similar to what W3C XML Schema is to validation XML documents). A JSON Schema document is simply JSON with a specific grammar/dialect.

The specification provides the rules and structure of crafting a JSON Schema document. In addition, the learning resources section provides examples and guides on becoming more familiar with JSON Schema.

YAML

YAML is a superset of JSON and, when decoded, has similar representations as JSON. For example, in Python, parsing YAML or JSON results in a Python native dictionary data type.

YAML is typically easier to author (less verbose/quoting/brackets), for example:

JSON example:

{
    "data": {
        "foo": "bar"
    }
}

YAML example:

data:
    foo: bar

Given that YAML is typically easier to author, there exist many JSON schema documents authored as YAML. This is typical in OpenAPI document definitions and associated tooling (i.e. Swagger). Creating JSON Schema documents as YAML provides an easier management workflow, as well as the ability to serialize YAML to JSON for official publications of JSON Schemas as required. Organizations may also choose to simply publish the JSON Schema as YAML (i.e. this is common practice in OGC API specifications).

Schema examples

Standards

• OGC API - Features schemas: https://github.com/opengeospatial/ogcapi-features/tree/master/core/openapi/schemas
• OGC API - Records schemas: https://github.com/opengeospatial/ogcapi-records/tree/master/core/openapi/schemas

Software

• pygeometa schemas: https://github.com/geopython/pygeometa/blob/master/pygeometa/schemas/mcf/core.yml

Development workflow

Stoplight Studio (free and open source) is a full GUI environment (web-based or desktop) for designing schemas, models and APIs (JSON/YAML/OpenAPI). WCMP2 schema bundles are generated using Stoplight Studio.

WCMP2 schemas are managed in YAML, and bundled JSON Schema are generated to the main branch of this repository in schemas/wcmp2-bundled.json.

WCMP2 validation tools

There exist numerous toolkits for working with JSON Schema and YAML in a variety of programming languages. Contributors are free to use tools of their choice/preference, however given the significant use of Python in WMO projects, we will use Python tools to help demonstrate WCMP2 validation.

The following tools are required before setting up a validation environment:

• Python
• pip

Installation

## install dependencies
pip3 install check-jsonschema

Workflow

# validate an instance document against the schema
check-jsonschema --schemafile schemas/wcmp2-bundled.json /path/to/sample/wcmp-file.json