API Reference

API Reference

load

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

Load and parse an APICORE configuration file from disk.

Parameter	Type	Default	Description
path	str | Path	required	Path to the configuration file
version	str | None	None	Force APICORE version ("v1" or "v2")
format	FormatName | None	None	Override format ("json", "yaml", "toml")
encoding	str	"utf-8"	File encoding

Returns a Document (V1Document or V2Document).

Example

from apicore import load

doc = load("config.api.yaml")
doc = load("config.api.json", version="v1")

---

loads

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

Parse an APICORE configuration from a string or bytes.

Parameter	Type	Default	Description
data	str | bytes	required	Raw configuration content
version	str | None	None	Force APICORE version ("v1" or "v2")
format	FormatName | None	None	Input format ("json", "yaml", "toml")
encoding	str	"utf-8"	Encoding for str input

Returns a Document (V1Document or V2Document).

Example

from apicore import loads

doc = loads('{"friendly_name": "Demo", ...}', format="json")

---

validate

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

Validate an APICORE configuration file. Raises an exception on invalid input. Alias for load().

This function returns the parsed Document; it does not return True or False.

Example

from apicore import validate

doc = validate("config.api.toml", format="toml")
print(doc.apicore_version)

---

Version Detection

• If APICORE_version is present in the document, that version is used.
• If version is explicitly passed, it overrides detection (and conflicts with APICORE_version raise an error).
• If neither is present, defaults to v2.

Accepted APICORE_version values

Value	Resolved
"1", "1.0", "v1"	v1
"2", "2.0", "v2"	v2

---

Format Detection (file extension)

Extension	Format
.json	json
.yaml, .yml	yaml
.toml	toml

If the file suffix is unsupported and format is not provided, parsing raises ValidationError.

Exceptions

• ParseError is raised for invalid JSON, YAML, or TOML syntax.
• ValidationError is raised when the decoded document violates APICORE rules.
• APICoreError is the shared base class if you want one catch-all branch.