Should Portolan be a STAC extension, a profile, or some combination?

[nlebovits]

Status: blocking — sprint work waits on this one.

We've concluded that Portolan should not try to become "a STAC extension" — most of what our spec requires (file layout on disk, the versions.json manifest, how remote buckets are managed) simply can't be expressed as STAC metadata. What we think the right structure looks like:

• A small portolan: extension for our genuinely custom fields: the flag marking a collection as non-geospatial, the provisional-datetime marker, the styles and legends manifests, and size rollups.
• Our partition: extension for Hive-partitioned datasets, which is already designed.
• Existing STAC extensions wherever they fit — file for checksums and sizes, version for version links, web-map-links for PMTiles links, table for tabular schemas — instead of inventing our own equivalents.
• A "Portolan profile" document for everything else: the requirements a catalog must meet that live outside the STAC JSON itself.

Our questions: Does this split match how you would structure it? And is there existing prior art for a "STAC profile" — some conformance mechanism like conformance classes or a profile URI — that we should copy instead of inventing our own?

---

Part of the July 2026 spec sprint. Hub: discussion #570 · work tracker: epic #564 · everything here carries the spec-sprint label.

[m-mohr]

Parts of the partition extension have similarities to existing extensions:

• table
• link-templates (and the discussed asset templates extension)

We could potentially simplify it by marking the partition column in the table extension and using a templated URL via link templates or asset templates extension (later extension: tbd)

Is there somewhere an overview over the portolan fields? I couldn't find an extension document yet.

[cholmes]

We've concluded that Portolan should not try to become "a STAC extension" — most of what our spec requires (file layout on disk, the versions.json manifest, how remote buckets are managed) simply can't be expressed as STAC metadata. What we think the right structure looks like:

I generally agree with the assessment here, but I don't I agree that 'most' of the spec can't be expressed, the 'most of what our spec requires (file layout on disk, the versions.json manifest, how remote buckets are managed' doesn't seem to be a great list - versions.json I'm not fully convinced is truly 'core' (like I think it could be ok to allow portolan catalogs without those) and I also think it could potentially be integrated into STAC, and how remote buckets are managed seems to be more a cli thing? If file layout on disk means like cog and geoparquet profiles then I agree, but I also don't think it's 'most'.

But I had definitely been thinking about a small portolan extension and mostly reusing other extensions. And I think there is some prior art on defining a STAC extension that requires a number of other extensions.

Main design philosophy to me is:

• As much as possible should be expressed as STAC extensions, and we should be able to validate much of a portolan catalog with pure STAC validators.
• We can 'incubate' stac fields under portolan: namespace, but we should be looking to contribute to the broader ecosystem as much as possible, for anything that is more broadly useful.
• We'll need to figure out how to validate the things beyond what we can in STAC, and those will need a custom tool. The spec itself should just list the requirements in human readable language, and stac extensions are the encoding a subset of that in validating json.

[cayetanobv]

Agree with the philosophy of pushing as much as possible into STAC, and I audited it against the actual MUST list (spec vs what the CLI creates vs what check enforces). it's possible, almost entirely.

Small report (I prepared 2 more detailed reports supporting it, which we can discuss in the Sprint tomorrow):

Of ~18 MUSTs, ~12 are already expressible as pure JSON Schema (core + existing extensions + a small portolan: schema). Three more just need to become required links instead of required files: versions.json → rel:"version-history", llms.txt → rel:"llms", and the PMTiles size threshold → a schema check on file:size (only works if #577 lands on "embed"). What's left that STAC truly can't express is just two things: whether the data files are actually valid (GeoParquet/COG internals, checksums — #580) and how they're hosted (CORS/Range). Both fit the "custom tool + human-readable requirements" bucket. .portolan/config.yaml we'd drop from the spec entirely — it's CLI-internal state, same logic as bucket management.

Two important findings from the audit are worth having on the table:

• Spec, CLI, and check currently disagree on the MUSTs. spec/schema/rules.yaml defines ~40 rules but only 6 are wired to a validator; llms.txt is a MUST that nothing creates and nothing checks; versions.json/config.yaml existence is error-level in the spec but never validated; PMTiles is a size-thresholded MUST in the spec but a blanket, never-blocking warning in check. So "which MUSTs" need deciding before "where they live".
• On versions.json not being truly core, the Iceberg backend proves the point. backends/iceberg/ has no versions.json at all (version history = snapshots), so the moment RULE-0050/0051 get enforced, every Iceberg-backed catalog fails. Rather than the validator sniffing CLI config to skip checks, we'd propose versioning as a named conformance class (versioning-json / versioning-iceberg), declared in the published catalog, the same pattern the tabular rules already use with portolan:geospatial.

[m-mohr]

Quick note: The validity of a COG can be implicitly expressed via media types, but I think we don't have a specific GeoParquet media type, unfortunately.

[nlebovits]

Closing, since we've agreed on a structure:

• Portolan is not a pure STAC extension, since some of what we require (e.g., data file validity or CORS) can't be expressed as STAC metadata.
• We'll have a small Portolan STAC extension for our own custom fields and try to push anything useful upstream to the wider ecosystem; incubate --> promote is the idea.
• We'll reuse existing extensions whenever possible.
• The human-readable spec is the source of truth. We'll build a custom validator for this and then get he CLI in sync with this, removnig the current schema + spec + validator from the CLI (which is now outdated).
• versions.json is not core and will not be included in this version of the spec. We'll research tradeoffs/possibilities among versions.json, the versions STAC extension, and iceberg, and consider the best way to integrate them into v0.2/0.3 of the spec.