API Reference

Class Summary

Class	Summary
ApiConfigurationSchema	Configuration schema root for API configuration. Use this class for individual configuration schemas that will be exported as JSON with a `$schema` property. This class currently does not add any additional fields or methods. Inherits from: `ConfigurationSchema`, the base configuration schema root class.
BaseJSONImporter	Import any `fsp_config_foundation.data_model.ConfigModel` subclass from a schema-annotated JSON file. Applies the normalization pipeline before Pydantic validation: metadata stripping, value-wrapper unboxing, hex-string coercion, scalar-to-list coercion, and id:Name reference resolution. This is the primary entry point for importing schema-annotated JSON files when the model type and file path are known up front: `instance = BaseJSONImporter(MyConfig, "config.json").import_data()`
ConfigModel	Base configuration for all data models. This abstract base class provides standardized validation and serialization behavior for all data models in the system. It configures Pydantic models to: Validate field assignments Prevent implicit type conversions Ignore extra fields in input data for forward compatibility All domain data models should inherit from this class to ensure consistent behavior across the application.
ConfigUnitDataModel	Base class for defining configuration data models for individual configurable units. A configurable unit data model organizes configuration into API, Implementation, and Runtime sections using direct schema-typed fields on the configurable unit model itself. The configuration sections are defined as fields on the `ConfigUnitDataModel` subclass. Only include the sections relevant to your configurable unit (a configurable unit can have 1 to 3 sections). Example with all three configuration sections: `class MyConfigUnitDataModel(ConfigUnitDataModel): api: MyApiConfigurationSchema implementation: MyImplementationConfigurationSchema runtime: MyRuntimeConfigurationSchema` Example with multiple runtime schemas on the configurable unit: `class MyConfigUnitDataModel(ConfigUnitDataModel): runtime_machine_config: MachineConfig runtime_process_configs: list[ProcessConfig]` Inherits from: `ConfigModel`, the base configuration model class.
ConfigUnitFacade	Base class for facade classes managing one `ConfigUnitDataModel` instance. A `ConfigUnitFacade` is a special facade class that manages the whole configuration data of a configurable unit represented by a `ConfigUnitDataModel` instance. All configurable unit facades in the system inherit from this class. Inherits from: `Facade`, the base facade class.
ConfigUnitFacadeRegistration	Registration container pairing a configurable unit data model with its facade and factories. Package plugins can expose registrations via `PackagePlugin.get_config_unit_registrations()` to allow lookup by configurable unit data model type.
ConfigurationSchema	Base configuration model that serves as a foundation for various configuration schemas. This class provides a foundation for defining configuration schemas that can be exported as JSON Schema. It ensures that all derived configuration schemas include a `$schema` property in their serialized output, pointing to the appropriate schema URL for versioning and validation. Inherits from: `ConfigModel`, the base configuration model class.
Entity	Base class for identifiable configuration objects.
ExportTool	High-level JSON exporter for configurable unit facades.
Facade	Base class for all facade classes. A facade manages one or multiple configuration data trees.
ImplementationConfigurationSchema	Configuration schema root for implementation configuration. Use this class for individual configuration schemas that will be exported as JSON with a `$schema` property. This class currently does not add any additional fields or methods. Inherits from: `ConfigurationSchema`, the base configuration schema root class.
ImportTool	Plugin-aware tool for importing configurable unit facades from JSON files.
NamedInstance	Mixin class for named instances. This class provides a name attribute and a method to retrieve the name.
PackagePlugin	Base class for Forge package plugins. Forge packages should provide a concrete implementation of this class and register it via the `forge.packages` entry point group. The plugin acts as the main interface between the foundation framework and the package, providing access to package-specific functionality. All methods have default implementations that return `None`, making the plugin system highly extensible. Subclasses only need to override the methods they actually use.
Ref	Typed reference to an Entity represented as a path string in JSON.
RefOutcome	Structured result of resolving a reference within a schema.
RefStatus	Outcome category for resolving a reference.
RuntimeConfigurationSchema	Configuration schema root for runtime configuration. Use this class for individual configuration schemas that will be exported as JSON with a `$schema` property. This class currently does not add any additional fields or methods. Inherits from: `ConfigurationSchema`, the base configuration schema root class.
Struct	Base class for plain nested data structures that are not referenceable by Ref[T].
ValidationError	Validation failure with a unified structured error API.
ValidationTool	Automatic validation tooling that discovers rules via plugins.

Configuration schema root for API configuration. Use this class for individual configuration schemas that will be exported as JSON with a $schema property. This class currently does not add any additional fields or methods.

Inherits from: ConfigurationSchema, the base configuration schema root class.

BaseJSONImporter

Import any fsp_config_foundation.data_model.ConfigModel subclass from a schema-annotated JSON file. Applies the normalization pipeline before Pydantic validation: metadata stripping, value-wrapper unboxing, hex-string coercion, scalar-to-list coercion, and id:Name reference resolution. This is the primary entry point for importing schema-annotated JSON files when the model type and file path are known up front: instance = BaseJSONImporter(MyConfig, "config.json").import_data()

ConfigModel

Base configuration for all data models.

This abstract base class provides standardized validation and serialization behavior for all data models in the system. It configures Pydantic models to:

Validate field assignments
Prevent implicit type conversions
Ignore extra fields in input data for forward compatibility

All domain data models should inherit from this class to ensure consistent behavior across the application.

ConfigUnitDataModel

Base class for defining configuration data models for individual configurable units.

A configurable unit data model organizes configuration into API, Implementation, and Runtime sections using direct schema-typed fields on the configurable unit model itself. The configuration sections are defined as fields on the ConfigUnitDataModel subclass. Only include the sections relevant to your configurable unit (a configurable unit can have 1 to 3 sections).

Example with all three configuration sections:

class MyConfigUnitDataModel(ConfigUnitDataModel):
    api: MyApiConfigurationSchema
    implementation: MyImplementationConfigurationSchema
    runtime: MyRuntimeConfigurationSchema

Example with multiple runtime schemas on the configurable unit:

class MyConfigUnitDataModel(ConfigUnitDataModel):
    runtime_machine_config: MachineConfig
    runtime_process_configs: list[ProcessConfig]

Inherits from: ConfigModel, the base configuration model class.

ConfigUnitFacade

Base class for facade classes managing one ConfigUnitDataModel instance. A ConfigUnitFacade is a special facade class that manages the whole configuration data of a configurable unit represented by a ConfigUnitDataModel instance. All configurable unit facades in the system inherit from this class.

Inherits from: Facade, the base facade class.

ConfigUnitFacadeRegistration

Registration container pairing a configurable unit data model with its facade and factories. Package plugins can expose registrations via PackagePlugin.get_config_unit_registrations() to allow lookup by configurable unit data model type.

ConfigurationSchema

Base configuration model that serves as a foundation for various configuration schemas. This class provides a foundation for defining configuration schemas that can be exported as JSON Schema. It ensures that all derived configuration schemas include a $schema property in their serialized output, pointing to the appropriate schema URL for versioning and validation.

Inherits from: ConfigModel, the base configuration model class.

Entity

Base class for identifiable configuration objects.

ExportTool

High-level JSON exporter for configurable unit facades.

Facade

Base class for all facade classes. A facade manages one or multiple configuration data trees.

ImplementationConfigurationSchema

Configuration schema root for implementation configuration. Use this class for individual configuration schemas that will be exported as JSON with a $schema property. This class currently does not add any additional fields or methods.

Inherits from: ConfigurationSchema, the base configuration schema root class.

ImportTool

Plugin-aware tool for importing configurable unit facades from JSON files.

NamedInstance

Mixin class for named instances. This class provides a name attribute and a method to retrieve the name.

PackagePlugin

Base class for Forge package plugins. Forge packages should provide a concrete implementation of this class and register it via the forge.packages entry point group. The plugin acts as the main interface between the foundation framework and the package, providing access to package-specific functionality.

All methods have default implementations that return None, making the plugin system highly extensible. Subclasses only need to override the methods they actually use.

Ref

Typed reference to an Entity represented as a path string in JSON.

RefOutcome

Structured result of resolving a reference within a schema.

RefStatus

Outcome category for resolving a reference.

RuntimeConfigurationSchema

Configuration schema root for runtime configuration. Use this class for individual configuration schemas that will be exported as JSON with a $schema property. This class currently does not add any additional fields or methods.

Inherits from: ConfigurationSchema, the base configuration schema root class.

Struct

Base class for plain nested data structures that are not referenceable by Ref[T].

ValidationError

Validation failure with a unified structured error API.

ValidationTool

Automatic validation tooling that discovers rules via plugins.