Data Schema

data_schema(...) declares fields for structured readout results.

It is used when a readout has a custom or open result shape. It supports readout operations; it is not a workflow operation by itself.

Declare a Schema

let gel_schema = data_schema(label = "GelImage", fields = [band_count, signal]);

Arguments:

Argument	Required	Meaning
label	yes	Human-readable structure name.
fields	yes	List of field names allowed in the result.

Use schema_ref

Readout calls use schema_ref to attach the declared result structure.

let obs = img(sample = lane, quantity = ReadoutQuantity.CUSTOMIZED, schema_ref = gel_schema);

schema_ref is required when quantity = ReadoutQuantity.CUSTOMIZED.

It can also be used for supported complex result cases such as physical current readout.

let ms_schema = data_schema(label = "MSCurrent", fields = [current_pulse, arrival_time]);
let obs = phy(sample = detector, quantity = ReadoutQuantity.CURRENT, schema_ref = ms_schema);

Local Data References

data_ref and data_group_ref describe local data with a kind and declared result schema. Their kind parameter uses the DataKind family: OBSERVATION, SEQUENCE_READ and SORT_RECORD. Use qualified members such as DataKind.SEQUENCE_READ; historical kind text remains compatible.

protocol SequenceSummary {
    let schema = data_schema(label = "Sequence", fields = [read_count]);
    let data = data_ref(kind = DataKind.SEQUENCE_READ, schema_ref = schema);
    data.result.read_count = 0;
}

Custom kinds inherit DataKindBase from culsma.domains.data and register through STANDARD_DATA_KINDS.with_type(...) in the same host-managed scope used for observation units. Kind identity does not define result fields or measurement behavior. Results retain textual data_kind; registered extensions additionally retain data_kind_type for their stable identity. This kind is distinct from material ContentKind and ObservationUnit.

Why Declare First

The result shape is declared before use. That keeps later references explicit:

obs.result.current_pulse
obs.result.arrival_time

The schema describes structured result fields. It is not a container, material, or execution step by itself.