API Reference

class stac_check.lint.Linter(item: str | ~typing.Dict, config_file: str | None = None, assets: bool = False, links: bool = False, recursive: bool = False, max_depth: int | None = None, assets_open_urls: bool = True, headers: ~typing.Dict = <factory>, pydantic: bool = False, verbose: bool = False)

Bases: object

A class for linting STAC JSON files and generating validation messages.

Parameters:

• item (Union[str, dict]) – A URL, file name, or dictionary representing a STAC JSON file.

• config_file (Optional[str], optional) – A path to a YAML configuration file. Defaults to None.

• assets (bool, optional) – A boolean value indicating whether to validate assets. Defaults to False.

• links (bool, optional) – A boolean value indicating whether to validate links. Defaults to False.

• recursive (bool, optional) – A boolean value indicating whether to perform recursive validation. Defaults to False.

• max_depth (Optional[int], optional) – An optional integer indicating the maximum depth to validate recursively. Defaults to None.

• assets_open_urls (bool) – Whether to open assets URLs when validating assets. Defaults to True.

• headers (dict) – HTTP headers to include in the requests.

• pydantic (bool, optional) – A boolean value indicating whether to use pydantic validation. Defaults to False.

• verbose (bool, optional) – A boolean value indicating whether to enable verbose output. Defaults to False.

data

A dictionary representing the STAC JSON file.

Type:

dict

message

A dictionary containing the validation message for the STAC JSON file.

Type:

dict

config

A dictionary containing the configuration settings.

Type:

dict

asset_type

A string representing the asset type, if one is specified.

Type:

str

version

A string representing the version of the STAC standard used in the STAC JSON file.

Type:

str

validator_version

A string representing the version of the STAC validator used to validate the STAC JSON file.

Type:

str

validate_all

A dictionary containing the validation message for all STAC JSON files found recursively, if recursive validation was performed.

Type:

dict

valid_stac

A boolean value indicating whether the STAC JSON file is valid.

Type:

bool

error_type

A string representing the type of error in the STAC JSON file, if one exists.

Type:

str

error_msg

A string representing the error message in the STAC JSON file, if one exists.

Type:

str

invalid_asset_format

A list of URLs with invalid asset formats, if assets were validated.

Type:

List[str]

invalid_asset_request

A list of URLs with invalid asset requests, if assets were validated.

Type:

List[str]

invalid_link_format

A list of URLs with invalid link formats, if links were validated.

Type:

List[str]

invalid_link_request

A list of URLs with invalid link requests, if links were validated.

Type:

List[str]

schema

A list of the STAC JSON file’s JSON schema files.

Type:

List[str]

object_id

A string representing the STAC JSON file’s ID.

Type:

str

file_name

A string representing the name of the file containing the STAC JSON data.

Type:

str

best_practices_msg

A string representing best practices messages for the STAC JSON file.

Type:

str

geometry_errors_msg

A string representing geometry-related error messages for the STAC JSON file.

Type:

str

parse_config(config_file

Optional[str] = None) -> Dict: Parses a YAML configuration file and returns a dictionary with the configuration settings.

def get_asset_name(self, file

Union[str, Dict] = None) -> str: Returns the name of a file.

load_data(self, file

Union[str, Dict]) -> Dict: Loads a STAC JSON file from a URL or file path and returns a dictionary representation.

validate_file(self, file

Union[str, dict]) -> Dict[str, Any]: Validates a STAC JSON file and returns a dictionary with the validation message.

recursive_validation(self, file

Union[str, Dict[str, Any]]) -> str: Validates a STAC JSON file recursively and returns a dictionary with the validation message.

set_update_message(self) → str

Sets a message regarding the recommended version of the STAC JSON file standard.

check_links_assets(self, num_links

int, url_type: str, format_type: str) -> List[str]: Checks whether the STAC JSON file has links or assets with invalid formats or requests.

check_error_type(self) → str

Checks whether the STAC JSON file has an error type.

check_error_message(self) → str

Checks whether the STAC JSON file has an error message.

def check_summaries(self) -> bool

Checks whether the STAC JSON file has summaries.

check_bloated_links(self, max_links

Optional[int] = 20) -> bool: Checks whether the STAC JSON file has bloated links.

check_bloated_metadata(self, max_properties

Optional[int] = 20) -> bool: Checks whether the STAC JSON file has bloated metadata.

check_datetime_null(self) → bool

Checks whether the STAC JSON file has a null datetime.

check_unlocated(self) → bool

Checks whether the STAC JSON file has unlocated items.

check_geometry_null(self) → bool

Checks whether the STAC JSON file has a null geometry.

check_searchable_identifiers(self) → bool

Checks whether the STAC JSON file has searchable identifiers.

check_bbox_antimeridian(self) → bool

Checks if a bbox that crosses the antimeridian is correctly formatted.

check_percent_encoded(self) → bool

Checks whether the STAC JSON file has percent-encoded characters.

check_thumbnail(self) → bool

Checks whether the STAC JSON file has a thumbnail.

check_links_title_field(self) → bool

Checks whether the STAC JSON file has a title field in its links.

check_links_self(self) → bool

Checks whether the STAC JSON file has a self link.

check_item_id_file_name(self) → bool

Checks whether the filename of an Item conforms to the STAC specification.

check_catalog_file_name(self) → str

Checks whether the filename of a Catalog or Collection conforms to the STAC specification.

create_best_practices_dict(self) → Dict[str, Any]

Creates a dictionary with best practices recommendations for the STAC JSON file.

create_best_practices_msg(self) → List[str]

Creates a message with best practices recommendations for the STAC JSON file.

create_geometry_errors_msg(self) → List[str]

Creates a message with geometry-related error messages for the STAC JSON file.

assets: bool = False

assets_open_urls: bool = True

check_bbox_antimeridian() → bool

Checks if a bbox that crosses the antimeridian is correctly formatted.

According to the GeoJSON spec, when a bbox crosses the antimeridian (180°/-180° longitude), the minimum longitude (bbox[0]) should be greater than the maximum longitude (bbox[2]). This method checks if this convention is followed correctly.

Returns:

True if the bbox is valid (either doesn’t cross antimeridian or crosses it correctly),

False if it incorrectly crosses the antimeridian.

Return type:

bool

check_bbox_matches_geometry() → bool | Tuple[bool, List[float], List[float], List[float]]

Checks if the bbox of a STAC item matches its geometry.

This function verifies that the bounding box (bbox) accurately represents the minimum bounding rectangle of the item’s geometry. It only applies to items with non-null geometry of type Polygon or MultiPolygon.

Returns:

• True if the bbox matches the geometry or if the check is not applicable (e.g., null geometry or non-polygon type).

• When there’s a mismatch: a tuple containing (False, calculated_bbox, actual_bbox, differences)

Return type:

Union[bool, Tuple[bool, List[float], List[float], List[float]]]

check_bloated_links(max_links: int | None = 20) → bool

Checks if the number of links in the STAC data exceeds a certain maximum.

Parameters:

max_links (Optional[int]) – The maximum number of links that the STAC data is allowed to have. Default is 20.

Returns:

A boolean indicating if the number of links in the STAC data exceeds the specified maximum.

Return type:

bool

check_bloated_metadata(max_properties: int | None = 20) → bool

Checks whether a STAC item’s metadata contains too many properties.

Parameters:

max_properties (int, optional) – The maximum number of properties that the metadata can contain before it is considered too bloated. Defaults to 20.

Returns:

True if the number of properties in the metadata exceeds the maximum number of properties specified by

max_properties, False otherwise.

Return type:

bool

check_catalog_file_name() → bool

Checks whether the filename of a Catalog or Collection conforms to the STAC specification.

Returns:

True if the filename is valid, False otherwise.

Return type:

bool

check_datetime_null() → bool

Checks if the STAC item has a null datetime property.

Returns:

A boolean indicating whether the datetime property is null (True) or not (False).

Return type:

bool

check_geometry_coordinates_definite_errors() → bool | Tuple[bool, List]

Checks if the coordinates in a geometry contain definite errors.

This function checks for coordinates that definitely violate the GeoJSON specification:

1. Latitude values (second element) exceed ±90 degrees

2. Longitude values (first element) exceed ±180 degrees

This check focuses on definite errors rather than potential/likely errors. For checking potential errors (likely reversed coordinates), use check_geometry_coordinates_order().

Returns:

• If no errors: True

• If errors found: (False, list_of_invalid_coordinates)

Return type:

Union[bool, Tuple[bool, List]]

check_geometry_coordinates_order() → bool

Checks if the coordinates in a geometry may be in the incorrect order.

This function uses a heuristic to detect coordinates that are likely in the wrong order (latitude, longitude instead of longitude, latitude). It looks for cases where: - The first value (supposed to be longitude) is > 90 degrees - The second value (supposed to be latitude) is < 90 degrees - The first value is more than twice the second value

For checking definite errors (values outside valid ranges), use check_geometry_coordinates_definite_errors().

Returns:

True if coordinates appear to be in the correct order, False if they may be reversed.

Return type:

bool

check_geometry_null() → bool

Checks if a STAC item has a null geometry property.

Returns:

A boolean indicating whether the geometry property is null (True) or not (False).

Return type:

bool

check_item_id_file_name() → bool

check_links_assets(num_links: int, url_type: str, format_type: str) → List[str]

Checks the links and assets in the STAC catalog and returns a list of invalid links of a specified type and format.

Parameters:

• num_links (int) – The maximum number of invalid links to return.

• url_type (str) – The type of URL to check, which can be either ‘self’ or ‘external’.

• format_type (str) – The format of the URL to check, which can be either ‘html’ or ‘json’.

Returns:

A list of invalid links of the specified type and format. If there are no invalid links, an empty list is returned.

check_links_self() → bool

Checks whether the “self” link is present in the STAC collection or catalog or absent in STAC item.

Returns:

True if the “self” link is present in STAC collection or catalog or absent in STAC item, False otherwise.

Return type:

bool

check_links_title_field() → bool

Checks if all links in a STAC collection or catalog have a ‘title’ field. The ‘title’ field is not required for the ‘self’ link.

Returns:

True if all links have a ‘title’ field, False otherwise.

Return type:

bool

check_percent_encoded() → bool

Checks if the identifiers of a STAC item are percent-encoded, i.e., they only contain lowercase letters, numbers, hyphens, and underscores.

Returns:

True if the identifiers are percent-encoded, False otherwise.

Return type:

bool

check_searchable_identifiers() → bool

Checks if the identifiers of a STAC item are searchable, i.e., they only contain lowercase letters, numbers, hyphens, and underscores.

Returns:

True if the identifiers are searchable, False otherwise.

Return type:

bool

check_summaries() → bool

Check if a Collection asset has a “summaries” property.

Returns:

A boolean indicating whether the Collection asset has a “summaries” property.

check_thumbnail() → bool

Checks if the thumbnail of a STAC item is valid, i.e., it has a valid format.

Returns:

True if the thumbnail is valid, False otherwise.

Return type:

bool

check_unlocated() → bool

Checks if a STAC item is unlocated, i.e., has no geometry but has a bounding box.

Returns:

True if the STAC item is unlocated, False otherwise.

Return type:

bool

config_file: str | None = None

create_best_practices_dict() → Dict

Creates a dictionary of best practices violations for the current STAC object. The violations are determined by a set of configurable linting rules specified in the config file.

Returns:

A dictionary of best practices violations for the current STAC object. The keys in the dictionary correspond to the linting rules that were violated, and the values are lists of strings containing error messages and recommendations for how to fix the violations.

create_best_practices_msg() → List[str]

Generates a list of best practices messages based on the results of the ‘create_best_practices_dict’ method.

Returns:

A list of strings, where each string contains a best practice message. Each message starts with the ‘STAC Best Practices:’ base string and is followed by a specific recommendation. Each message is indented with four spaces, and there is an empty string between each message for readability.

create_geometry_errors_msg() → List[str]

Generates a list of geometry-related error messages based on the results of the ‘create_best_practices_dict’ method.

This separates geometry coordinate validation errors from other best practices for clearer presentation.

Returns:

A list of strings, where each string contains a geometry error message. Each message starts with the ‘Geometry Validation Errors [BETA]:’ base string and is followed by specific details. Each message is indented with four spaces, and there is an empty string between each message for readability.

get_asset_name(file: str | Dict = None) → str

Extracts the name of an asset from its file path or from a STAC item asset dictionary.

Parameters:

file (Union[str, dict], optional) – A string representing the file path to the asset or a dictionary representing the asset as specified in a STAC item’s assets property.

Returns:

A string containing the name of the asset.

Raises:

TypeError – If the input file is not a string or a dictionary.

get_message_field(field_name: str) → str

Get a field from the validation message.

Parameters:

field_name – The name of the field to retrieve (e.g., ‘error_type’, ‘error_message’)

Returns:

The value of the field if it exists, otherwise an empty string.

headers: Dict

item: str | Dict

links: bool = False

load_data(file: str | Dict) → Dict

Loads JSON data from a file or URL.

Parameters:

file (Union[str, Dict]) – A string representing the path to a JSON file or a dictionary containing the JSON data.

Returns:

A dictionary containing the loaded JSON data.

Raises:

• TypeError – If the input file is not a string or dictionary.

• ValueError – If file is a string that doesn’t represent a valid URL or file path.

• requests.exceptions.RequestException – If there is an error making a request to a URL.

• JSONDecodeError – If the JSON data cannot be decoded.

• FileNotFoundError – If the specified file cannot be found.

max_depth: int | None = None

static parse_config(config_file: str | None = None) → Dict

Parse the configuration file for STAC checks.

The method first looks for a file path specified in the STAC_CHECK_CONFIG environment variable. If the variable is defined, the method loads the YAML configuration file located at that path. Otherwise, it loads the default configuration file packaged with the stac-check module.

If config_file is specified, the method also loads the YAML configuration file located at that path and merges its contents with the default or environment-based configuration.

Parameters:

config_file (str) – The path to the YAML configuration file.

Returns:

A dictionary containing the parsed configuration values.

Raises:

• IOError – If config_file is specified but cannot be read.

• yaml.YAMLError – If any YAML syntax errors occur while parsing the configuration file(s).

pydantic: bool = False

recursive: bool = False

recursive_validation(file: str | Dict[str, Any]) → str

Recursively validate a STAC item or catalog file and its child items.

Parameters:

file (Union[str, Dict[str, Any]]) – A string representing the file path to the STAC item or catalog, or a dictionary representing the STAC item or catalog.

Returns:

A string containing the validation message.

Raises:

TypeError – If the input file is not a string or a dictionary.

set_update_message() → str

Returns a message for users to update their STAC version.

Returns:

A string containing a message for users to update their STAC version.

validate_file(file: str | dict) → Dict[str, Any]

Validates the given file path or STAC dictionary against the validation schema.

Parameters:

file (Union[str, dict]) – A string representing the file path to the STAC file or a dictionary representing the STAC item.

Returns:

A dictionary containing the results of the validation, including the status of the validation and any errors encountered.

Raises:

ValueError – If file is not a valid file path or STAC dictionary.

verbose: bool = False