buffalo_core.schema.SchemaField

class buffalo_core.schema.SchemaField(value_kind, required, label, order, short_help, default=None, choices=None, minimum=None, maximum=None, exclusive_minimum=None, exclusive_maximum=None, tuple_length=None, min_items=None, max_items=None, item_kind=None, format_hint=None, reference_target=None, collection_add_label=None, collection_item_label_field=None, collection_item_creation_hint=None, collection_key_label=None, collection_key_format_hint=None, notes=None, advanced=False, shown_when=None, enabled_when=None, required_when=None)

Bases: object

Structured machine-readable metadata for one dataclass field.

Notes

This dataclass is a builder for the plain dictionary stored in dataclasses.field(metadata=...). Downstream projects keep their dataclasses as the source of truth while still attaching stable GUI and editor hints in one shared Core format.

Methods

to_metadata()

Return the plain metadata mapping stored in dataclass fields.

Attributes

value_kind	Machine-readable category such as enum, number, or list.
required	Whether the field is required by the schema contract.
label	Human-readable field label for UIs and editors.
order	Suggested stable display ordering for sibling fields.
short_help	Short help text describing the field for direct UI display.
default	Optional default value when one is meaningful for editing.
choices	Optional enum-like choices exposed as structured value/label pairs.
minimum	Inclusive numeric lower bound when one is known.
maximum	Inclusive numeric upper bound when one is known.
exclusive_minimum	Exclusive numeric lower bound when one is known.
exclusive_maximum	Exclusive numeric upper bound when one is known.
tuple_length	Expected tuple length when the field stores a fixed-size tuple.
min_items	Minimum item count when the field stores a collection.
max_items	Maximum item count when the field stores a collection.
item_kind	Machine-readable description of collection item shape or type.
format_hint	Optional formatting hint for text or tuple entry widgets.
reference_target	Optional logical target when the field references named objects.
collection_add_label	Optional add-item button label for collection editors.
collection_item_label_field	Optional item field used as the row label in collection editors.
collection_item_creation_hint	Optional help text for creating new collection items.
collection_key_label	Optional label used for mapping keys in collection editors.
collection_key_format_hint	Optional format hint used for mapping keys in collection editors.
notes	Optional extra machine-usable clarification text.
advanced	Whether the field should default to an advanced editing section.
shown_when	Optional conditions controlling whether a field should be shown.
enabled_when	Optional conditions controlling whether a field should be editable.
required_when	Optional conditions controlling whether a field becomes required.

value_kind: str

Machine-readable category such as enum, number, or list.

required: bool

Whether the field is required by the schema contract.

label: str

Human-readable field label for UIs and editors.

order: int

Suggested stable display ordering for sibling fields.

short_help: str

Short help text describing the field for direct UI display.

default: object | None

Optional default value when one is meaningful for editing.

choices: tuple[SchemaChoice | object, ...] | None

Optional enum-like choices exposed as structured value/label pairs.

minimum: float | int | None

Inclusive numeric lower bound when one is known.

maximum: float | int | None

Inclusive numeric upper bound when one is known.

exclusive_minimum: float | int | None

Exclusive numeric lower bound when one is known.

exclusive_maximum: float | int | None

Exclusive numeric upper bound when one is known.

tuple_length: int | None

Expected tuple length when the field stores a fixed-size tuple.

min_items: int | None

Minimum item count when the field stores a collection.

max_items: int | None

Maximum item count when the field stores a collection.

item_kind: str | None

Machine-readable description of collection item shape or type.

format_hint: str | None

Optional formatting hint for text or tuple entry widgets.

reference_target: str | None

Optional logical target when the field references named objects.

collection_add_label: str | None

Optional add-item button label for collection editors.

collection_item_label_field: str | None

Optional item field used as the row label in collection editors.

collection_item_creation_hint: str | None

Optional help text for creating new collection items.

collection_key_label: str | None

Optional label used for mapping keys in collection editors.

collection_key_format_hint: str | None

Optional format hint used for mapping keys in collection editors.

notes: str | None

Optional extra machine-usable clarification text.

advanced: bool

Whether the field should default to an advanced editing section.

shown_when: tuple[SchemaCondition, ...] | None

Optional conditions controlling whether a field should be shown.

enabled_when: tuple[SchemaCondition, ...] | None

Optional conditions controlling whether a field should be editable.

required_when: tuple[SchemaCondition, ...] | None

Optional conditions controlling whether a field becomes required.

to_metadata()

Return the plain metadata mapping stored in dataclass fields.

Return type:

SchemaFieldMetadata