Embed file properties (checksums, sizes) in STAC, or leave them on the files?

[nlebovits]

This came out of the June 26 meeting, and it reopens something we had provisionally decided.

The two positions. Chris's view: embed file properties in the STAC JSON (via the file extension) so that consumers get checksums and sizes without having to touch the data files. Javi's concern: embedded copies of file properties go stale the moment a file changes, and then you either serve wrong metadata or force validators to re-verify everything anyway. Matthias, reviewing separately, leaned toward embedding — with the technical note that the file extension's checksum field uses multihash encoding, not a raw sha256 string, so our values would need converting rather than copying.

Where we're leaning: embed — adopt file:checksum and file:size on assets — while keeping versions.json as the authoritative record. The staleness concern is real, but we think the answer is in the publishing workflow: if the embedded properties are regenerated at push time, as part of the same operation that uploads the files, they can't drift from what's actually in the bucket. We'd want to write that regeneration requirement into the spec, not leave it as an implementation nicety.

---

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

[m-mohr]

Agreed, having it in STAC metadata makes sense. If data files are updated that may also affect other metadata and a rewrite of the STAC is needed then anyway. Or differently speaking: This is not only a file-extension-specific issue. Think about created/updated dates for examples.

[nlebovits]

Resolved as:

Portolan reuses existing extensions rather than restating their fields: file for file:values, table for schema and columns, raster and vector for band and layer detail, license for per-asset license, and scientific for citation or DOI. Assets MUST carry file:size and file:checksum from the file extension. The checksum MUST use multihash encoding, not a raw sha256 string. These embedded values MUST be regenerated at publish time, in the same operation that uploads the files, so they always match what is in the bucket.

[m-mohr]

@nlebovits file:values? That is deprecated since years. classification:classes/bitfields is the successor.