oapi-profile-builder 2.1.9__tar.gz → 2.3.0__tar.gz

oapi_profile_builder-2.3.0/PKG-INFO

@@ -0,0 +1,565 @@
+Metadata-Version: 2.4
+Name: oapi-profile-builder
+Version: 2.3.0
+Summary: Authoritative tooling for creating OGC API Service Profiles (EDR, Features)
+Author-email: Shane Mill <shane.mill@noaa.gov>
+License: Apache License
+        Version 2.0, January 2004
+        http://www.apache.org/licenses/
+        
+        Copyright 2025 NOAA/NWS/Meteorological Development Laboratory
+        
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+            http://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+        
+Project-URL: Homepage, https://github.com/ShaneMill1/OGC-API-Service-Profile-Builder
+Project-URL: Issues, https://github.com/ShaneMill1/OGC-API-Service-Profile-Builder/issues
+Keywords: ogc,edr,features,environmental-data-retrieval,profile,openapi,asyncapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: edr-pydantic>=0.3
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Provides-Extra: validate
+Requires-Dist: schemathesis>=3.0; extra == "validate"
+Dynamic: license-file
+
+# OGC API Service Profile Builder
+
+Generate OGC API - EDR Part 3 Service Profile artifacts from a YAML config — OpenAPI 3.1.0, AsyncAPI, AsciiDoc requirements, and conformance tests.
+
+[![PyPI](https://img.shields.io/pypi/v/oapi-profile-builder)](https://pypi.org/project/oapi-profile-builder/)
+[![License](https://img.shields.io/badge/license-Apache-blue)](LICENSE)
+
+---
+
+## Quick Start
+
+```bash
+pip install oapi-profile-builder
+
+# Copy an example config and edit it
+cp examples/minimal_profile.yaml my_profile.yaml
+
+# Validate and generate artifacts
+oapi-profile-builder generate --config my_profile.yaml --output ./output
+```
+
+That's it. The `output/` directory will contain:
+
+```
+output/
+├── openapi.yaml          # OpenAPI 3.1.0 — ready for Swagger UI, Redoc, schemathesis
+├── profile_config.json   # Round-trip serialized profile
+├── document.adoc         # Metanorma root document
+├── sections/             # Abstract, Preface, Scope, Conformance, References, Terms
+├── requirements/         # Individual REQ_*.adoc files
+└── abstract_tests/       # Individual ATS_*.adoc files
+```
+
+---
+
+## Example Profiles
+
+Three working examples are included:
+
+| File | What it shows |
+|---|---|
+| [`examples/minimal_profile.yaml`](examples/minimal_profile.yaml) | Smallest valid profile — one collection, one requirement |
+| [`examples/insitu_observations_profile.yaml`](examples/insitu_observations_profile.yaml) | Full meteorological profile — 8 parameters with QUDT units, CF standard names, metocean extensions, CRS listing, temporal extent, custom dimensions, `parameter_schema` |
+| [`examples/nwsviz_profile.yaml`](examples/nwsviz_profile.yaml) | Production profile — 13 collections, 3 OGC API Processes, PDF metadata |
+
+---
+
+## CLI Reference
+
+```
+oapi-profile-builder generate   --config <file> --output <dir> [--pdf]
+oapi-profile-builder validate   --config <file>
+oapi-profile-builder validate-server --config <file> --url <url> [--max-examples N] [--stateful]
+oapi-profile-builder cite-test  --url <url> [--report <dir>]
+oapi-profile-builder cite-test-features --url <url> [--report <dir>]
+oapi-profile-builder schema     [--output <file>]
+```
+
+### `generate`
+
+Validates the profile config and writes all artifacts to the output directory.
+
+```bash
+oapi-profile-builder generate --config my_profile.yaml --output ./output
+```
+
+Add `--pdf` to also compile an OGC-compliant PDF via the `metanorma/metanorma` Docker image (Docker required):
+
+```bash
+oapi-profile-builder generate --config my_profile.yaml --output ./output --pdf
+```
+
+### `validate`
+
+Validates the config without writing any files. Useful in CI before generating.
+
+```bash
+oapi-profile-builder validate --config my_profile.yaml
+# Profile 'my_profile' is valid.
+```
+
+### `validate-server`
+
+Runs [schemathesis](https://schemathesis.io/) against a live server using the profile's generated OpenAPI. Requires `pip install oapi-profile-builder[validate]`.
+
+```bash
+oapi-profile-builder validate-server \
+  --config my_profile.yaml \
+  --url https://my-server.example.com \
+  --max-examples 5
+```
+
+Supply real `instanceId` values in your config so schemathesis can exercise instance-level paths:
+
+```yaml
+collection_examples:
+  my_collection:
+    instanceId: "2025-04-02T00:00:00Z"
+```
+
+### `cite-test` / `cite-test-features`
+
+Runs the official OGC CITE conformance test suites against a live server. Docker and Maven are required for `cite-test` (EDR); Docker only for `cite-test-features`.
+
+```bash
+# OGC API - EDR Part 1 (builds ets-ogcapi-edr10 on first run, ~2 min)
+oapi-profile-builder cite-test \
+  --url https://my-server.example.com \
+  --report ./cite_results
+
+# OGC API - Features Part 1 (pulls pre-built image from Docker Hub)
+oapi-profile-builder cite-test-features \
+  --url https://my-server.example.com \
+  --report ./cite_features_results
+```
+
+Results:
+
+```
+OGC API - EDR CITE Results
+  Passed:  76/84
+  Failed:  0
+  Skipped: 8
+
+✓ All CITE tests passed.
+```
+
+---
+
+## GitHub Actions
+
+No local install needed. Add this to any workflow to generate profile artifacts from a config file:
+
+```yaml
+name: Generate Profile
+
+on:
+  push:
+    paths: ['my_profile.yaml']
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Generate profile artifacts
+        uses: ShaneMill1/OGC-API-Service-Profile-Builder@main
+        with:
+          config: my_profile.yaml
+          output: ./profile_output
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: profile-artifacts
+          path: ./profile_output/
+```
+
+**To download the artifacts:** Actions tab → click the run → scroll to **Artifacts** at the bottom → download the zip.
+
+### Action inputs
+
+| Input | Default | Description |
+|---|---|---|
+| `config` | — | Path to the profile config YAML (required) |
+| `output` | `./profile_output` | Output directory |
+| `version` | `latest` | Package version to install |
+| `pdf` | `false` | Compile PDF via Metanorma (Docker required on runner) |
+| `cite-url` | — | Run OGC CITE tests against this server URL |
+| `cite-type` | `edr` | `edr`, `features`, or `both` |
+
+> **CITE + VPN:** The CITE test runner needs to reach the server from GitHub's runners. Servers behind a VPN require a [self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners).
+
+---
+
+## Profile Config Reference
+
+A profile config is a YAML file. The full JSON Schema is at [`profile.schema.json`](profile.schema.json).
+
+### Minimal valid config
+
+```yaml
+name: my_profile          # lowercase, a-z 0-9 _ only
+title: My EDR Profile
+version: "1.0"
+
+required_conformance_classes:
+  - "http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/core"
+
+extent_requirements:
+  minimum_bbox: [-180, -90, 180, 90]
+  allowed_crs:
+    - "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
+
+output_formats:
+  - name: GeoJSON
+    media_type: application/geo+json
+
+collections:
+  - id: my_collection
+    links:
+      - href: https://example.com/collections/my_collection
+        rel: self
+        type: application/json
+    extent:
+      spatial:
+        bbox: [[-180, -90, 180, 90]]
+        crs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
+    parameter_names:
+      temperature:
+        type: Parameter
+        observedProperty:
+          label: Air Temperature
+        unit:
+          label: Celsius
+          symbol: "°C"
+```
+
+### Top-level fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | string | yes | Lowercase `a-z 0-9 _`. Drives OGC URIs and OpenAPI `operationId`s |
+| `title` | string | yes | Human-readable profile title |
+| `version` | string | no | Defaults to `"1.0"` |
+| `server_url` | string | no | Documentation only — not written to the profile OpenAPI |
+| `collections` | list | yes | One or more EDR collections (see below) |
+| `required_conformance_classes` | list | no | Conformance classes implementations must declare. Defaults to EDR Core |
+| `extent_requirements` | object | no | Profile-level CRS/TRS/VRS constraints (see below) |
+| `output_formats` | list | no | Format name → media type + schema ref mappings |
+| `collection_id_pattern` | string | no | Regex all collection IDs must match |
+| `parameter_name_pattern` | string | no | Regex all `parameter_names` keys must match |
+| `parameter_schema` | object | no | JSON Schema for parameter objects — replaces the default schema in the generated OpenAPI (see below) |
+| `processes` | list | no | OGC API Processes to expose in the OpenAPI |
+| `requirements` | list | no | Normative requirements for the AsciiDoc/PDF |
+| `abstract_tests` | list | no | Conformance tests — each must reference a valid requirement `id` |
+| `pubsub` | object | no | OGC API - EDR Part 2 PubSub config — generates `asyncapi.yaml` |
+| `collection_examples` | object | no | `{collectionId: {instanceId: "..."}}` — used by `validate-server` |
+| `document_metadata` | object | no | Metanorma PDF header (doc number, editors, orgs, keywords) |
+
+---
+
+### `collections[]`
+
+Uses the [edr-pydantic](https://github.com/KNMI/edr-pydantic) `Collection` model — the same schema an EDR server returns at `/collections/{id}`.
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | yes | Collection identifier |
+| `title` | no | Human-readable name |
+| `description` | no | Longer description |
+| `links` | yes | At minimum a `self` link |
+| `extent.spatial.bbox` | yes | `[[minLon, minLat, maxLon, maxLat]]` |
+| `extent.spatial.crs` | yes | CRS URI — validated against `extent_requirements` |
+| `extent.temporal` | no | `interval`, `values`, `trs` |
+| `extent.vertical` | no | `interval`, `values`, `vrs` |
+| `extent.custom` | no | Custom dimensions (e.g. `standard_name`, `level`) |
+| `crs` | no | Full list of CRS values this collection supports |
+| `output_formats` | no | Format names this collection supports (e.g. `[CoverageJSON, GeoJSON]`) |
+| `data_queries` | no | EDR query types: `position`, `area`, `radius`, `cube`, `trajectory`, `corridor`, `locations`, `items`, `instances` |
+| `parameter_names` | no | Map of parameter id → Parameter object. All parameters must have `unit` and `observedProperty` |
+
+#### `data_queries` example
+
+```yaml
+data_queries:
+  position:
+    link:
+      href: https://example.com/collections/obs/position
+      rel: data
+      variables:
+        query_type: position
+        output_formats: [CoverageJSON]
+  radius:
+    link:
+      href: https://example.com/collections/obs/radius
+      rel: data
+      variables:
+        query_type: radius
+        output_formats: [CoverageJSON]
+        within_units: [m, km]
+        # crs_details: per-query CRS support, validated against extent_requirements
+        crs_details:
+          - crs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
+          - crs: "http://www.opengis.net/def/crs/EPSG/0/4326"
+```
+
+#### `parameter_names` example
+
+```yaml
+parameter_names:
+  air-temperature-2m:
+    type: Parameter
+    label: Air Temperature at 2m
+    description: Instantaneous air temperature at 2 metres above ground
+    observedProperty:
+      id: "https://vocab.nerc.ac.uk/standard_name/air_temperature"
+      label: Air Temperature
+    unit:
+      label: Kelvin
+      symbol:
+        value: K
+        type: "https://qudt.org/vocab/unit/K"
+    measurementType:
+      method: point
+      duration: PT0S
+```
+
+---
+
+### `extent_requirements`
+
+Constrains CRS, TRS, and VRS values across all collections. Validated at build time and embedded in the generated OpenAPI.
+
+```yaml
+extent_requirements:
+  minimum_bbox: [-180, -90, 180, 90]
+
+  # Option A: exact list
+  allowed_crs:
+    - "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
+    - "http://www.opengis.net/def/crs/EPSG/0/4326"
+
+  # Option B: regex (accepts any OGC or EPSG CRS)
+  # crs_pattern: "^http://www\\.opengis\\.net/def/crs/(OGC|EPSG)/.*$"
+
+  allowed_trs:
+    - "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
+```
+
+Either `allowed_crs` or `crs_pattern` is required. The same enum/regex approach applies to `allowed_trs`/`trs_pattern` and `allowed_vrs`/`vrs_pattern`.
+
+---
+
+### `parameter_schema`
+
+A JSON Schema fragment that replaces the default parameter schema in the generated OpenAPI. Use this to enforce field-level constraints — required fields, QUDT unit URIs, CF standard name URIs, ISO 8601 durations, and custom extension properties.
+
+```yaml
+parameter_schema:
+  type: object
+  required:
+    - type
+    - observedProperty
+    - measurementType
+    - label
+    - description
+    - unit
+    - "metocean:standard_name"
+    - "metocean:level"
+  properties:
+    unit:
+      type: object
+      properties:
+        symbol:
+          type: object
+          properties:
+            type:
+              type: string
+              pattern: "^https://qudt\\.org/vocab/unit/.*$"
+    observedProperty:
+      type: object
+      properties:
+        id:
+          type: string
+          pattern: "^https://vocab\\.nerc\\.ac\\.uk/standard_name/.*$"
+    measurementType:
+      type: object
+      properties:
+        duration:
+          type: string
+          pattern: "^P(\\d+Y)?(\\d+M)?(\\d+D)?(T(\\d+H)?(\\d+M)?(\\d+S)?)?$"
+    "metocean:standard_name":
+      type: string
+    "metocean:level":
+      type: number
+  additionalProperties: true
+```
+
+See [`examples/insitu_observations_profile.yaml`](examples/insitu_observations_profile.yaml) for a complete working example.
+
+---
+
+### `requirements[]` and `abstract_tests[]`
+
+Requirements drive the AsciiDoc/PDF output. Abstract tests must reference a valid requirement `id`.
+
+```yaml
+requirements:
+  - id: position-coveragejson          # lowercase, hyphens only
+    statement: The position query SHALL return CoverageJSON.
+    parts:
+      - The service SHALL provide a /collections/{id}/position endpoint.
+      - The response Content-Type SHALL be application/prs.coverage+json.
+
+abstract_tests:
+  - id: position-coveragejson          # must equal requirement_id
+    requirement_id: position-coveragejson
+    steps:
+      - Send GET /collections/{id}/position?coords=POINT(lon lat).
+      - Verify Content-Type is application/prs.coverage+json.
+```
+
+---
+
+### `processes[]`
+
+Adds OGC API Processes paths to the generated OpenAPI.
+
+```yaml
+processes:
+  - id: compute-difference
+    title: Compute Dataset Difference
+    description: Calculates the difference between two datasets.
+    output_content:
+      application/zip:
+        schema:
+          type: object
+```
+
+Generates: `/processes/compute-difference`, `/processes/compute-difference/execution`, `/jobs`, `/jobs/{jobId}`, `/jobs/{jobId}/results`.
+
+---
+
+### `pubsub`
+
+When present, generates `asyncapi.yaml` alongside `openapi.yaml`.
+
+```yaml
+pubsub:
+  broker_host: my-broker.example.com
+  broker_port: 5672
+  protocol: amqp          # amqp | mqtt | kafka
+  collections:
+    - my_collection
+  filters:
+    - name: station
+      description: Filter by station ID
+      type: string
+```
+
+---
+
+### `document_metadata`
+
+Required only when compiling a PDF with `--pdf`.
+
+```yaml
+document_metadata:
+  doc_number: "25-myprofile"
+  doc_subtype: implementation   # implementation | best-practice | engineering-report
+  editors:
+    - Jane Smith
+  submitting_orgs:
+    - My Organization
+  keywords:
+    - ogcdoc
+    - OGC API
+    - EDR
+  copyright_year: 2026
+  external_id: http://www.opengis.net/doc/dp/my-profile/1.0
+```
+
+---
+
+## Validation Rules
+
+The tool enforces these rules at build time. Violations produce clear error messages.
+
+| Rule | Detail |
+|---|---|
+| `name` format | Must match `^[a-z0-9_]+$` |
+| No duplicate collection IDs | Across the whole profile |
+| `extent_requirements` requires CRS spec | Either `allowed_crs` or `crs_pattern` must be set |
+| Collection CRS validated | Each `extent.spatial.crs` checked against `allowed_crs`/`crs_pattern` |
+| Collection TRS validated | Each `extent.temporal.trs` checked against `allowed_trs`/`trs_pattern` |
+| `crs_details` validated | Each `data_queries.*.variables.crs_details[].crs` checked against CRS constraints |
+| Parameters need `unit` + `observedProperty` | Required by OGC API - EDR Part 3 |
+| `parameter_name_pattern` enforced | All `parameter_names` keys must match if set |
+| `collection_id_pattern` enforced | All collection IDs must match if set |
+| Abstract test IDs match requirements | `requirement_id` must reference an existing requirement |
+| Requirement IDs | Must match `^[a-z0-9][a-z0-9\-]*$`, no trailing hyphen |
+
+---
+
+## Programmatic Use
+
+```python
+from oapi_profile_builder.models import ServiceProfile
+from oapi_profile_builder.generate import generate
+from pathlib import Path
+import yaml
+
+with open("my_profile.yaml") as f:
+    config = yaml.safe_load(f)
+
+profile = ServiceProfile.model_validate(config)  # validates everything
+generate(profile, Path("./output"))
+```
+
+---
+
+## Standards
+
+- [OGC API - EDR Part 1: Core](https://docs.ogc.org/is/19-086r6/19-086r6.html)
+- [OGC API - EDR Part 2: PubSub](https://docs.ogc.org/DRAFTS/21-009.html)
+- [OGC API - EDR Part 3: Service Profiles (draft)](https://github.com/opengeospatial/ogcapi-environmental-data-retrieval)
+- [OGC API - Processes Part 1](https://docs.ogc.org/is/18-062r2/18-062r2.html)
+- OpenAPI 3.1.0 / AsyncAPI 3.0
+- Metanorma/AsciiDoc
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).
+
+## Contact
+
+Shane Mill · NOAA/NWS/MDL · shane.mill@noaa.gov  
+Issues: https://github.com/ShaneMill1/OGC-API-Service-Profile-Builder/issues