ogcapi-registry 0.1.0__tar.gz

ogcapi_registry-0.1.0/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.3
+Name: ogcapi-registry
+Version: 0.1.0
+Summary: Add your description here
+Author: Claude, Francesco Bartoli
+Author-email: Claude <noreply@anthropic.com>, Francesco Bartoli <xbartolone@gmail.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: openapi-pydantic>=0.5.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# OGC API Registry Validator
+
+A Python library for validating OpenAPI documents published by OGC API servers against OGC specification requirements.
+
+## Why This Library?
+
+OGC API standards (Features, Tiles, Processes, Records, etc.) define specific requirements for the OpenAPI documents that servers must publish. These requirements include:
+
+- **Required endpoints** (e.g., `/collections`, `/conformance`)
+- **Required HTTP operations** (GET, POST, etc.)
+- **Conformance class declarations**
+- **Response schemas and content types**
+
+This library performs **static validation** of these OpenAPI documents, helping you verify that your OGC API server's published specification meets the standard requirements before deployment.
+
+## Features
+
+- **OGC API Validation**: Validate against OGC API - Features, Tiles, Processes, Records, Coverages, EDR, Maps, Styles, Routes
+- **Conformance-Based Detection**: Automatically detect API type from conformance classes
+- **Error Severity Levels**: Distinguish between critical errors, warnings, and informational messages
+- **Extensible Strategy Pattern**: Add custom validation strategies for new specifications
+- **Async Support**: Full async/await support for high-performance validation
+
+## Installation
+
+```bash
+pip install ogcapi-registry
+```
+
+Or with uv:
+
+```bash
+uv add ogcapi-registry
+```
+
+## Quick Start
+
+### Validating an OGC API Server
+
+```python
+from ogcapi_registry import (
+    OpenAPIClient,
+    validate_ogc_api,
+    parse_conformance_classes,
+)
+
+# Fetch the OpenAPI document from your server
+client = OpenAPIClient()
+openapi_doc, metadata = client.fetch("https://demo.pygeoapi.io/master/openapi")
+
+# Parse conformance classes (usually from /conformance endpoint)
+conformance_uris = [
+    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
+    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson",
+    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
+]
+conformance_classes = parse_conformance_classes(conformance_uris)
+
+# Validate against OGC API requirements
+result = validate_ogc_api(openapi_doc, conformance_classes)
+
+if result.is_valid:
+    print("OpenAPI document is fully compliant!")
+else:
+    # Check error severity
+    for error in result.critical_errors:
+        print(f"CRITICAL: {error['message']}")
+
+    for warning in result.warnings:
+        print(f"WARNING: {warning['message']}")
+```
+
+### Understanding Error Severity
+
+The library classifies validation errors by severity:
+
+```python
+from ogcapi_registry import ErrorSeverity
+
+# Critical errors: Must be fixed for OGC compliance
+result.critical_errors  # Missing required endpoints, wrong HTTP methods
+
+# Warnings: Should be fixed but API may still function
+result.warnings  # Missing recommended features like CRS support
+
+# Info: Optional improvements
+result.info_errors  # Missing optional features like filtering
+
+# Check if API is compliant (no critical errors)
+if result.is_compliant:
+    print("API meets minimum OGC requirements")
+```
+
+### Automatic API Type Detection
+
+```python
+from ogcapi_registry import detect_api_types, get_primary_api_type
+
+# Detect all API types from conformance classes
+api_types = detect_api_types(conformance_classes)
+# e.g., {OGCAPIType.FEATURES, OGCAPIType.TILES}
+
+# Get the primary (most specific) API type
+primary = get_primary_api_type(conformance_classes)
+# e.g., OGCAPIType.FEATURES
+```
+
+## Application Example: CI/CD Validation
+
+Integrate OGC API validation into your deployment pipeline to catch specification errors before they reach production:
+
+```python
+#!/usr/bin/env python
+"""validate_ogc_server.py - CI/CD validation script"""
+
+import sys
+import httpx
+from ogcapi_registry import (
+    OpenAPIClient,
+    validate_ogc_api,
+    parse_conformance_classes,
+)
+
+
+def validate_server(base_url: str) -> bool:
+    """Validate an OGC API server's OpenAPI document."""
+
+    # 1. Fetch conformance classes
+    response = httpx.get(f"{base_url}/conformance")
+    response.raise_for_status()
+    conformance_uris = response.json().get("conformsTo", [])
+
+    if not conformance_uris:
+        print("ERROR: No conformance classes declared")
+        return False
+
+    conformance_classes = parse_conformance_classes(conformance_uris)
+    print(f"Found {len(conformance_classes)} conformance classes")
+
+    # 2. Fetch and validate OpenAPI document
+    client = OpenAPIClient()
+    openapi_doc, metadata = client.fetch(f"{base_url}/openapi")
+
+    print(f"Validating OpenAPI {openapi_doc.get('openapi', 'unknown')}")
+
+    # 3. Run OGC API validation
+    result = validate_ogc_api(openapi_doc, conformance_classes)
+
+    # 4. Report results
+    print(f"\n{'='*50}")
+    print(f"Validation Result: {'PASSED' if result.is_valid else 'FAILED'}")
+    print(f"{'='*50}")
+
+    if result.critical_errors:
+        print(f"\nCritical Errors ({len(result.critical_errors)}):")
+        for err in result.critical_errors:
+            print(f"  - {err['path']}: {err['message']}")
+
+    if result.warnings:
+        print(f"\nWarnings ({len(result.warnings)}):")
+        for warn in result.warnings:
+            print(f"  - {warn['path']}: {warn['message']}")
+
+    summary = result.get_summary()
+    print(f"\nSummary: {summary['critical']} critical, "
+          f"{summary['warning']} warnings, {summary['info']} info")
+
+    # Return True only if no critical errors
+    return result.is_compliant
+
+
+if __name__ == "__main__":
+    server_url = sys.argv[1] if len(sys.argv) > 1 else "https://demo.pygeoapi.io/master"
+
+    success = validate_server(server_url)
+    sys.exit(0 if success else 1)
+```
+
+Use in GitHub Actions:
+
+```yaml
+- name: Validate OGC API Compliance
+  run: python validate_ogc_server.py ${{ env.SERVER_URL }}
+```
+
+## Supported OGC API Standards
+
+| Standard | Strategy Class | Key Validations |
+|----------|---------------|-----------------|
+| OGC API - Common | `CommonStrategy` | Landing page, conformance, API definition |
+| OGC API - Features | `FeaturesStrategy` | Collections, items, bbox, CRS |
+| OGC API - Tiles | `TilesStrategy` | Tile matrix sets, tile endpoints |
+| OGC API - Processes | `ProcessesStrategy` | Process list, execution, jobs |
+| OGC API - Records | `RecordsStrategy` | Catalog, record queries |
+| OGC API - Coverages | `CoveragesStrategy` | Coverage data access |
+| OGC API - EDR | `EDRStrategy` | Environmental data queries |
+| OGC API - Maps | `MapsStrategy` | Map rendering endpoints |
+| OGC API - Styles | `StylesStrategy` | Style management |
+| OGC API - Routes | `RoutesStrategy` | Routing endpoints |
+
+## Advanced Usage
+
+### Custom Validation Strategy
+
+```python
+from ogcapi_registry import ValidationStrategy, OGCAPIType, ValidationResult
+
+class MyCustomStrategy(ValidationStrategy):
+    """Custom validation for organization-specific requirements."""
+
+    api_type = OGCAPIType.FEATURES
+
+    def validate(self, document, conformance_classes):
+        errors = []
+
+        # Add custom validation logic
+        if "/health" not in document.get("paths", {}):
+            errors.append({
+                "path": "paths",
+                "message": "Missing /health endpoint (org requirement)",
+                "severity": "warning",
+            })
+
+        return ValidationResult.success() if not errors else ValidationResult.failure(errors)
+```
+
+### Async Validation
+
+```python
+import asyncio
+from ogcapi_registry import AsyncOpenAPIClient, validate_ogc_api
+
+async def validate_multiple_servers(urls: list[str]):
+    client = AsyncOpenAPIClient()
+
+    async def validate_one(url):
+        doc, _ = await client.fetch(f"{url}/openapi")
+        # ... fetch conformance and validate
+        return url, result
+
+    results = await asyncio.gather(*[validate_one(url) for url in urls])
+    return dict(results)
+```
+
+## Documentation
+
+Full documentation: [https://francbartoli.github.io/ogcapi-registry/](https://francbartoli.github.io/ogcapi-registry/)
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/francbartoli/ogcapi-registry.git
+cd ogcapi-registry
+uv sync --all-extras --dev
+
+# Run tests
+uv run pytest -v
+
+# Run linting
+uv run ruff check src/ tests/
+uv run mypy src/ogcapi_registry
+```
+
+## License
+
+MIT

ogcapi_registry-0.1.0/README.md

@@ -0,0 +1,267 @@
+# OGC API Registry Validator
+
+A Python library for validating OpenAPI documents published by OGC API servers against OGC specification requirements.
+
+## Why This Library?
+
+OGC API standards (Features, Tiles, Processes, Records, etc.) define specific requirements for the OpenAPI documents that servers must publish. These requirements include:
+
+- **Required endpoints** (e.g., `/collections`, `/conformance`)
+- **Required HTTP operations** (GET, POST, etc.)
+- **Conformance class declarations**
+- **Response schemas and content types**
+
+This library performs **static validation** of these OpenAPI documents, helping you verify that your OGC API server's published specification meets the standard requirements before deployment.
+
+## Features
+
+- **OGC API Validation**: Validate against OGC API - Features, Tiles, Processes, Records, Coverages, EDR, Maps, Styles, Routes
+- **Conformance-Based Detection**: Automatically detect API type from conformance classes
+- **Error Severity Levels**: Distinguish between critical errors, warnings, and informational messages
+- **Extensible Strategy Pattern**: Add custom validation strategies for new specifications
+- **Async Support**: Full async/await support for high-performance validation
+
+## Installation
+
+```bash
+pip install ogcapi-registry
+```
+
+Or with uv:
+
+```bash
+uv add ogcapi-registry
+```
+
+## Quick Start
+
+### Validating an OGC API Server
+
+```python
+from ogcapi_registry import (
+    OpenAPIClient,
+    validate_ogc_api,
+    parse_conformance_classes,
+)
+
+# Fetch the OpenAPI document from your server
+client = OpenAPIClient()
+openapi_doc, metadata = client.fetch("https://demo.pygeoapi.io/master/openapi")
+
+# Parse conformance classes (usually from /conformance endpoint)
+conformance_uris = [
+    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
+    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson",
+    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
+]
+conformance_classes = parse_conformance_classes(conformance_uris)
+
+# Validate against OGC API requirements
+result = validate_ogc_api(openapi_doc, conformance_classes)
+
+if result.is_valid:
+    print("OpenAPI document is fully compliant!")
+else:
+    # Check error severity
+    for error in result.critical_errors:
+        print(f"CRITICAL: {error['message']}")
+
+    for warning in result.warnings:
+        print(f"WARNING: {warning['message']}")
+```
+
+### Understanding Error Severity
+
+The library classifies validation errors by severity:
+
+```python
+from ogcapi_registry import ErrorSeverity
+
+# Critical errors: Must be fixed for OGC compliance
+result.critical_errors  # Missing required endpoints, wrong HTTP methods
+
+# Warnings: Should be fixed but API may still function
+result.warnings  # Missing recommended features like CRS support
+
+# Info: Optional improvements
+result.info_errors  # Missing optional features like filtering
+
+# Check if API is compliant (no critical errors)
+if result.is_compliant:
+    print("API meets minimum OGC requirements")
+```
+
+### Automatic API Type Detection
+
+```python
+from ogcapi_registry import detect_api_types, get_primary_api_type
+
+# Detect all API types from conformance classes
+api_types = detect_api_types(conformance_classes)
+# e.g., {OGCAPIType.FEATURES, OGCAPIType.TILES}
+
+# Get the primary (most specific) API type
+primary = get_primary_api_type(conformance_classes)
+# e.g., OGCAPIType.FEATURES
+```
+
+## Application Example: CI/CD Validation
+
+Integrate OGC API validation into your deployment pipeline to catch specification errors before they reach production:
+
+```python
+#!/usr/bin/env python
+"""validate_ogc_server.py - CI/CD validation script"""
+
+import sys
+import httpx
+from ogcapi_registry import (
+    OpenAPIClient,
+    validate_ogc_api,
+    parse_conformance_classes,
+)
+
+
+def validate_server(base_url: str) -> bool:
+    """Validate an OGC API server's OpenAPI document."""
+
+    # 1. Fetch conformance classes
+    response = httpx.get(f"{base_url}/conformance")
+    response.raise_for_status()
+    conformance_uris = response.json().get("conformsTo", [])
+
+    if not conformance_uris:
+        print("ERROR: No conformance classes declared")
+        return False
+
+    conformance_classes = parse_conformance_classes(conformance_uris)
+    print(f"Found {len(conformance_classes)} conformance classes")
+
+    # 2. Fetch and validate OpenAPI document
+    client = OpenAPIClient()
+    openapi_doc, metadata = client.fetch(f"{base_url}/openapi")
+
+    print(f"Validating OpenAPI {openapi_doc.get('openapi', 'unknown')}")
+
+    # 3. Run OGC API validation
+    result = validate_ogc_api(openapi_doc, conformance_classes)
+
+    # 4. Report results
+    print(f"\n{'='*50}")
+    print(f"Validation Result: {'PASSED' if result.is_valid else 'FAILED'}")
+    print(f"{'='*50}")
+
+    if result.critical_errors:
+        print(f"\nCritical Errors ({len(result.critical_errors)}):")
+        for err in result.critical_errors:
+            print(f"  - {err['path']}: {err['message']}")
+
+    if result.warnings:
+        print(f"\nWarnings ({len(result.warnings)}):")
+        for warn in result.warnings:
+            print(f"  - {warn['path']}: {warn['message']}")
+
+    summary = result.get_summary()
+    print(f"\nSummary: {summary['critical']} critical, "
+          f"{summary['warning']} warnings, {summary['info']} info")
+
+    # Return True only if no critical errors
+    return result.is_compliant
+
+
+if __name__ == "__main__":
+    server_url = sys.argv[1] if len(sys.argv) > 1 else "https://demo.pygeoapi.io/master"
+
+    success = validate_server(server_url)
+    sys.exit(0 if success else 1)
+```
+
+Use in GitHub Actions:
+
+```yaml
+- name: Validate OGC API Compliance
+  run: python validate_ogc_server.py ${{ env.SERVER_URL }}
+```
+
+## Supported OGC API Standards
+
+| Standard | Strategy Class | Key Validations |
+|----------|---------------|-----------------|
+| OGC API - Common | `CommonStrategy` | Landing page, conformance, API definition |
+| OGC API - Features | `FeaturesStrategy` | Collections, items, bbox, CRS |
+| OGC API - Tiles | `TilesStrategy` | Tile matrix sets, tile endpoints |
+| OGC API - Processes | `ProcessesStrategy` | Process list, execution, jobs |
+| OGC API - Records | `RecordsStrategy` | Catalog, record queries |
+| OGC API - Coverages | `CoveragesStrategy` | Coverage data access |
+| OGC API - EDR | `EDRStrategy` | Environmental data queries |
+| OGC API - Maps | `MapsStrategy` | Map rendering endpoints |
+| OGC API - Styles | `StylesStrategy` | Style management |
+| OGC API - Routes | `RoutesStrategy` | Routing endpoints |
+
+## Advanced Usage
+
+### Custom Validation Strategy
+
+```python
+from ogcapi_registry import ValidationStrategy, OGCAPIType, ValidationResult
+
+class MyCustomStrategy(ValidationStrategy):
+    """Custom validation for organization-specific requirements."""
+
+    api_type = OGCAPIType.FEATURES
+
+    def validate(self, document, conformance_classes):
+        errors = []
+
+        # Add custom validation logic
+        if "/health" not in document.get("paths", {}):
+            errors.append({
+                "path": "paths",
+                "message": "Missing /health endpoint (org requirement)",
+                "severity": "warning",
+            })
+
+        return ValidationResult.success() if not errors else ValidationResult.failure(errors)
+```
+
+### Async Validation
+
+```python
+import asyncio
+from ogcapi_registry import AsyncOpenAPIClient, validate_ogc_api
+
+async def validate_multiple_servers(urls: list[str]):
+    client = AsyncOpenAPIClient()
+
+    async def validate_one(url):
+        doc, _ = await client.fetch(f"{url}/openapi")
+        # ... fetch conformance and validate
+        return url, result
+
+    results = await asyncio.gather(*[validate_one(url) for url in urls])
+    return dict(results)
+```
+
+## Documentation
+
+Full documentation: [https://francbartoli.github.io/ogcapi-registry/](https://francbartoli.github.io/ogcapi-registry/)
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/francbartoli/ogcapi-registry.git
+cd ogcapi-registry
+uv sync --all-extras --dev
+
+# Run tests
+uv run pytest -v
+
+# Run linting
+uv run ruff check src/ tests/
+uv run mypy src/ogcapi_registry
+```
+
+## License
+
+MIT

ogcapi_registry-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "ogcapi-registry"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Claude", email = "noreply@anthropic.com" },
+    { name = "Francesco Bartoli", email = "xbartolone@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28.1",
+    "openapi-pydantic>=0.5.1",
+    "pydantic>=2.12.5",
+    "pyyaml>=6.0.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.17,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.0",
+    "mypy>=1.19.0",
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=6.0.0",
+    "pytest-httpx>=0.36.0",
+    "ruff>=0.14.8",
+    "types-pyyaml>=6.0.12.20250915",
+]
+
+[tool.mypy]
+python_version = "3.11"
+warn_unused_ignores = true
+plugins = ["pydantic.mypy"]
+# Ignore missing imports for packages without type stubs
+ignore_missing_imports = true
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true