OGC API - Processes to openEO Converter

This project provides a JSON converter to transform an OGC API - Processes processDescription (Part 1: Core, ZOO-Project style) into openEO process metadata.

openEO target: 1.3.0 (process structure of GET /processes).

Python Package Layout

The project is now organized as a package under src/openeo_ogc_converter.

• Core API: conversion and HTTP helpers (openeo_ogc_converter.core)
• Bulk API: catalog loading and list conversion (openeo_ogc_converter.bulk)
• CLI entrypoints:
  • openeo_ogc_converter.cli_single
  • openeo_ogc_converter.cli_bulk

Backward-compatible root scripts are kept:

• ogc_process_to_openeo.py
• ogc_processes_list_to_openeo.py

Build With Hatch

Install Hatch once:

python3 -m pip install hatch

Build wheel + sdist:

hatch build

Run tests:

hatch run test

Install locally in editable mode:

python3 -m pip install -e .

Then use installed commands:

ogc-process-to-openeo --help
ogc-processes-list-to-openeo --help

Or run modules directly:

python3 -m openeo_ogc_converter.cli_single --help
python3 -m openeo_ogc_converter.cli_bulk --help

Minimal API usage:

from openeo_ogc_converter.core import convert_document

openeo_process = convert_document(process_description_json)

Mapping Overview

• OGC id -> openEO id
• OGC title/description -> openEO summary/description
• OGC inputs -> openEO parameters
• OGC outputs -> openEO returns
• OGC keywords -> openEO categories (normalized to snake_case)
• OGC links -> openEO links

Important rules:

• If an input has maxOccurs > 1 (or unbounded), the openEO schema becomes an array.
• If minOccurs == 0, the openEO parameter is marked as optional: true.
• If multiple outputs exist, they are merged into a single returns.schema of type object with one property per output.

openEO Types and Subtypes

• JSON Schema base types are preserved as-is. openEO supports: string, number, integer, boolean, array, object, null. A warning is logged if a schema declares a base type outside this set.
• Common OGC format hints are mapped to openEO subtype values, for example:
  • ogc-bbox -> bounding-box
  • uri/url -> uri
  • stac, stac-collection, stac-item -> stac
  • date, date-time, time, duration -> matching subtypes
  • epsg-code -> epsg-code, wkt2 -> wkt2-definition
• The ogc-bbox pattern expressed as allOf: [{ "format": "ogc-bbox" }, ...] is detected and annotated with subtype: bounding-box.
• When the standard schema does not expose a format, the converter falls back to the ZOO-Project extensions original-schema and extended-schema to infer the subtype. These fields are optional and their absence never causes an error.
• Ambiguous oneOf/anyOf schemas are left untouched to avoid wrong subtypes.

Logging Verbosity

Both CLIs use Python logging. Control verbosity with:

• -v/--verbose: debug-level logging
• -q/--quiet: only warnings and errors

Usage

Convert a single process

python3 ogc_process_to_openeo.py process_description.json -o process_openeo.json

Force openEO /processes output format

python3 ogc_process_to_openeo.py process_description.json --as-processes-list -o processes.json

Split multi-output processes into output-specific variants

python3 ogc_process_to_openeo.py process_description.json --split-multi-outputs -o processes_split.json

When enabled, each OGC output becomes a dedicated openEO process variant with an id suffix based on the output name (for example buffer__result).

Write to stdout

python3 ogc_process_to_openeo.py process_description.json

Bulk conversion from an OGC API /processes endpoint

python3 ogc_processes_list_to_openeo.py https://example.org/ogc-api --limit 100 -o processes.json

You can also use a local JSON file as input when it contains a /processes response object (with a processes array):

python3 ogc_processes_list_to_openeo.py local_processes.json -o processes.json

To accept a local file containing a single processDescription object:

python3 ogc_processes_list_to_openeo.py process_description.sample1.json --accept-single-process-description -o processes.json

Useful options:

• --max-processes N: stop after converting N process summaries (global cap across pages)
• --split-multi-outputs: generate one openEO process variant per output
• --version auto|null|VALUE: set output version field
  • auto: reuse source /processes version when present
  • null: force JSON null
  • VALUE: set a fixed string (for example 1.3.0)

Notes for local input:

• The bulk script does not fetch /processes/{id} when using a local file.
• A single processDescription JSON file is accepted only with --accept-single-process-description.

Minimal Input Example

{
  "id": "buffer",
  "title": "Buffer",
  "description": "Create a geometry buffer.",
  "keywords": ["vector", "geometry"],
  "inputs": {
    "geom": {
      "description": "Input geometry",
      "minOccurs": 1,
      "maxOccurs": 1,
      "schema": {
        "type": "object"
      }
    },
    "distance": {
      "description": "Buffer distance",
      "minOccurs": 0,
      "maxOccurs": 1,
      "schema": {
        "type": "number",
        "default": 10
      }
    }
  },
  "outputs": {
    "result": {
      "description": "Buffered geometry",
      "schema": {
        "type": "object"
      }
    }
  }
}

Current Limitations

• JSON schema mapping is structural: it does not translate domain vocabularies.
• Non-standard OGC attributes are ignored unless already compatible with openEO.
• Listed processes without inputs/outputs (summaries only) cannot be converted into complete openEO processes.