validate_octx()

Validate an OCTX Package completely and return errors and warnings in a structured report.

validate_octx() fully validates the OCTX format and every Capability understood by the current implementation, then returns a ValidationReport. It is the validation entry point for external or untrusted Packages.

Signature

def validate_octx(
    package_or_source: OctxPackage | os.PathLike[str] | str,
    *,
    limits: ArchiveLimits | None = None,
    max_issues: int | None = None,
) -> ValidationReport

Parameter	Purpose
`package_or_source`	A `.octx` path, unpacked directory, or already open `OctxPackage`.
`limits`	`ArchiveLimits` used for this open and validation operation. The source is reopened when different limits are supplied.
`max_issues`	Maximum number of issues retained in the report; it must be positive.

Basic usage

from octx import validate_octx

report = validate_octx("asset.octx")

if not report.valid:
    for issue in report.issues:
        print(issue.severity, issue.code, issue.path, issue.message)

For ordinary container, format, and specification errors, the function returns a report with valid=False instead of interrupting the caller with an exception.

`valid` and `fully_validated`

report.valid: the OCTX format is valid, and every recognized declared layer that was validated passed.
report.fully_validated: the current installation understands and has completely validated every declared layer.

A Package with an unknown optional Capability can therefore have valid=True and fully_validated=False. Publication or high-trust import should generally require both values to be True:

if not (report.valid and report.fully_validated):
    reject(report.to_dict())

When octx[vectors] is not installed, the vectors layer produces a warning and sets fully_validated=False; it never pretends that validation succeeded.

Validation scope

OCTX format validation covers container safety, manifest Schema, identity, version, file inventory, per-file SHA-256, Package Digest, Markdown/OKF frontmatter, and Document IDs.

When structure layers are declared, validation also covers:

JSON Schema and UUIDv7 values for chunks, events, and entities in sag-structured.
chunk-event and event-entity references and hierarchy relationships.
Complete-coverage constraints for SAG-Structured.
Arrow schema, RecordBatch messages, dimensions, numeric types, target coverage, and resource boundaries.

When an integrity check fails, the corresponding untrusted structured payload is not parsed further.

Ownership of an open Package

from octx import open_octx, validate_octx

with open_octx("asset.octx") as package:
    report = validate_octx(package)
    # The caller still owns package and can continue reading it.

When passed a path, validate_octx() opens and closes the Package itself. When passed an existing OctxPackage without overriding limits, it does not close the caller-owned object.

Use report.to_dict() to obtain a JSON-serializable structure suitable for logs, CLIs, or API responses.