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.