Schema

All columns in a Table are described by a Schema — specifying the data type, how it’s stored, and how the Dashboard displays and interacts with it. More generally, all Table attributes are described by schemas (inherited from the base Object model), so even the rows themselves have a schema that describes how a single row looks — containing the individual column schemas. The schema you choose for a column determines what you can do with that column: whether the Dashboard renders images, lets you draw bounding boxes, displays label dropdowns, runs dimensionality reduction on embeddings, and so on.

Use Built-in Schemas

For each column, pick a built-in convenience schema. It configures the data type, storage, sample type, and Dashboard integration in one step. Most live as classes under tlc.schemas (e.g. tlc.schemas.ImageSchema, tlc.schemas.CategoricalLabelSchema); annotation columns whose data is backed by a runtime dataclass — bounding boxes, keypoints, segmentations, geometries — are constructed through that dataclass’s schema() classmethod, so the storage type and the column description stay paired:

import tlc
from tlc.data_types import BoundingBoxes2D

schema = {
    "image": tlc.schemas.ImageSchema(),
    "label": tlc.schemas.CategoricalLabelSchema(classes=["cat", "dog"]),
    "embedding": tlc.schemas.Float32Schema(shape=(512,), sample_type="numpy_array"),
    "boxes": BoundingBoxes2D.schema(classes=["cat", "dog"]),
}

See Column Types for the full list of available schemas, their parameters, and Dashboard features.

Built-in schemas unlock Dashboard features

The Dashboard recognizes built-in schema patterns and provides specialized functionality — image rendering, annotation editing, label management, dimensionality reduction, and more. If you build a raw Schema manually, the Dashboard will store and display your data but won’t provide these features.

Stick with built-in schemas unless you have a specific reason not to. See Custom Sample Types for when and how to define your own.

Common Parameters

All built-in schemas share a set of column-level parameters that control how the column appears in the Dashboard:

Parameter	Default	Description
display_name	""	Column header in the Dashboard. If empty, uses the column key from the schema dict.
description	""	Tooltip text shown on hover in the Dashboard.
writable	True	Whether the column is editable in the Dashboard.
visible	True	Whether the column is visible by default (hidden columns can be shown manually).
display_importance	0	Column ordering weight — higher values appear further right. Also subject to the Dashboard’s own ordering heuristics.
default_value	None	Default value for new rows.

schema = {
    "confidence": tlc.schemas.Float32Schema(
        display_name="Model Confidence",
        description="Softmax probability of the predicted class",
        writable=False,
    ),
}

How Storage Works

Convenience schemas automatically configure the right storage pattern for each column. Most columns store data inline (directly in the row). Some schemas — like ImageSchema — store data externally as separate files with URL references in the row. See Bulk Data for details on controlling where externalized files are stored.

Building Schemas from Scratch

Do you need this?

Most users never need to build raw schemas. If a built-in convenience schema covers your data type, use it — you’ll get better Dashboard support and simpler code. This section is for advanced users who need to represent data types not covered by the built-ins.

When no convenience schema fits, you build a Schema directly. A Schema can be atomic (single value) or composite (named sub-schemas):

import tlc

# Atomic — a single integer value
int_schema = tlc.Schema(
    display_name="Label",
    value=tlc.schemas.values.Int32Value(value_min=0, value_max=100),
)

# Composite — combines multiple schemas into a struct
composite_schema = tlc.Schema(
    values={"score": tlc.Schema(value=tlc.schemas.values.Float32Value()), "label": int_schema},
)

Key concepts:

• Atomic schemas have a value attribute — a ScalarValue subclass (Int32Value, Float32Value, StringValue, etc.)

• Composite schemas have a values attribute — a dict[str, Schema] of named sub-schemas

• Dimensionality is described by size0 through size5 attributes of type DimensionNumericValue — a scalar has no size attributes, a 1D array has size0, and so on

See the Schema API reference for the full constructor signature.