Document validation

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

validate_document() raises on an invalid value in a Package, naming its path, before the document is saved.

validate_document

creator_studio_doc_format.validation.validate_document(doc, main_json=None)[source]

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.

Parameters:
doc : Package[PayloadT]

The document to validate.

main_json : dict[str, Any] | None

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.

DocumentVersionWarning

exception creator_studio_doc_format.validation.DocumentVersionWarning[source]

A warning about a union case this version of the library doesn’t implement.

A newer version of the app can write a value as several cases at once. The new case is the primary, and an older case is a fallback for readers that predate it. This version of the library doesn’t implement the primary, so union_primary and union_cases return the fallback, which can be a different kind of value. A save still writes the primary back.

validate_document issues the warning. Catch it to detect that a document was read through a fallback. The message names the primary and the fallback. By default, the warnings module shows a warning once per call site, so checking many documents from one line needs the "always" action.

See also

Validating a document covers when each kind of validation runs and how to handle the errors it raises.