Skip to content

Latest commit

 

History

History
149 lines (117 loc) · 9.31 KB

README.md

File metadata and controls

149 lines (117 loc) · 9.31 KB
Raw

File Info Extension Specification

Provides a way to specify file related details such as checksum, data type and size for assets in STAC Items, STAC Catalogs, as well as STAC Collections that implement collection-level assets.

Asset / Link Object fields

The following fields can be used for assets (in the Asset Object) or links (in the Link Object).

Field Name Type Description
file:byte_order string The byte order of integer values in the file. One of big-endian or little-endian.
file:checksum string Provides a way to specify file checksums (e.g. BLAKE2, MD5, SHA1, SHA2, SHA3). The hashes are self-identifying hashes as described in the Multihash specification and must be encoded as hexadecimal (base 16) string with lowercase letters.
file:header_size integer The header size of the file, specified in bytes.
file:size integer The file size, specified in bytes.
file:values (deprecated) [Mapping Object] Lists the value that are in the file and describes their meaning. See the Mapping Object chapter for an example. If given, at least one array element is required. Deprecated in favor of the classification extension.
file:local_path string A relative local path for the asset/link.

Note: File specific details should not be part of the Item Assets Definition extension to Collections.

Mapping Object

NOTE: file:values and their associated mapping objects are deprecated in favor of the classification extension, and will be removed in the next major release (v3.0.0).

Value maps are used by assets/links that are used as classification layers and give details about the values in the asset/link and their meanings.

Field Name Data Type Description
values [any] REQUIRED. The value(s) in the file. At least one array element is required.
summary string REQUIRED. A short description of the value(s).

For example for a cloud cover mask, file:values property could contain the following data:

[
	{"value": [0], "summary": "clear"},
	{"value": [1], "summary": "clouds"},
	{"value": [2], "summary": "cloud shadows"}
]

Sizes

Please be aware that the integer values (always unsigned) given for the sizes (especially file:size) may exceed the maximum value for the default integer data type in your environment / programming language. In this specification integer specifies a integer number without an upper limit. You might need to use other data types to store the values in. For example, files with a size larger than around 2,14 GB would exceed the maximum value for int32 and in JavaScript BigInt could be used then.

Checksums

file:checksum was previously defined in the checksum extension and the field name was checksum:multihash before STAC v1.0.0-rc.1. The specification of the field has not changed.

Below is a list with checksum examples for some algorithms supported by Multihash. The checksums given are for an ASCII text file with the content test.

  • Algorithm sha1 (160 bits): 1114a94a8fe5ccb19ba61c4c0873d391e987982fbbd3
  • Algorithm sha2 (256 bits): 12209f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
  • Algorithm sha2 (256 bits truncated to 160 bits): 12149f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b
  • Algorithm blake2b-128: 90e4021044a8995dd50b6657a037a7839304535b

Local Path

An asset/link is referenced with a simple URL that does not give a good indication about how the file might be organized together with the other assets/links when downloaded and/or extracted to a local filesystem.

By default, the main purpose is file downloading but the purpose of this field may be refined by other extensions, e.g., an archive extension may indicate the location of the asset/link in a ZIP or TAR file which at the same time is also the local path to extract the file to. For example, some software require that the asset/link is placed in a specific relative folder or the metadata asset/link might contain references relative to another asset/link.

The file:local_path field indicates a relative path that can be used by clients for different purposes to organize the files locally. For compatibility reasons the name-separator character in paths must be / and the Windows separator \ is not allowed.

Example use case: SNAP toolbox reads the SAFE manifest to open a product that references the different files (e.g. image bands) relatively and thus expects to find them in the referenced folder (e.g. IMG_DATA).

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples