Python API

load

load(
path: str|Path,
*,
version: VersionSelector|None=None,
format: FormatName|None=None,
encoding: str="utf-8",
) ->Document

Reads, decodes, validates, and returns an APICORE document. The input format is inferred from the filename unless overridden. Filesystem exceptions propagate unchanged.

loads

loads(
data: str|bytes,
*,
version: VersionSelector|None=None,
format: FormatName|None=None,
encoding: str="utf-8",
) ->Document

Decodes and validates in-memory input. The default format is JSON.

parse

parse(
data: Mapping[str, Any],
*,
version: VersionSelector|None=None,
) ->Document

Validates an already decoded mapping. This is the preferred function for configurations assembled by Python code.

validate

validate(
path: str|Path,
*,
version: VersionSelector|None=None,
format: FormatName|None=None,
encoding: str="utf-8",
) ->Document

Validation-oriented alias for load(). It returns the parsed document, not a boolean.

resolve_i18n

resolve_i18n(
value: I18nString,
locale: str,
*,
fallback_locale: str|None=None,
) ->str

Returns plain strings unchanged. For a language mapping, resolution uses the requested locale, the optional fallback locale, and then the first translation in insertion order.

Version Selectors

VersionSelector accepts:

• v1: APICORE 1 family
• 1.0: exact APICORE 1.0
• v2: APICORE 2 family; accepts declared 2.0 or 2.1 and applies feature-based detection to undeclared input
• 2.0: exact APICORE 2.0
• 2.1 or v2.1: exact APICORE 2.1

If neither the document nor the function call specifies a version, the parser retains APICORE 2.0 semantics unless it detects a v2.1-only field or localized UI value.

APICoreVersion remains the compatibility type alias Literal["v1", "v2"]. Use APICoreSpecVersion when a type annotation must represent exact document versions "1.0", "2.0", and "2.1".

Exceptions

• ParseError: JSON, YAML, or TOML decoding failed.
• ValidationError: decoded data violates APICORE requirements.
• APICoreError: base class for library-defined errors.
• OSError: file access failed in load() or validate().

Public Exports

The supported package-level API is listed in apicore.__all__. It includes all document, parameter, config, handler, response, version, and error models needed to type or construct complete model trees.

__version__ is read from installed package metadata and falls back to 0.0.0 when package metadata is unavailable.