protomaps/PMTiles

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

format ladder · level 4

• ✓ L1 A specification document describes the format (layout, header, encoding), or a machine-readable definition exists. spec/v2/spec.md format specification (byte, bytes, header, little-endian)spec/v3/spec.md format specification (byte, bytes, compression, encoding)
• ✓ L2 The specification is versioned (versioned spec documents, or a version field in the format). versioned specifications: spec/v2, spec/v3
• ✓ L3 Reference implementations exist in at least two languages. js/package.json npm packageopenlayers/package.json npm package
• ✓ L4 Conformance material: sample files including invalid ones, or a machine-readable definition (Kaitai Struct, ABNF, JSON Schema). js/test/data/empty.pmtiles 7 sample filesjs/test/data/invalid.pmtiles invalid-input fixture

library ladder · level 4

• ✓ L1 An importable, packaged API exists. js/package.json npm packageopenlayers/package.json npm package
• ✓ L2 The public API is delimited (__all__, an exports map, exported identifiers). js/package.json package entry pointopenlayers/package.json package entry point
• ✓ L3 The public API is statically typed (py.typed, type declarations, a typed language). python/pmtiles/pmtiles/py.typed py.typedjs/package.json TypeScript types
• ✓ L4 An API reference is generated from the code (autodoc, mkdocstrings, typedoc, …). js/package-lock.json 9 matches.github/workflows/actions.yml 2 matches

Can integrators rely on it not changing under them?

• next: L1 Releases are versioned (semver tags or versioned changelog sections). (no semver tags or versioned releases)
• next: [format] L4 Old versions can be migrated or converted (documented tooling). (no migration from old versions)

all ladder · level 0

• ✗ L1 Releases are versioned (semver tags or versioned changelog sections). no semver tags or versioned releases
• ✗ 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. fewer than two tagged releases to compare

format ladder · level 3

• ✓ L1 The format carries a version. versioned specifications: spec/v2, spec/v3
• ✓ L2 Changes between format versions are documented (a spec changelog or per-version specifications). spec/v3/CHANGELOG.md per-version specifications
• ✓ L3 The specification states compatibility rules (what readers and writers must do across versions, deprecations). spec/v2/spec.md compatibility rules
• ✗ L4 Old versions can be migrated or converted (documented tooling). no migration from old versions

Can others react to state changes without polling?

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

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

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

• next: L3 Timeouts and retries are configurable. (no timeout parameter)

library ladder · level 2

• ✓ L1 Errors are specific exception types, and library code never calls sys.exit. python/pmtiles/pmtiles/tile.py 2 matchesjs/src/index.ts 1 match
• ✓ L2 Inputs are validated with messages naming the bad argument. js/src/index.ts 13 matchespython/pmtiles/pmtiles/tile.py 4 matches
• ✗ L3 Timeouts and retries are configurable. no timeout parameter
• ✗ L4 Agent docs, and examples that run as tests (doctests). no agent docs

Can another system run and compose it without a human?

• next: L3 Published to a public registry, with at most 10 runtime dependencies. (not published to a registry)

library ladder · level 2

• ✓ L1 Importable from source. js/package.json npm packageopenlayers/package.json npm package
• ✓ L2 Installable as a package (a package manifest). js/package.json package manifestopenlayers/package.json package manifest
• ✗ L3 Published to a public registry, with at most 10 runtime dependencies. not published to a registry
• ✓ L4 Optional features behind extras/features. python/rio-pmtiles/setup.py 1 match

Can behaviour be added without modifying the code?

• next: L1 Internal seams: a registry, registration function or plugin manager. (no registry or registration function)
• next: [format] L2 Readers are told how to treat unknown fields or values (forward compatibility), or values are reserved. (the specification doesn't say: unknown or reserved fields)

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. extensions must be added inside the package
• ✗ L4 The extension API is versioned, has lifecycle hooks, and has example extensions. the extension API isn't versioned

format ladder · level 1

• ✓ L1 The specification defines free-form metadata or custom fields. spec/v2/spec.md metadata or custom fields
• ✗ L2 Readers are told how to treat unknown fields or values (forward compatibility), or values are reserved. the specification doesn't say: unknown or reserved fields
• ✓ L3 Enumerations (types, compressions) are extensible, with reserved or registered values. spec/v3/spec.md extensible enumerations
• ✗ L4 A documented process or registry for adding extensions. the specification doesn't say: an extension process

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

• next: L1 Logs through a standard logger namespace and never prints from library code. (library code prints: python/pmtiles/pmtiles/convert.py, .github/check_examples.py)

library ladder · level 0

• ✗ L1 Logs through a standard logger namespace and never prints from library code. library code prints: python/pmtiles/pmtiles/convert.py, .github/check_examples.py
• ✗ L2 Log levels are used meaningfully (at least two levels). fewer than two log levels used
• ✗ L3 Optional metrics or tracing hooks. no metrics or tracing hooks
• ✗ L4 OpenTelemetry instrumentation available. no OpenTelemetry instrumentation

Can an agent change it safely with limited context?

• next: L4 No import cycles, and agent docs (AGENTS.md, CLAUDE.md, llms.txt). (no agent docs (AGENTS.md, CLAUDE.md, llms.txt))

all ladder · level 3

• ✓ L1 A README and some tests. README.mdjs/test/abort.test.ts 13 test files
• ✓ L2 CI runs the tests; applications pin dependencies (libraries and zero-dependency projects are exempt). .github/workflows/actions.yml library or zero-dependency project: lockfile not required
• ✓ 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. js/test/abort.test.ts test ratio 0.30, 80% typed, modules fit
• ✗ L4 No import cycles, and agent docs (AGENTS.md, CLAUDE.md, llms.txt). no agent docs (AGENTS.md, CLAUDE.md, llms.txt)