Structure Types and the Type Library

A Structure Type is a named, reusable data shape you define once and use in many places in a thunk. Instead of describing the same object — a contact, an address, a line item — separately on every column and tool that handles it, you define it one time, give it a name, and then refer to it by that name wherever a structured value is needed.

Structure Types build on the idea in Schematized State: the more specific the shape of a property, the better an AI agent can read and fill it in. A Structure Type is the most specific shape you can give a structured value, and it is shared, so every place that uses it stays consistent.

A Structure Type is an object shape with a fixed set of fields. For example, a Contact type might have name, email, and company fields. Each field has a name, a description, and a type of its own.

You define and manage these types in the Type Library tab, alongside the thunk's Properties. A type defined there is available to the whole thunk.

In the Type Library, add a type, give it a meaningful name, and add its fields. For each field you choose a type, just as you do for a work item column:

Every field of a Structure Type is required. Structure Types are strict by design: when the shape is fixed and complete, an AI agent filling in a value cannot leave a field out or invent an extra one, which is what makes the type reliable to read and write. (A type used by a tool that implements an interface may have more fields than the interface lists; see Structure Types in interfaces.) Give each field a clear description for the same reason you would on a column — it tells the agent exactly what belongs there.

A field can itself be a Structure Type, so you can compose larger shapes out of smaller ones. A Contact can have a company field whose type is an Organization; an Order can have an items field that is a list of LineItem.

This is also how you share a common part between types. If several types contain the same sub-shape — say both Customer and Supplier have a mailing address — define that part once as its own type (Address) and reference it from each. The shared part then has one definition, so it stays identical everywhere and changes in one place.

Two rules keep these references sound:

Once a type exists, it appears as a first-class entry in the type picker — alongside the basic types — everywhere a structured value is chosen. You can use it as:

For how lists of values — including lists of a Structure Type — are shown and configured, see Format a list property.

The point of a named type is that there is one definition and one place to change it:

One thing is not rewritten automatically: when you rename or remove a field of a type, step directions or tool instructions that mention that field by name are plain text and keep the old name. After you change a type's fields, re-read the instructions of the steps and tools that use it and update any that name the changed field.

An interface is a list of tool signatures that another thunk can implement. Structure Types follow the same rule there as JSON Objects. Anywhere an interface has an object (an input, a result, or an item in a list), the thunk that implements it can use an object with more fields than the interface lists, and that object can be one of its own Structure Types.

For example, an interface's save_contact tool takes a contact object with name and email. A thunk that implements it can give its save_contact tool a Contact type with name, email, and company. The tool still matches the interface, because the type has every field the interface asks for. A type that is missing one of those fields, or gives one a different type, does not match.

When you put a Structure Type in an interface you are defining, it is copied in as its fields at that moment. Later edits to the type don't change the interface.

A tool that implements an interface depends on the types it uses, so the Type Library protects them. You can add a field to such a type at any time. Removing, renaming, or retyping one of its fields, or deleting the type, is refused while an interface tool uses it, and the message names the tool.

Use a Structure Type for any value that has more than one part. A value with several components — a contact, an address, an invoice line item — should be one Structure Type, not several loose columns and not an untyped blob. It gives you two things at once:

Prefer a Structure Type even when the value is used in only one place today: the coherence and the strict, named shape make it more reliable for an AI agent to fill in, and reuse is there the moment a second place needs the same shape.

When should you not reach for one?

A JSON Object property is the older way to hold a structured value: a shape defined inline on one column, usually from a pasted example. It is anonymous and unshared — two columns holding the same kind of object are two separate shapes that drift — and a custom tool can't take or return it. For a shape you know, a Structure Type gives you everything it does and more, so prefer the Structure Type; if you have a JSON Object property today, you can promote it to a named type.

If a shape seems hard to express as a Structure Type, the answer is almost always to model it strictly, not to fall back to a loose object:

A Structure Type can't form a reference loop, so these self-referential shapes are modeled as a list with a parent reference rather than a type that contains itself.