search

stac-utils / stac-fields

A minimal STAC library that contains a list of STAC fields with some metadata and helper functions for styling as HTML.
Apache License 2.0
8 stars 7 forks source link

readme

stac-fields

A minimal STAC library that contains a list of STAC fields with some metadata (title, unit, prefix) and helper functions for styling as HTML.

Version: 1.5.0-beta.2

Usage

Add to your project with npm install @radiantearth/stac-fields --save

Import the utilities to format values:

const StacFields = require('@radiantearth/stac-fields');

or

import StacFields from '@radiantearth/stac-fields';

Format a value:

let stacItem = {
    stac_version: '1.0.0',
    id: '...',
    properties: {
        datetime: '2020-01-01T13:55:43Z',
        'radiant:public_access': true,
        ...
    },
    ...
};

// Add custom extension and field(s)
StacFields.Registry.addExtension('radiant', 'Radiant Earth');
StacFields.Registry.addMetadataField('radiant:public_access', {
    label: "Data Access",
    formatter: (value) => value ? "Public" : "Private"
});

// Option 1: Manually iterate through properties and format them
for(let field in stacItem.properties) {
    let value = stacItem.properties[field];
    let formatted = StacFields.format(value, field, stacItem);
    let label = StacFields.label(field);
    console.log(label, formatted);
}

// Option 2: Group by extension and format item properties
// The second parameter is a filter function to skip specific properties or paths, remove to get all properties
let groups = StacFields.formatItemProperties(stacItem, (key, path) => key !== 'eo:bands');

To filter by path (remove all common_name fields from bands):

let groups = StacFields.formatItemProperties(stacItem, (key, path) => !(path[0] === 'eo:bands' && path[2] === 'common_name'));

This library is written for the latest version of the STAC specification (1.0.0-rc.4). It is recommended to pass your STAC data through a migration tool like @radiantearth/stac-migrate before so that it complies to the latest STAC version. Otherwise some fields may not be handled correctly.

Non-JavaScript library authors can re-use the fields.json. It is available at: https://cdn.jsdelivr.net/npm/@radiantearth/stac-fields/fields.json

fields.json

This is a file defining useful metadata about extensions and metadata fields. In general, the fields.json only lists fields that are either backed by a released extension or have at least one public catalog implementing it.

The following options are available in the object:

If only a label is available, it can be passed as string instead of an object.

Some details about the fields included in the fields.json file can be found here.

There is also a fields-normalized.json, which is a normalized version of the fields.json. All non-Javascript users will probably prefer to use the fields-normalized.json as it already has the aliases resolved and all fields and extensions are defined as objects for easier handling.

formatters.js

The most important methods are:

Pre-defined formatters (Formatters)

Custom formatters

Formatters are always functions that have the following signature:

method(value : any, field : string, spec : object, context = null, parent = null) => string

The returned value is always expected to be a string. It may contain HTML if the formatter is added to the htmlFormats array in fields.json. If the return value is allowed to contain HTML, ALL user input must run thorugh the e() function (or parseInt for integers, for example) to escape malicious HTML tags. This avoids XSS and similar security issues.

I18N

All properties on the I18N class should only be used in read-only mode. You should use the following functions instead:

Registry

Data Types (DataTypes)

This object has functions to format the native JSON data types as HTML strings:

Additionally, it has a method format(value: any) => string, which applies the right formatting depending on the data type of the value.

All methods return strings, which may contain HTML. Input is sanitized.

Helpers