fluxnet_shuttle.models

Pydantic Schema Models for FLUXNET Shuttle Library

module::: fluxnet_shuttle.models
synopsis:: Pydantic models for FLUXNET dataset metadata and validation
moduleauthor:: Valerie Hendrix <vchendrix@lbl.gov>
moduleauthor:: Sy-Toan Ngo <sytoanngo@lbl.gov>
platform:: Unix, Windows
created:: 2025-10-09
updated:: 2025-12-09

This module defines Pydantic models for data validation and serialization in the FLUXNET Shuttle Library. These models ensure type safety and provide automatic validation for FLUXNET dataset metadata and operations.

Classes:: TeamMember: Team member information for a site BadmSiteGeneralInfo: Site general information from BADM format DataFluxnetProduct: FLUXNET product data information FluxnetDatasetMetadata: Combined model for complete dataset metadata PluginErrorDetail: Individual plugin error information ErrorSummary: Summary of errors collected during operations

The models are designed to work with the FLUXNET data format and provide validation for:

Data hub and publisher information

Site identifiers and temporal coverage

Data versions and file metadata

Download URLs with validation

Error tracking and reporting

Example

>>> from fluxnet_shuttle.models.schema import FluxnetDatasetMetadata
>>> site_info = BadmSiteGeneralInfo(
...     site_id="US-Ha1",
...     site_name="Harvard Forest",
...     data_hub="AmeriFlux",
...     location_lat=42.5378,
...     location_long=-72.1715,
...     igbp="DBF",
...     group_team_member=TeamMember(
...         team_member_name="J. William Munger",
...         team_member_email="<EMAIL>",
...         team_member_role="PI"
...     ),
...     network=["AmeriFlux", "LTER", "Phenocam"]
... )
>>> product_data = DataFluxnetProduct(
...     first_year=2005,
...     last_year=2025,
...     download_link="https://amfcdn-dev.lbl.gov/data.zip",
...     product_id="10.17190/AMF/1871137",
...     product_citation="J. William Munger (2025), AmeriFlux FLUXNET citation ...",
...     product_source_network="AMF",
...     oneflux_code_version="1.3",
...     fluxnet_product_name="AMF_US-Ha1_FLUXNET_..."
... )
>>> metadata = FluxnetDatasetMetadata(
...     site_info=site_info,
...     product_data=product_data
... )

Note

All models use Pydantic v2 syntax and are compatible with FastAPI automatic API documentation generation.

Functions

`Field`([default, default_factory, alias, ...])	!!! abstract "Usage Documentation"
`field_validator`(field, /, *fields[, mode, ...])	!!! abstract "Usage Documentation"
`model_validator`(*, mode)	!!! abstract "Usage Documentation"

Classes

`BadmSiteGeneralInfo`(**data)	Pydantic model for BADM Site General Information.
`BaseModel`(**data)	!!! abstract "Usage Documentation"
`ConfigDict`	A TypedDict for configuring Pydantic behaviour.
`DataFluxnetProduct`(**data)	Pydantic model for FLUXNET Product Data Information.
`ErrorSummary`(**data)	Pydantic model for error summary information.
`FluxnetDatasetMetadata`(**data)	Combined model for complete FLUXNET dataset metadata.
`HttpUrl`(url)	A type that will accept any http or https URL.
`PluginErrorDetail`(**data)	Pydantic model for individual plugin error details.
`TeamMember`(**data)	Pydantic model for team member information.
`datetime`(year, month, day[, hour[, minute[, ...)	The year, month and day arguments are required.

class fluxnet_shuttle.models.BadmSiteGeneralInfo(**data)[source]

Bases: BaseModel

Pydantic model for BADM Site General Information.

This model represents the minimum required fields for site general information in the BADM (Biological, Ancillary, Disturbance and Metadata) format.

Parameters:

site_id (str)
site_name (str)
data_hub (str)
location_lat (float)
location_long (float)
igbp (str)
network (List[str])
group_team_member (List[TeamMember])

site_id

Site identifier by country using first two chars or clusters

Type:: str

site_name

Site name

Type:: str

data_hub

Data hub name (e.g., AmeriFlux, ICOS, TERN)

Type:: str

location_lat

Site latitude in decimal degrees, datum WGS84 ellipsoid

Type:: float

location_long

Site longitude in decimal degrees, datum WGS84 ellipsoid

Type:: float

igbp

IGBP land cover type classification

Type:: str

network

Network affiliation(s) of the site

Type:: List[str]

group_team_member

List of team member information for this site

Type:: List[TeamMember]

data_hub: str

group_team_member: List[TeamMember]

igbp: str

location_lat: float

location_long: float

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

network: List[str]

site_id: str

site_name: str

classmethod validate_site_id_format(v)[source]

Validate that site_id follows the country code pattern.

Return type:: str
Parameters:: v (str)

class fluxnet_shuttle.models.DataFluxnetProduct(**data)[source]

Bases: BaseModel

Pydantic model for FLUXNET Product Data Information.

This model represents the minimum required fields for FLUXNET data products, including temporal coverage and download information.

Parameters:

first_year (int)
last_year (int)
download_link (HttpUrl)
product_citation (str)
product_id (str)
oneflux_code_version (str)
product_source_network (str)
fluxnet_product_name (str)

first_year

First year of data coverage (YYYY format)

Type:: int

last_year

Last year of data coverage (YYYY format)

Type:: int

download_link

URL for downloading the data product

Type:: HttpUrl

product_citation

Citation for the data product

Type:: str

product_id

Product identifier (e.g., hashtag, DOI, PID)

Type:: str

oneflux_code_version

ONEFlux processing code used, extracted from fluxnet_product_name (major.minor version designation only)

Type:: str

product_source_network

Source network identifier extracted from fluxnet_product_name (e.g., AMF, ICOSETC)

Type:: str

fluxnet_product_name

Name of the FLUXNET data product file

Type:: str

download_link: HttpUrl

first_year: int

fluxnet_product_name: str

last_year: int

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

oneflux_code_version: str

product_citation: str

product_id: str

product_source_network: str

validate_year_range()[source]

Validate that last_year is not before first_year.

Return type:: DataFluxnetProduct

class fluxnet_shuttle.models.ErrorSummary(**data)[source]

Bases: BaseModel

Pydantic model for error summary information.

This model represents a summary of errors collected during FLUXNET Shuttle operations, including total counts and detailed error information.

Parameters:

total_errors (int)
total_results (int)
errors (List[PluginErrorDetail])

total_errors

Total number of errors encountered

Type:: int

total_results

Total number of successful results retrieved

Type:: int

errors

List of detailed error information

Type:: List[PluginErrorDetail]

errors: List[PluginErrorDetail]

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total_errors: int

total_results: int

class fluxnet_shuttle.models.FluxnetDatasetMetadata(**data)[source]

Bases: BaseModel

Combined model for complete FLUXNET dataset metadata.

This model combines both site general information and product data to represent a complete FLUXNET dataset entry.

Parameters:

site_info (BadmSiteGeneralInfo)
product_data (DataFluxnetProduct)
extra_data (Any)

site_info

Site general information

Type:: BadmSiteGeneralInfo

product_data

Product data information

Type:: DataFluxnetProduct

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

product_data: DataFluxnetProduct

site_info: BadmSiteGeneralInfo

class fluxnet_shuttle.models.PluginErrorDetail(**data)[source]

Bases: BaseModel

Pydantic model for individual plugin error details.

This model represents an error that occurred during plugin execution, including context about which data hub/plugin encountered the error.

Parameters:

data_hub (str)
operation (str)
error (str)
error_type (str)
timestamp (str)

data_hub

Data hub/plugin name where the error occurred

Type:: str

operation

Operation being performed when the error occurred

Type:: str

error

Error message or description

Type:: str

error_type

Exception class name (e.g. “TimeoutError”, “PluginError”)

Type:: str

timestamp

ISO format timestamp when the error occurred

Type:: str

data_hub: str

error: str

error_type: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

operation: str

timestamp: str

classmethod validate_timestamp_format(v)[source]

Validate that timestamp is in ISO format.

Return type:: str
Parameters:: v (str)

class fluxnet_shuttle.models.TeamMember(**data)[source]

Bases: BaseModel

Pydantic model for team member information.

This model represents information about a team member associated with a site, including their name, role, and contact email.

Parameters:

team_member_name (str)
team_member_role (str)
team_member_email (str)

team_member_name

Team member name (First/Given Last/Family)

Type:: str

team_member_role

Team member role (e.g., PI, Researcher, Data Manager)

Type:: str

team_member_email

Team member email address

Type:: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

team_member_email: str

team_member_name: str

team_member_role: str