geopython/pygeoapi

Can another program use it through a documented, machine-readable surface?

• next: [cli] L2 --help documents every option (at least 90% of options have help text). (8 of 15 options have help text)

cli ladder · level 1

• ✓ L1 Invocable non-interactively: no prompts, or prompts guarded by a TTY check or a --yes/--no-input option. no interactive prompts
• ✗ L2 --help documents every option (at least 90% of options have help text). 8 of 15 options have help text
• ✗ L3 Machine-readable output (--json/--format) and documented exit statuses. exit statuses aren't documented
• ✓ L4 The output format is specified by a JSON Schema. pygeoapi/api/__init__.py 2 matchespygeoapi/api/itemtypes.py 2 matches

service ladder · level 4

• ✓ L1 A network surface exists: HTTP routes, an MCP server, or a standard protocol listener. pygeoapi/flask_app.py fastapi/flask: 51 route declarationspygeoapi/django_/urls.py django: 30 route declarations
• ✓ L2 A contract exists: a checked-in OpenAPI/GraphQL/protobuf/AsyncAPI spec, a framework-generated spec, MCP tool schemas, or a standard application protocol that off-the-shelf clients speak (RESP, MQTT, gRPC, PostgreSQL wire, …). pygeoapi/resources/schemas/asyncapi/asyncapi-3.0.0.json asyncapi, 0 operations
• ✓ L3 A contract covers its transport: an HTTP contract covers at least 80% of declared routes (generated contracts do), or the application layer over a standard protocol (commands, topics, payloads) is specified in a protocol document or AsyncAPI. pygeoapi/resources/schemas/asyncapi/asyncapi-3.0.0.json asyncapi, 0 operations
• ✓ L4 A second surface: another transport (HTTP and a protocol, two protocols), an MCP server, a CLI with JSON output, or an SDK. pygeoapi/flask_app.py HTTPpygeoapi/asyncapi.py CLI JSON output

Can integrators rely on it not changing under them?

• next: L2 A changelog exists and marks breaking changes. (no changelog)

all ladder · level 1

• ✓ L1 Releases are versioned (semver tags or versioned changelog sections). 37 semver tags, latest 0.24.0
• ✗ L2 A changelog exists and marks breaking changes. no changelog
• ✗ L3 A deprecation mechanism is used in code (warnings, @deprecated, Deprecation/Sunset headers) or the API is versioned. no deprecation mechanism or API versioning
• ✓ L4 Across tagged releases, no OpenAPI operation, CLI option or __all__ symbol was removed without first being deprecated. 20 tagged releases compared

Can others react to state changes without polling?

• next: L2 Webhooks sent by this system, or a streaming endpoint (SSE, WebSocket). (no outbound webhooks or streams)

service ladder · level 1

• ✓ L1 Internal events exist (signals, queues, an outbox, emitters). pygeoapi/api/__init__.py 24 matchespygeoapi/api/pubsub.py 8 matches
• ✗ L2 Webhooks sent by this system, or a streaming endpoint (SSE, WebSocket). no outbound webhooks or streams
• ✗ L3 Signed webhooks registrable through the API, or two mechanisms (webhooks, streams, a broker). one delivery mechanism, or webhooks that are unsigned or not registrable through the API
• ✓ L4 Events are described by AsyncAPI or CloudEvents. pygeoapi/resources/schemas/asyncapi/asyncapi-3.0.0.jsonpygeoapi/api/pubsub.py 1 match

Can a machine act with its own revocable, least-privilege identity?

• next: L1 Programmatic authentication (bearer tokens, API keys). (no token auth)

service ladder · level 0

• ✗ L1 Programmatic authentication (bearer tokens, API keys). no token auth
• ✗ L2 Per-client, revocable credentials (managed API keys, service accounts) or OAuth2. no managed keys or OAuth
• ✓ L3 Credentials carry scopes or permissions. pygeoapi/starlette_app.py 4 matchespygeoapi/api/__init__.py 1 match
• ✗ L4 Standard provisioning or federation (OIDC client credentials, SCIM). no OIDC client credentials or SCIM

Can its data get in and out, in bulk, in open formats, with an explicit schema?

• next: L1 The data schema is explicit (migrations, DDL, schema files). (no migrations or schema files)

all ladder · level 0

• ✗ L1 The data schema is explicit (migrations, DDL, schema files). no migrations or schema files
• ✗ L2 An export exists (endpoint or command, not only the UI). no export
• ✗ L3 A bulk export in an open format, and a bulk import. no import
• ✗ L4 The export format is documented and the round trip is tested. no round-trip test

Can an automated caller use it without guessing, and recover from failure?

• next: [service] L1 Errors are machine-readable: consistent JSON over HTTP, or a standard protocol's native error replies (RESP errors, MQTT reason codes, gRPC status, SQLSTATE). (no machine-readable errors)
• next: [cli] L3 Documented exit statuses distinguish error classes, errors are JSON in JSON mode, and color is off when not a TTY. (exit statuses aren't documented)

cli ladder · level 2

• ✓ L1 Never blocks on a prompt when stdin is not a TTY. no interactive prompts
• ✓ L2 Data on stdout, diagnostics on stderr, non-zero exit on failure. pygeoapi/log.py 14 matchespygeoapi/api/__init__.py 2 matches
• ✗ L3 Documented exit statuses distinguish error classes, errors are JSON in JSON mode, and color is off when not a TTY. exit statuses aren't documented
• ✗ L4 --dry-run, limits for long or costly operations (timeouts, budgets), and agent docs. no --dry-run

service ladder · level 0

• ✗ L1 Errors are machine-readable: consistent JSON over HTTP, or a standard protocol's native error replies (RESP errors, MQTT reason codes, gRPC status, SQLSTATE). no machine-readable errors
• ✓ L2 Field-level validation errors, and paginated lists. pygeoapi/models/provider/base.py 4 matchespygeoapi/models/config.py 3 matches
• ✗ L3 Typed errors (RFC 9457 over HTTP, or a standard protocol's typed error codes), idempotent writes (Idempotency-Key), and rate-limit signals. no typed errors
• ✗ L4 Dry-run or validate-only, conditional requests, and agent docs. no dry-run

Can another system run and compose it without a human?

• next: [service] L1 Runnable from source with documented steps (a README with commands). (no documented run steps)
• next: [cli] L3 Published to a public registry and run non-interactively in CI. (not published to a registry)

cli ladder · level 2

• ✓ L1 Runnable from source (a declared entry point). setup.py console script
• ✓ L2 Installable as a package that provides the command. setup.py console script
• ✗ L3 Published to a public registry and run non-interactively in CI. not published to a registry
• ✓ L4 Also shipped as a container image or a single binary. Dockerfile

service ladder · level 0

• ✗ L1 Runnable from source with documented steps (a README with commands). no documented run steps
• ✓ L2 Configured through environment variables, documented: a .env example, a config schema, or docs naming at least half of the variables the code reads. pygeoapi/api/admin.py 2 matchespygeoapi/config.py 2 matches
• ✓ L3 A container image. Dockerfile
• ✗ L4 Composition artifacts (compose, Helm, IaC). no compose/Helm/IaC

Can behaviour be added without modifying the code?

• next: L1 Internal seams: a registry, registration function or plugin manager. (no registry or registration function)

all ladder · level 0

• ✗ L1 Internal seams: a registry, registration function or plugin manager. no registry or registration function
• ✗ L2 The docs show how to add behaviour through those seams (even in-tree). no registration functions to document
• ✓ L3 Out-of-tree extensions are discovered (entry points, a plugin directory, configuration) without editing the package. pygeoapi/__init__.py 1 match
• ✗ L4 The extension API is versioned, has lifecycle hooks, and has example extensions. no lifecycle hooks

Can an operator, or an orchestrating agent, tell whether it works and why not?

• next: [service] L1 A health or readiness endpoint, or a container healthcheck. (no health endpoint or healthcheck)
• next: [cli] L3 Structured logs (e.g. --log-format json) or a machine-readable run summary. (no structured diagnostics)

cli ladder · level 2

• ✓ L1 Meaningful exit statuses, and errors on stderr. pygeoapi/log.py 14 matchespygeoapi/api/__init__.py 2 matches
• ✓ L2 Verbosity control for diagnostics (--quiet, --log-level, --debug). pygeoapi/flask_app.py 1 matchpygeoapi/starlette_app.py 1 match
• ✗ L3 Structured logs (e.g. --log-format json) or a machine-readable run summary. no structured diagnostics
• ✗ L4 Tracing hooks (OpenTelemetry). no tracing hooks

service ladder · level 0

• ✗ L1 A health or readiness endpoint, or a container healthcheck. no health endpoint or healthcheck
• ✗ L2 Structured logs. no structured logging
• ✗ L3 Metrics. no metrics
• ✗ L4 Distributed tracing (OpenTelemetry). no tracing

Can an agent change it safely with limited context?

• next: L2 CI runs the tests; applications pin dependencies (libraries and zero-dependency projects are exempt). (no lockfile (applications should pin dependencies))

all ladder · level 1

• ✓ L1 A README and some tests. README.mdtests/api/test_admin.py 73 test files
• ✗ L2 CI runs the tests; applications pin dependencies (libraries and zero-dependency projects are exempt). no lockfile (applications should pin dependencies)
• ✗ L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. 79% of modules fit 32k tokens; 2 files over 12k; 45% of code is typed (< 70%)
• ✗ L4 No import cycles, and agent docs (AGENTS.md, CLAUDE.md, llms.txt). 1 import cycles (largest: pygeoapi/__init__.py, pygeoapi/api/__init__.py, pygeoapi/api/collection.py)