Source:

• src/ometeotl_core/io/importers.py

Local role: Validated reconstruction of a World from JSON text, YAML text, or an already-parsed mapping.

Big-picture role: The import pipeline composes the existing SyntacticValidator, StructuralValidator, and ValidationPipeline from ometeotl_core.validation with World.from_dict from ometeotl_core.model. It keeps parse, validate, and reconstruct as separate internal steps so each failure mode is individually diagnosable. Business logic and serialization rules remain in model; validation rules remain in validation; IO only orchestrates.

WorldImportResult

Frozen dataclass returned by every import helper.

Public functions

world_from_mapping(payload, *, validation_pipeline, mode, stage_modes, raise_on_error)

Accepts an already-parsed mapping. Skips syntactic parsing; runs structural validation on the native payload. Default mode is strict.

world_from_json(payload, *, ...)

Accepts a JSON str or bytes. Runs syntactic validation on the raw text, structural validation on the parsed mapping, then reconstructs.

world_from_yaml(payload, *, ...)

Accepts a YAML str or bytes. Same pipeline as JSON, with format_hint="yaml".

read_world_json(path, *, ...)

Reads UTF-8 JSON from a file path, then delegates to world_from_json.

read_world_yaml(path, *, ...)

Reads UTF-8 YAML from a file path, then delegates to world_from_yaml.

Validation pipeline details

The default pipeline runs two staged validators in order:

1. syntactic — receives the raw serialized text (or the native mapping for world_from_mapping). Checks JSON/YAML parseability and format.
2. structural — receives the parsed mapping. Checks required fields, field types, and schema version.

You can supply a custom ValidationPipeline to override this default. Additional domain validators (temporal, spatial, epistemic, etc.) can be added to that pipeline. Stage-level mode overrides are forwarded from the stage_modes parameter.

Failure contract

• Parse errors raise ValueError before any validation runs.
• Validation failures with raise_on_error=True (the default) raise ValidationException carrying the full ValidationResult.
• Automatic repair is not performed; diagnostics must be acted on by the caller.
• Deferred phases: LLM-view export, schema-backed validation, and automated repair are excluded from V1.

Example:

from ometeotl_core.io.importers import world_from_json, world_from_yaml, read_world_json
from ometeotl_core.io.exporters import world_to_json

# Round-trip: export then reimport
json_str = world_to_json(world)
result = world_from_json(json_str)

restored_world = result.world
print(result.validation.valid)       # True if no issues
print(result.parsed_format)          # "json"

# From file
file_result = read_world_json("output/world.json")
world2 = file_result.world

# Lenient import: collect issues without raising
result2 = world_from_json(json_str, raise_on_error=False)
for issue in result2.validation.errors:
    print(issue.code, issue.message)