foundation-data-interfaces

name	foundation-data-interfaces
description	Foundational skill for data contracts, resources, interface boundaries, command/result schemas, and deterministic ordering.
tier	core
godot_version	4.6+
doc_anchors	["godot-docs/tutorials/best_practices/data_preferences.rst","godot-docs/tutorials/best_practices/godot_interfaces.rst","godot-docs/classes/class_resource.rst"]
tags	["data","interfaces","contracts"]
depends_on	[]

Foundation Data and Interfaces

Use When

• Defining cross-layer data contracts.
• Building command bridges between UI and services.
• Choosing data structures for performance and clarity.

Outcomes

• Public interfaces expose explicit schema and invariants.
• Command handlers return structured, deterministic results.
• Data ownership boundaries are consistent across systems.

Required Rules

• All public interfaces must define schema and invariants.
• Command handlers must return structured results.
• Deterministic ordering must be explicit where command batches exist.
• UI cannot mutate service-owned state directly.

Workflow

1. Define data models for cross-layer communication.
2. Specify invariants, allowed values, and failure response schema.
3. Separate service-owned mutable data from UI-facing read models.
4. Declare deterministic ordering where batch processing exists.
5. Validate schema compatibility with persistence and network layers.

Validation

• Interface schemas are documented and checked in tests or assertions.
• Command failures return stable reason fields rather than ad hoc strings.
• Same command batch executed twice yields deterministic ordering/results.

Failure Modes

• Loosely typed dictionaries drift and break consumers silently.
• UI mutates service state directly, bypassing command boundaries.
• Unordered collection iteration introduces nondeterministic outcomes.

Local Doc Anchors

• godot-docs/tutorials/best_practices/data_preferences.rst
• godot-docs/tutorials/best_practices/godot_interfaces.rst
• godot-docs/classes/class_resource.rst