oapi-profile-builder 3.0.1__tar.gz → 3.2.0__tar.gz

{oapi_profile_builder-3.0.1/src/oapi_profile_builder.egg-info → oapi_profile_builder-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oapi-profile-builder
-Version: 3.0.1
+Version: 3.2.0
 Summary: Authoritative tooling for creating OGC API Service Profiles (EDR, Features)
 Author-email: Shane Mill <shane.mill@noaa.gov>
 License: Apache License
@@ -41,11 +41,13 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.31
 Provides-Extra: validate
 Requires-Dist: schemathesis>=3.0; extra == "validate"
+Provides-Extra: pdf
+Requires-Dist: pillow>=10.0; extra == "pdf"
 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.
+Generate OGC API - EDR Part 3 Service Profile artifacts from a YAML config — OpenAPI 3.1.0, AsyncAPI, AsciiDoc requirements and conformance tests, and a publication-ready Metanorma PDF with optional custom (e.g. DGIWG) branding.
 
 [![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)
@@ -80,13 +82,16 @@ output/
 
 ## Example Profiles
 
-Three working examples are included:
+Six 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/nws_connect_profile.yaml`](examples/nws_connect_profile.yaml) | PubSub profile — generates `asyncapi.yaml` alongside the OpenAPI |
 | [`examples/nwsviz_profile.yaml`](examples/nwsviz_profile.yaml) | Production profile — 13 collections, 3 OGC API Processes, PDF metadata |
+| [`examples/nwp_radar.yaml`](examples/nwp_radar.yaml) | **DGIWG-branded** profile — custom cover logo, DGIWG colours/footer/legal page, `default_output_format`, per-query CRS, vertical `positive`, DGIWG namespace |
+| [`examples/nwp_earth_observations_lightning_profile.yaml`](examples/nwp_earth_observations_lightning_profile.yaml) | DGIWG lightning profile — same branding, CF units |
 
 ---
 
@@ -115,6 +120,8 @@ Add `--pdf` to also compile an OGC-compliant PDF via the `metanorma/metanorma` D
 oapi-profile-builder generate --config my_profile.yaml --output ./output --pdf
 ```
 
+The PDF can be rebranded for another SDO (e.g. DGIWG) — custom cover logo, colours, legal page, footer, and identifier namespace — all from the profile config. See [Document generation and branding](#document-generation-and-branding).
+
 ### `validate`
 
 Validates the config without writing any files. Useful in CI before generating.
@@ -219,6 +226,29 @@ jobs:
 
 ---
 
+## Document generation and branding
+
+With `--pdf`, the builder compiles a Metanorma document (`document.adoc` + `sections/`, `requirements/`, `abstract_tests/`) into `document.pdf` using the official `metanorma/metanorma` Docker image. By default this is an OGC `draft-standard` document.
+
+Everything about the document — cover, title-page metadata, legal page, footer, colours, and even the requirement/conformance identifier namespace — is driven from the profile config, so the same tooling can produce a document branded for another SDO such as **DGIWG** with no OGC branding remaining.
+
+| What you want to change | Field | Mechanism |
+|---|---|---|
+| Cover logo + tagline (replaces the OGC cover) | `document_metadata.cover` | Generated cover image via `:coverpage-image:` full replacement |
+| Title, doc number, edition, dates, sub-title/status | `title`, `version`, `document_metadata.{doc_number, doc_type, doc_subtype, status, *_date}` | Metanorma document attributes |
+| PDF colours (titles, tables, cover, backgrounds) | `document_metadata.colors` | `:presentation-metadata-color-*:` |
+| Page-ii legal text (copyright / license / notice) | `document_metadata.boilerplate` | `:boilerplate-authority:` |
+| Footer organisation name | `document_metadata.copyright_holder` | `:copyright-holder:` |
+| Remove the OGC logo from the legal page | `document_metadata.suppress_flavor_logo` | targeted `:pdf-stylesheet-override:` |
+| Requirement / conformance identifier namespace | `spec_uri_base` | derives `req_uri` / `conf_uri` |
+| Submitter table, notice paragraph, normative refs | `document_metadata.{submitters, notice, normative_references}` | Metanorma attributes / sections |
+
+Custom branding requires Pillow for the cover image: `pip install 'oapi-profile-builder[pdf]'`. Field-by-field detail is in the [`document_metadata`](#document_metadata) reference below; [`examples/nwp_radar.yaml`](examples/nwp_radar.yaml) is a complete DGIWG-branded example.
+
+> The `suppress_flavor_logo` override reaches into the OGC Metanorma flavor's XSL (template `insertLogoPreface`) and is coupled to that flavor. Everything else uses documented Metanorma attributes. For long-term SDO adoption, a dedicated Metanorma "taste"/flavor is the most durable path.
+
+---
+
 ## Profile Config Reference
 
 A profile config is a YAML file. The full JSON Schema is at [`profile.schema.json`](profile.schema.json).
@@ -290,12 +320,18 @@ abstract_tests: []
 | `description` | string | no | Human-readable description of the service profile. Surfaces in the OpenAPI `info.description` and the landing page response schema |
 | `keywords` | list | no | Service-level keywords (e.g. query types, parameter names, domain terms). Surfaces in `info.x-keywords` and the landing page response schema. Distinct from `document_metadata.keywords`, which are for the OGC PDF header |
 | `server_url` | string | no | Documentation only — not written to the profile OpenAPI |
+| `provider` | object | no | Service provider / responsible party. Surfaces in OpenAPI `info.contact` and the document Point of Contact (see below) |
+| `classification` | object | no | Security classification (`level` + `system`). Surfaces as a document banner and `info.x-classification` |
+| `metadata_date` | string | no | Metadata update date (ISO 8601). Surfaces as `info.x-metadata-date` |
+| `resource_service_publish_date` | string | no | Resource/service publication date (ISO 8601). Surfaces as `info.x-resource-publish-date` |
+| `resource_default_locale` | string | no | Default resource locale (e.g. `eng`). Surfaces as `info.x-default-locale` |
 | `allow_post_queries` | bool | no | When `true`, generates `POST` alongside `GET` for all EDR data query endpoints. Defaults to `false` |
 | `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 |
+| `spec_uri_base` | string | no | Base URI for the requirements/conformance class identifiers. Defaults to the OGC EDR Part 3 namespace; override to publish under another SDO namespace (e.g. DGIWG) |
 | `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 |
@@ -303,7 +339,7 @@ abstract_tests: []
 | `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) |
+| `document_metadata` | object | no | Metanorma PDF header — doc number/type/subtype, status, editors, submitters, dates, notice, normative references (see below) |
 
 ---
 
@@ -360,6 +396,22 @@ data_queries:
         crs_details:
           - crs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
           - crs: "http://www.opengis.net/def/crs/EPSG/0/4326"
+  cube:
+    link:
+      href: https://example.com/collections/obs/cube
+      rel: data
+      variables:
+        query_type: cube
+        output_formats: [CoverageJSON, GeoTIFF]
+        # default_output_format: response format used when the `f` query
+        # parameter is omitted. Must be one of output_formats. Sets the
+        # `default` on the generated OpenAPI `f` parameter for this query.
+        default_output_format: GeoTIFF
+        # crs: shorthand for crs_details — a plain list of CRS URIs.
+        # Validated against extent_requirements.supported_crs.
+        crs:
+          - "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
+          - "http://www.opengis.net/def/crs/EPSG/0/4326"
 ```
 
 #### `parameter_names` example
@@ -423,6 +475,61 @@ extent_requirements:
 
 At least one of `extent_crs` or `supported_crs` is required. The same applies to TRS and VRS — all are optional individually but at least one CRS constraint must be present.
 
+#### Vertical direction (`positive`)
+
+OGC API - EDR's vertical extent has no field for which way values increase. This is ambiguous for VRS like pressure levels, which different providers order top-to-bottom or bottom-to-top inconsistently (pressure increases as altitude *decreases*). Set `extent.vertical.positive` to `up` or `down` on a collection (following the CF Conventions `positive` attribute) to make the ordering explicit:
+
+```yaml
+collections:
+  - id: my_collection
+    extent:
+      spatial: { ... }
+      vertical:
+        interval:
+          - ["1000", "100"]   # hPa, surface to top of atmosphere
+        values: ["1000", "850", "700", "500", "300", "100"]
+        vrs: "http://www.opengis.net/def/crs/EPSG/0/5798"  # or similar pressure VRS
+        positive: down   # pressure increases downward, toward the surface
+```
+
+Set `extent_requirements.require_vertical_direction: true` to make `positive` mandatory on every collection with a vertical extent, so a profile can enforce one consistent convention rather than leaving it up to each collection author:
+
+```yaml
+extent_requirements:
+  minimum_bbox: [-180, -90, 180, 90]
+  extent_crs:
+    allowed: ["http://www.opengis.net/def/crs/OGC/1.3/CRS84"]
+  require_vertical_direction: true
+```
+
+---
+
+### `output_formats`
+
+Maps format names (referenced by `collections[].output_formats` and `data_queries.*.variables.output_formats`) to a media type and, optionally, a schema reference. The `schema_ref` flows into the generated OpenAPI response `content` for that format — use it to point a format at a specific schema (e.g. a DGIWG-published schema for GeoTIFF or CoverageJSON) instead of the tool's built-in default.
+
+```yaml
+output_formats:
+  - name: CoverageJSON
+    media_type: application/prs.coverage+json
+    schema_ref: https://schemas.opengis.net/covjson/1.0/coveragejson.json
+  - name: GeoJSON
+    media_type: application/geo+json
+    schema_ref: https://geojson.org/schema/FeatureCollection.json
+  - name: GeoTIFF
+    media_type: image/tiff; application=geotiff
+    # Omit schema_ref until a published schema exists for this format —
+    # the requirement/abstract test can still state the standard to conform to.
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | yes | Format name, referenced elsewhere as a string (e.g. `CoverageJSON`) |
+| `media_type` | yes | MIME type used as the OpenAPI response `content` key and the `f` parameter value |
+| `schema_ref` | no | URL to a JSON Schema (or other schema) for this format. When set, the generated response uses `{"$ref": schema_ref}`; when omitted, a generic/default schema is used |
+
+`schema_ref` is optional — if no schema exists yet for a format (as is currently the case for some binary formats like GeoTIFF), leave it unset and capture the required standard as a normative `requirements[]` entry instead. Add `schema_ref` later once a schema URL exists.
+
 ---
 
 ### `parameter_schema`
@@ -536,16 +643,39 @@ pubsub:
 
 ### `document_metadata`
 
-Required only when compiling a PDF with `--pdf`.
+Required only when compiling a PDF with `--pdf`. Fields map to Metanorma OGC document attributes.
 
 ```yaml
 document_metadata:
   doc_number: "25-myprofile"
-  doc_subtype: implementation   # implementation | best-practice | engineering-report
+  doc_type: draft-standard      # Metanorma :doctype: (draft-standard | standard | best-practice | engineering-report | ...)
+  doc_subtype: implementation   # implementation | best-practice | engineering-report | profile
+  status: approved              # Metanorma :status:/:docstage: (swg-draft | public-rfc | approved | ...)
   editors:
     - Jane Smith
+  # submitters: structured table for page iv — each row carries its own affiliation.
+  # When provided, takes precedence over the editors/submitting_orgs fallback.
+  submitters:
+    - name: Jane Smith
+      affiliation: My Organization
+      role: editor
+    - name: Standards Working Group
+      affiliation: My SDO
   submitting_orgs:
     - My Organization
+  # Title-page dates (YYYY-MM-DD). Omitted dates fall back to {copyright_year}-01-01.
+  submission_date: "2026-05-01"   # → :received-date:
+  approval_date:   "2026-06-15"   # → :issued-date:
+  publication_date: "2026-07-01"  # → :published-date:
+  # Custom notice paragraph rendered in the front matter. Note: the OGC cover-page
+  # legal notice itself is generated by Metanorma from doc_type/status.
+  notice: >
+    This is a DRAFT standard and is subject to change.
+  # Additional normative references appended to the References section.
+  normative_references:
+    - anchor: DGIWG-250
+      citation: DGIWG 250
+      title: DGIWG GeoTIFF Profile
   keywords:
     - ogcdoc
     - OGC API
@@ -554,6 +684,113 @@ document_metadata:
   external_id: http://www.opengis.net/doc/dp/my-profile/1.0
 ```
 
+The cover-page sub-title (e.g. "Draft Standard — Implementation — Approved") is produced by Metanorma from the `doc_type`, `doc_subtype`, and `status` combination.
+
+#### Custom branding (logo + colors)
+
+Two `document_metadata` blocks let you rebrand the PDF (e.g. for DGIWG) without a custom Metanorma flavor:
+
+- **`colors`** — recolours the PDF via Metanorma's `:presentation-metadata-color-*:` attributes. Values are hex colours.
+- **`cover`** — replaces the built-in OGC cover page with a generated one: your logo plus the document's title, number, edition and date. Requires Pillow (`pip install 'oapi-profile-builder[pdf]'`). The builder renders `cover.png` into the output directory and points Metanorma at it via `:coverpage-image:` + `:presentation-metadata-full-coverpage-replacement:`.
+
+```yaml
+document_metadata:
+  doc_number: "DGIWG 134"
+  cover:
+    logo: assets/dgiwg_logo.png    # path relative to the working directory (or absolute)
+    tagline: Delivering Military Advantage through multi-national geospatial interoperability
+    background: "#FFFFFF"          # optional cover background (default white)
+    text_color: "#1F3864"          # optional cover text colour (default black)
+  colors:
+    text: "#000000"                # body text
+    cover_text: "#1F3864"          # cover text / section numbers / ToC
+    cover_lines: "#1F3864"         # preface 'crossing lines' element
+    title: "#1F3864"               # clause/table/figure titles
+    page_background: "#FFFFFF"     # cover + section page background
+    table_header: "#1F3864"        # table header background
+    table_row_even: "#EEF1F7"      # even table rows
+    table_row_odd: "#FFFFFF"       # odd table rows
+```
+
+Note: colours work against the normal OGC cover too. The `cover` block does a *full* cover replacement, so the dynamic title/number/edition/date are drawn onto the generated image (which is why the builder composes it rather than relying on Metanorma attributes — logo attributes like `:coverpage-image:` alone are not rendered by the OGC flavor).
+
+#### De-branding the rest of the document (legal page + footer + logo)
+
+Cover + colors handle the front page, but the OGC flavor also stamps its identity on the page-ii legal boilerplate, the page footer, and an OGC logo on the legal page. Three more `document_metadata` fields remove those:
+
+- **`copyright_holder`** — sets `:copyright-holder:`, which also drives the **PDF footer** organisation name (replacing "OPEN GEOSPATIAL CONSORTIUM").
+- **`boilerplate`** — replaces the page-ii legal text (copyright / license / legal notice / feedback) via `:boilerplate-authority:`. Any field left unset is synthesised from `copyright_holder`, so no OGC text leaks through.
+- **`suppress_flavor_logo`** — removes the OGC logo from the preface/legal page via a targeted PDF-stylesheet override. (Coupled to the OGC Metanorma flavor's XSL.)
+
+```yaml
+document_metadata:
+  copyright_holder: DGIWG
+  suppress_flavor_logo: true
+  boilerplate:
+    copyright: "Copyright © 2026 Defence Geospatial Information Working Group (DGIWG). All rights reserved."
+    license: "Use of this document is subject to the DGIWG terms and conditions."
+    legal: "Attention is drawn to the possibility that some elements may be subject to patent rights; DGIWG shall not be held responsible for identifying any such rights."
+    feedback: "Comments on this document should be directed to DGIWG."
+```
+
+With `cover` + `colors` + `copyright_holder` + `boilerplate` + `suppress_flavor_logo` (and `spec_uri_base` for the requirement/conformance identifiers), the generated PDF carries no OGC branding — only legitimate citations to the OGC standards the profile conforms to. See [`examples/nwp_radar.yaml`](examples/nwp_radar.yaml).
+
+---
+
+### `provider`, `classification`, and provenance metadata
+
+Optional service-level metadata. Each may also be set per-collection (the collection value overrides the profile root for that collection and is round-tripped into `profile_config.json`).
+
+```yaml
+provider:
+  name: Austrian Military
+  url: "https://www.bmlv.gv.at/english/forces/organisation.shtml"
+  contact:
+    email: presse@bmlvs.gv.at
+    phone: "+43 ..."
+    hours: Monday to Friday 08:00 - 17:00
+    instructions: During hours of Service
+    address: "Ministry of Defence, Rossauer Lände 1"
+    postalcode: A-1090
+    city: Vienna
+    country: Austria
+
+classification:
+  level: "NATO RESTRICTED (NR)"
+  system: NATO
+
+metadata_date: "2026-06-25T07:31Z"
+resource_service_publish_date: "2026-06-24T14:10Z"
+resource_default_locale: eng
+```
+
+Where these surface:
+
+- `provider` → OpenAPI `info.contact` (`name`/`url`/`email`; the remaining contact fields become `x-` extensions) and a **Point of Contact** section in the generated document.
+- `classification` → a **security classification banner** in the document Abstract and `info.x-classification` in the OpenAPI.
+- `metadata_date` / `resource_service_publish_date` / `resource_default_locale` → `info.x-metadata-date` / `info.x-resource-publish-date` / `info.x-default-locale`.
+
+> The profile OpenAPI is implementation-independent (per EDR Part 3 REQ_publishing), so these describe the profile/data provenance rather than a specific deployment endpoint.
+
+---
+
+### `spec_uri_base`
+
+By default, the requirements class and conformance class identifiers are published under the OGC API - EDR Part 3 namespace:
+
+```
+http://www.opengis.net/spec/ogcapi-edr-3/1.0/req/<name>
+http://www.opengis.net/spec/ogcapi-edr-3/1.0/conf/<name>
+```
+
+Set `spec_uri_base` to publish under a different SDO namespace. This updates the OpenAPI `x-ogc-profile` link, the requirements/conformance AsciiDoc identifiers, and the conformance section:
+
+```yaml
+spec_uri_base: "https://schemas.dgiwg.org/edr/1.0"
+# → https://schemas.dgiwg.org/edr/1.0/req/<name>
+# → https://schemas.dgiwg.org/edr/1.0/conf/<name>
+```
+
 ---
 
 ## Validation Rules
@@ -564,10 +801,13 @@ The tool enforces these rules at build time. Violations produce clear error mess
 |---|---|
 | `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 |
+| `extent_requirements` requires CRS spec | At least one of `extent_crs` or `supported_crs` must be set (each uses `allowed` or `pattern`) |
+| Collection CRS validated | Each `extent.spatial.crs` checked against `extent_crs`; `crs[]` and `crs_details` checked against `supported_crs` |
+| Collection TRS validated | Each `extent.temporal.trs` checked against `extent_trs` |
+| `crs_details` / `crs` validated | Each `data_queries.*.variables.crs_details[].crs` and `crs[]` checked against `supported_crs` |
+| `default_output_format` validated | Each `data_queries.*.variables.default_output_format` must be one of that query's `output_formats` |
+| `require_vertical_direction` enforced | If set, every collection with a vertical extent must declare `extent.vertical.positive` as `up` or `down` |
+| Document dates format | `submission_date` / `approval_date` / `publication_date` must be `YYYY-MM-DD` |
 | 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 |