Source code for creator_studio_doc_format.validation

# Copyright © 2026 Apple Inc.
#
# Licensed under Apache License v2.0. For more information, see LICENSE.
# SPDX-License-Identifier: Apache-2.0

"""Check in-place edits, presets, and references across a document before you save it.

:func:`validate_document` raises on an invalid value in a
:class:`~creator_studio_doc_format.core.Package`, naming its path, before the document
is saved.
"""

__all__ = ["DocumentVersionWarning", "validate_document"]

import json
from typing import Any

from creator_studio_doc_format.core import Package, PayloadT

from ._field_types import validate_field_types
from ._indirect_resources import validate_indirect_resources
from ._model_tree import validate_model_tree
from ._preset_graph import validate_preset_graph
from ._resolve import _resolve_properties
from ._version_drift import DocumentVersionWarning, validate_version_drift


[docs] def validate_document( doc: Package[PayloadT], main_json: dict[str, Any] | None = None ) -> None: """Checks a document and raises on the first value that breaks the format's rules. Unlike a model's own validation, this also checks values changed in place, values inherited from a preset, resource references, and references across the document. Args: doc: The document to validate. main_json: The JSON that ``save`` passes to a ``pre_save_hooks`` entry. When omitted, the function computes it from ``doc``. Warns: DocumentVersionWarning: The document holds a union case this version of the library doesn't implement, so it reads the case's fallback instead. Raises: LookupError: A preset, identifier, or reference doesn't resolve. ValueError: A resolved value violates an invariant, or the serializer can't encode the document when the function produces its own JSON. DocumentVersionError: When the function produces its own JSON, a union's only case comes from a preset value too new for this version of the library to read. RuntimeError: The function changed ``main_json``. This indicates a defect in ``validate_document``. """ # noqa: DOC502,DOC503 (LookupError/ValueError/DocumentVersionError come from the checks and the dump) validate_version_drift(doc.payload) validate_field_types(doc.payload) # Runs before the dump so that a preset cycle is reported here, not as a # serializer error. validate_preset_graph(doc.presets) main = doc._to_main_json() if main_json is None else main_json before = json.dumps(main) if main_json is not None else None resolved = _resolve_properties(doc, main) validate_indirect_resources(doc, resolved) validate_model_tree(resolved) if before is not None and json.dumps(main) != before: raise RuntimeError( "`main_json` changed during `validate_document`. This is a defect in " "`validate_document`." )