Schema Metadata Model

Buffalo Core provides shared schema metadata primitives so Buffalo projects can attach machine-readable GUI and editor hints directly to dataclass fields. The model stays domain-light while giving downstream projects a stable vocabulary for labels, ordering, numeric constraints, collection hints, conditional UI rules, and human-readable choice text.

Components

• SchemaChoice stores both a serialized value and a display label for one enum-like option.

• SchemaCondition stores one machine-readable conditional UI rule.

• SchemaField builds the structured dictionary stored in dataclasses.field(metadata=...).

• schema_field_metadata(cls) reads that metadata back from a dataclass type.

Design Goals

The dataclass remains the source of truth. Buffalo Core only provides the shared metadata contract and normalization behavior used by GUIs, tree editors, tests, and downstream project-local facades. This keeps Buffalo Core focused on reusable schema infrastructure rather than owning project-specific schema families.

Usage Pattern

Create SchemaField(...) values next to the dataclass fields they describe and store SchemaField(...).to_metadata() in the dataclass field metadata. Use SchemaChoice(value=..., label=...) when a serialized token needs human-readable display text such as "Hess-Smith". Use schema_field_metadata(cls) when a GUI or editor needs to inspect the dataclass-level metadata contract.