Project

Portolan STAC Profile¶

Work in Progress — This profile is under active development. Requirement levels and the schema URL may change before the first stable release.

• Title: Portolan
• Identifier: https://schemas.portolan-sdi.org/portolan/v0.2.0/schema.json
• Field Name Prefix: portolan (reserved; no fields defined yet)
• Scope: Catalog, Collection — Items inherit conformance from their collection
• Extension Maturity Classification: Proposal

A Portolan catalog is a directory of STAC metadata and cloud-native geospatial data, served from plain object storage and consumable with zero infrastructure. Following the approach of the CEOS-ARD extension, this directory is both a minimal extension — a JSON Schema for the structural requirements checkable from STAC JSON alone — and a profile: how the Portolan specification uses STAC and existing extensions, which link relations, media types, and roles it requires, and where full validation happens.

Declaring this extension is a claim of conformance, not proof of it: an object conforms only by passing the Portolan validator (see Validation).

Fields¶

This extension defines no fields. The versioned schema URI declared in stac_extensions is the single signal of specification version; no separate version property exists (spec: Conformance and Versioning). Dataset versioning uses the version extension, never portolan: fields.

Declaration happens at the catalog and collection level only — every catalog and collection MUST declare the schema URI in stac_extensions; items inherit conformance from their collection and do not declare it. All objects within a catalog SHOULD declare the same URI; a validator flags a mismatch with the root catalog as a warning, not an error — a mixed-version catalog remains valid.

The portolan: prefix stays reserved for future use.

What the schema enforces¶

The schema encodes the specification's structural requirements that STAC core leaves optional:

• Every Catalog and Collection has a non-empty title and description; every child and item link carries a title (spec: Human-Readable Titles).
• Structural links (root, parent, child, item, collection) carry type: "application/json" (application/geo+json for links to items) (spec: Links). The schema takes no position on relative versus absolute hrefs, and it accepts a self link. The schemas through v0.1.2 reject a self link and require a relative structural href. v0.2.0 drops both rules, following the specification.
• Every asset has href, a media type, and at least one role (spec: Assets). file:size and file:checksum are SHOULD-level, so the schema checks their shape where present without requiring them; the checksum's multihash encoding, and whether either value matches the bytes, are verified by tooling rather than schema.
• Absolute asset hrefs use https — s3:// and other bucket schemes are rejected; relative hrefs are allowed (spec: Assets).
• Every Collection declares providers with at least one producer and a host reachable through url or email; that the host is exactly one and listed last is checked by tooling (spec: Providers).
• Collection license is never the deprecated proprietary; SPDX validity and the rel: "license" link required with other are checked by tooling (spec: License).
• Every bbox — collection extent and item — contains only in-range WGS84 coordinates, with no sentinel "effectively infinite" values (spec: Bounding Boxes and Spatial Extent).
• Every Catalog and Collection links its AGENTS.md with rel: "agents" and type: "text/markdown" (spec: AGENTS.md).
• Every Catalog and Collection links its README.md with rel: "describedby" and type: "text/markdown" (spec: README.md).

STAC Extensions¶

Portolan reuses established extensions rather than re-encoding the same information under portolan:. This table is the normative registry of the extensions the profile uses — the requirement level, the condition under which it applies, and the exact schema URI to pin in stac_extensions. The specification defers to this table rather than restating it.

Requirement keywords per BCP 14; a conditional MUST applies only when its condition holds.

Note that item_assets needs no extension — it is a core field in STAC 1.1.

As the profile grows, per-format requirement sets (vector, raster, tabular) may split into separate subprofile documents, as CEOS-ARD does for optical and SAR.

Profile¶

Link relations¶

Structural links can be relative or absolute; the specification takes no position, and the STAC best practices on the use of links cover the trade-offs. A catalog served over the internet from a single fixed URL SHOULD carry an absolute self link on its root catalog (spec: Links).

Whether a catalog is official or a mirror is derived from its providers (producer = host means official); a mirror records each sync in the core updated field. Every link in a catalog MUST resolve — a link that 404s is a conformance failure. This is a crawling check, outside JSON Schema.

Media types and roles¶

Styles are STAC assets: each style file is a collection-level asset with roles: ["style"], discovered by filtering assets on that role — no separate manifest exists (spec: Visualization Styles).

A source asset names the upstream original a cloud-native asset was derived from, so the format requirements do not reach it. A mirror should carry one when the original is a direct download, which means referencing it at the upstream href, not rehosting the file. collection-mirror comes from the stac-geoparquet specification, not from Portolan, and is required on a published item mirror. Neither role is enumerated in the JSON Schema, which accepts any non-empty role string.

Formats¶

Every collection and item is available in a cloud-optimized format; full requirements live in the specification's format sections, and the data-file internals are validated by tooling, not schema:

• Vector — GeoParquet 1.1/2.0 (compression, spatial ordering, row-group statistics); a PMTiles visualization derivative SHOULD be provided, registered through the rel: "pmtiles" link (an asset only when also intended for distribution), with MapLibre styles as style assets.
• Raster — COG with embedded per-band GDAL statistics in the leading header block.
• Tabular (non-geospatial) — Parquet as a collection-level asset, columns documented with the table extension, spatial requirements relaxed. No marker property: a tabular collection is identified by its data, a Parquet asset with no geometry column.
• Point cloud — reserved; COPC, pending a reference implementation.

Validation¶

Per the specification, validation runs in separable passes:

1. Structural — STAC 1.1.0 core schemas.
2. Metadata — every requirement checkable from metadata alone. This profile's schema is the machine-checkable core of this pass; link resolution needs a crawler.
3. Data — requirements that need asset bytes (GeoParquet spatial ordering, row-group statistics, embedded COG statistics). Run by portolan check, MAY run independently.

Hosting requirements (HTTP Range support, CORS on all metadata and asset files) are properties of the server, validated by probe.

Open questions¶

Tracked in the specification and deliberately not settled by this schema:

1. Raster styling — how raster styles are expressed (colormaps, legends, continuous vs. categorical vs. multiband) is under discussion in specs/incubating/raster-styling.md; the MapLibre style requirements are vector-only for now.

Examples¶

• Root catalog
• Single-file vector collection — GeoParquet + PMTiles + style + thumbnail as collection-level assets
• Partitioned vector collection and partition item

The files are stored flat in examples/ for convenience, but their relative hrefs describe the specification's canonical directory layout ({collection_id}/collection.json, {item_id}/item.json beneath it) — so href targets such as ../catalog.json, AGENTS.md, and the data files are illustrative and not present in this repository. The examples carry no self links and use relative structural hrefs, the portable layout the git-backed best practices recommend for a tracked tree.

Building and Testing¶

Every published schema version is tracked in this repository under json-schema/v<version>/schema.json; the version field in package.json names the current one and is the single source of truth. The portolan-sdi extension schemas (currently partition) live in their own repositories; portolan-extensions.json pins which versions are published under schemas.portolan-sdi.org/<name>/<version>/, so bumping a pin — like binding the profile to a new extension version — is a change to this repository. The publish workflow deploys the site from the tracked tree plus the pinned extension schemas fetched from their source repos.

From stac/:

npm install
npm test

npm test runs (after a pretest step that fetches the pinned extension schemas into the gitignored .schema-cache/):

• check-markdown — remark lint over the profile documents.
• check-version — every versioned Portolan schema URI reference (schema $id, READMEs, examples, spec documents) matches the package.json version, and the matching json-schema/v<version>/ directory exists.
• check-examples — stac-node-validator validates the examples, applying the schema where stac_extensions declares it.
• check-portolan — validates every example directly against the schema with ajv, the way the Portolan validator does. This is what exercises the schema's item rules — items never declare the schema URI, so check-examples alone would never apply it to them. It also applies the pinned extension schemas to every example that declares them, and verifies the examples' file:checksum values are well-formed sha2-256 multihashes, which the schema deliberately delegates to tooling.

Contributing¶

This profile is maintained by the Portolan SDI project. Issues and pull requests are welcome.

License¶

Apache-2.0