xpublish-ogc-core 0.1.2

OGC API Common structure and support for OGC Xpublish plugins

XPublish OGC Core

Enable Xpublish plugins that support various OGC standards to serve via fully OGC compliant routes.

This works by creating an app_router that restructures the Xpublish API around OGC API - Common conventions, and registering new hookspecs that other OGC plugins (for example xpublish-edr) implement to contribute their conformance classes, collection metadata, and data queries.

Endpoints

Path	Description
/	Landing page with self, service-desc (/openapi.json), service-doc (/docs), conformance, and data links (including the http://www.opengis.net/def/rel/ogc/1.0/... link relations)
/conformance	OGC API - Common conformance classes, plus every class declared by plugins via the ogc_conformance_classes hook
/collections	One collection per published dataset, built from dataset attributes plus plugin contributions
/collections/{collection_id}	A single collection, with data_queries aggregated from the ogc_collection_dataqueries hook. Unknown ids return an OGC exception shaped 404

If xpublish-ogc-core is installed it is loaded automatically through the xpublish.plugin entry point. The landing page title and description are configurable on the plugin, by instantiating it explicitly (note that passing plugins to xpublish.Rest disables entry point auto-loading, so list every plugin you want):

import xpublish
from xpublish_edr import CfEdrPlugin
from xpublish_ogc_core import OgcCorePlugin

rest = xpublish.Rest(
    datasets,
    plugins={
        "ogc-core": OgcCorePlugin(title="My data server", description="..."),
        "edr": CfEdrPlugin(),
    },
)

Hookspecs

Other OGC plugins implement these hookspecs (declared on OgcPluginSpec):

• ogc_router(deps) — return an APIRouter mounted at the application root, for OGC routes like /collections/{collection_id}/position.
• ogc_conformance_classes() — return a list of conformance class URIs (http://www.opengis.net/spec/...) to aggregate into /conformance.
• ogc_collection_metadata(collection_id, ds, deps) — return a dict of collection members (extent, parameter_names, crs, output_formats, ...) merged into the collection objects served at /collections and /collections/{collection_id}.
• ogc_collection_dataqueries(collection_id, ds, deps) — return a dict of data query descriptions (position, area, cube, ...) merged into the collection's data_queries.

Schema-driven development

Development on this plugin, and for other OGC plugins is driven by the official OGC schemas and test suites:

• The official OGC schemas are vendored under src/xpublish_ogc_core/schemas/ so tests run offline (refresh with uv run scripts/update_schemas.py): the OGC API - Common Part 1 building blocks plus the collections shapes from OGC API - Features Part 1 (the "common" document, which core's own responses validate against), and the bundled OpenAPI documents published by the OGC API - EDR and OGC API - Tiles standards for the plugins implementing them.

• xpublish_ogc_core.testing is shipped with the package so downstream plugins can validate their own responses against the official component schemas (the document argument picks the schema set, defaulting to "edr"):

  from xpublish_ogc_core.testing import validate_response
  
  validate_response("landingPage", client.get("/").json(), document="common")
  validate_response("collection", client.get("/collections/air").json())
  validate_response(
      "tileSet",
      client.get("/datasets/air/tiles/WebMercatorQuad").json(),
      document="tiles",
  )
  

  Validation failures raise with the jsonschema error messages, pointing at the exact spec violation.

• Plugins are also suggested to use Schemathesis for hypothesis testing their advertised endpoints. xpublish_ogc_core.testing.bundled_schema() helps with loading the schema and then hypothesis testing against the spec. The tests can be run in coordination with those generated by the plguins themselves.

  plugin_schema = schemathesis.openapi.from_asgi("/openapi.json", build_app())
  
  
  ogc_schema = (
      testing.bundled_schema(with_app=build_app())
      .exclude(path_regex=r"^/collections/\{collectionId\}/items")
      .exclude(path_regex=r"^/collections/\{collectionId\}/instances")
      .exclude(path_regex=r"^/collections/\{collectionId\}/locations")
      .exclude(path_regex=r"^/collections/\{collectionId\}/radius")
      .exclude(path_regex=r"^/collections/\{collectionId\}/trajectory")
      .exclude(path_regex=r"^/collections/\{collectionId\}/corridor")
  )
  
  
  @schemathesis.pytest.parametrize(
      plugin=plugin_schema,
      ogc=ogc_schema,
  )
  def test_schema(case):
      # the EDR query parameters (WKT coords, comma separated bbox) are looser
      # than their OpenAPI parameter schemas can express, so 422 rejections of
      # schema-compliant inputs are expected
      case.call_and_validate(excluded_checks=[positive_data_acceptance])
  

• xpublish_ogc_core.teamengine is also shipped to help facilitate other plugins testing with the OGC CITE test suites running in Docker.

  from xpublish_ogc_core import teamengine
  
  with (
      teamengine.serve_app(rest.app) as app_url,
      teamengine.teamengine_container(
          "ogccite/ets-ogcapi-edr10:1.3-teamengine-6.0.0-RC2"
      ) as engine_url,
  ):
      result = teamengine.run_suite(
          engine_url,
          "ogcapi-edr10",
          {"iut": app_url, "apiDefinition": f"{app_url}/openapi.json"},
      )
  
  assert not result.failure_names(), result.summary()