Skip to main content

OGC API Service Profile Builder

Describe an OGC API - EDR Part 3 service profile in one YAML file. The builder validates it and generates everything the profile needs: an OpenAPI definition, an AsyncAPI definition for pub/sub, the requirements and abstract tests, and a publication-ready OGC PDF.

PyPI License

Full detail: every command, option and config field is in the Reference.


Install

pip install 'oapi-profile-builder[pdf]'
  • PDF output (--pdf) and the OGC CITE tests run in Docker, so install Docker for those.
  • Testing a live server with validate-server needs pip install 'oapi-profile-builder[validate]'.

Quick start

# 1. Start from an example
curl -O https://raw.githubusercontent.com/ShaneMill1/OGC-API-Service-Profile-Builder/main/examples/minimal_profile.yaml

# 2. Check it
oapi-profile-builder validate --config minimal_profile.yaml

# 3. Generate the artifacts (drop --pdf if you don't have Docker)
oapi-profile-builder generate --config minimal_profile.yaml --output ./output --pdf
output/
├── openapi.yaml          # OpenAPI 3.0 / 3.1 for Swagger UI, Redoc, schemathesis
├── asyncapi.yaml         # only when the profile defines pubsub
├── document.pdf          # the OGC profile document (with --pdf)
├── document.adoc         # its Metanorma source, with sections/, requirements/, abstract_tests/
└── profile_config.json   # the validated profile

validate and generate also print a summary of the profile's requirements, recommendations and permissions. Invalid configs fail with a message naming the field.

Write a profile

A profile has four parts: identity, the collections a conforming service exposes, the requirements, and the document metadata.

name: my_profile                      # lowercase; used in identifiers
title: My EDR Profile

collections:                          # what a conforming service exposes
  - id: temperature
    title: Temperature Observations
    links: [{href: "https://example.com/collections/temperature", rel: self}]
    extent:
      spatial:
        bbox: [[-180, -90, 180, 90]]
        crs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
    parameter_names:
      temp:
        type: Parameter
        observedProperty: {label: Air Temperature}
        unit: {label: Celsius, symbol: {value: "°C", type: "http://www.opengis.net/def/uom/UCUM/degC"}}

requirements:                         # SHALL = requirement, SHOULD = recommendation, MAY = permission
  - id: temperature-geojson
    title: GeoJSON response            # the requirement's heading
    description: Clients need a predictable encoding for temperature observations.   # informative
    parts:                             # the normative text, one row each
      - The temperature collection SHALL return GeoJSON features.
      - The response Content-Type SHALL be application/geo+json.

abstract_tests:                       # one per requirement (SHALL)
  - id: temperature-geojson
    requirement_id: temperature-geojson
    steps:
      - Send GET /collections/temperature/items and check the Content-Type.

document_metadata:                    # only needed for the PDF
  doc_number: "26-001"
  editors: [Your Name]

The full working version is examples/minimal_profile.yaml. For editor autocompletion and checking, point your YAML editor at profile.schema.json.

What you can do

Task How Example
Constrain implementations: CRS/TRS, bounding box, required queries, ID and parameter-name patterns, license links extent_requirements, required_data_queries, collection_id_pattern, … Reference insitu
Requirements, recommendations, permissions: only SHALL is conformance-tested; SHOULD/MAY are informative requirements[].level (inferred from SHALL/SHOULD/MAY). Reference minimal, walkthrough
Several conformance classes in one profile, with class-specific rules requirements[].conformance_class, conformance_class_requirements. Reference metocean
Write the document: your own text, Markdown, PlantUML diagrams, images and preformatted (ASCII) text in any section requirements[].description, document_metadata.body. Below documentation content
Brand the PDF for another organization (logo, colors, legal page, identifiers) document_metadata.cover, colors, boilerplate, spec_uri_base. Reference DGIWG radar
Tailor the OpenAPI per endpoint: formats, optional parameters, status codes and error messages, example responses shaped by your parameters query_options, http_responses. Reference DGIWG lightning
Pub/Sub (AsyncAPI), OGC API Processes, Features paging pubsub, processes, paging. Reference NWS Connect, NWSViz

Write the document

The PDF is generated from the config, and you can add your own material anywhere without losing the generated text. A content block has a format:

  • markdown for prose, lists and tables.
  • plantuml for a diagram, rendered as a captioned figure.
  • preformatted for ASCII art or console output, reproduced exactly.
  • asciidoc for anything Metanorma supports.
requirements:
  - id: temperature-geojson
    title: GeoJSON response
    parts: [The temperature collection SHALL return GeoJSON features.]
    description:                            # before the box; description_position: after moves it
      - format: plantuml
        title: Request flow
        body: "Client -> Service: GET /collections/temperature/items"

document_metadata:
  body:
    section_content:
      scope:                                # added to the end of the Scope section
        - format: preformatted
          title: Collections
          body: |
            temperature  +-- temp (degC)

Content can go in any generated section, at its start or end, and in your own clauses and annexes. The documentation_content example uses every option; see its compiled PDF. Details are in the Reference.

Requirements are laid out like OGC 26-027: the title is the heading, the description is informative text before the box, and the box holds the identifier and the parts. The description can be one sentence or blocks with tables, figures and diagrams; set description_position: after to place it after the box, as a note. There is no Statement row. Profiles that still use statement keep their Statement row, with a deprecation warning.

Examples

Example Shows
minimal_profile Smallest valid profile: one collection, one requirement, recommendation and permission
documentation_content_profile Markdown, PlantUML, images and preformatted text in the PDF
insitu_observations_profile Full meteorological profile: units, CF names, CRS lists, custom dimensions
metocean_profile The OGC MetOcean profile: four conformance classes, OGC-style clauses and annexes
nws_connect_profile Pub/Sub: generates asyncapi.yaml
nwsviz_profile 13 collections and 3 OGC API Processes
nwp_radar, nwp_earth_observations_lightning_profile DGIWG-branded PDFs

The generated output of each example, PDFs included, is in generated/.

Test a live server

# Check a server against the profile's OpenAPI (schemathesis)
oapi-profile-builder validate-server --config my_profile.yaml --url https://my-server.example.com

# Run the official OGC CITE suites (Docker)
oapi-profile-builder cite-test          --url https://my-server.example.com   # EDR Part 1
oapi-profile-builder cite-test-features --url https://my-server.example.com   # Features Part 1

Use it from GitHub

  • Without installing anything: open an issue with the Generate profile artifacts template and paste your YAML. A workflow replies with the generated files.

  • In your own workflow:

    - uses: ShaneMill1/OGC-API-Service-Profile-Builder@main
      with:
        config: my_profile.yaml
        output: ./profile_output
        pdf: true
    

Inputs and the issue workflow are described in the Reference.

Commands

Command Does
generate --config <file> --output <dir> [--pdf] Validate and write all artifacts
validate --config <file> Validate only
validate-server --config <file> --url <url> Test a live server against the profile
cite-test / cite-test-features --url <url> Run the OGC CITE suites
schema [--output <file>] Print the config JSON Schema

Use it from Python

from pathlib import Path
from oapi_profile_builder.cli import load_config
from oapi_profile_builder.models import ServiceProfile
from oapi_profile_builder.generate import generate

profile = ServiceProfile.model_validate(load_config(Path("my_profile.yaml")))
generate(profile, Path("./output"))

Standards

OGC API - EDR Part 1 · Part 2: PubSub · Part 3: Service Profiles (draft) · OGC API - Processes · OpenAPI 3.1 · AsyncAPI 3.0 · Metanorma

License and contact

Apache 2.0, see LICENSE. Shane Mill, NOAA/NWS/MDL, shane.mill@noaa.gov. Issues.

Metadata

Release files for oapi-profile-builder 3.17.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oapi-profile-builder 3.17.0
File Size Uploaded Provenance Actions
oapi_profile_builder-3.17.0.tar.gz 101.3 kB With provenance Details for oapi_profile_builder-3.17.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oapi-profile-builder 3.17.0
File Interpreter ABI Platform Actions
oapi_profile_builder-3.17.0-py3-none-any.whl Python 3 none any Details for oapi_profile_builder-3.17.0-py3-none-any.whl

Total release size: 209.5 kB

Release files / oapi_profile_builder-3.17.0.tar.gz

Download URL oapi_profile_builder-3.17.0.tar.gz
Size 101.3 kB
Tags Source
SHA-256 checksum
How to use checksums
b55e7bd7139ecb7ee5284b4d53710caf704fef70f11cc0fd1cf193797994d340
BLAKE2b-256 checksum
How to use checksums
ec9d365329aa316d7638bfb0fe94b49992581ac9011e1895e62dd7faaa258029
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / oapi_profile_builder-3.17.0-py3-none-any.whl

Download URL oapi_profile_builder-3.17.0-py3-none-any.whl
Size 108.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
93e6b43397f5f74e2f75789c69fcc6d094c2876a3cc299ad07d8fe9c5636de97
BLAKE2b-256 checksum
How to use checksums
825d56155ea3d21280aa75a38b456212090310f659aff6322cc4c62f655060f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for oapi-profile-builder 3.17.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for oapi_profile_builder-3.17.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.17.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page