Contract schemas

A contract schema describes the shape of the data that passes between the steps of an automation: which fields arrive, what type each one is, and which must be present. Steps that ask an AI model, run your own code or call an outside system use a contract to know exactly what goes in and what comes back.

What a contract schema is

A contract schema is a named set of fields, much like a form, except that nobody ever fills it in. Its only job is to type data. It says what a step in an automation should expect to receive, or what it must hand back.

Each field in a contract has a name, a type, and a setting for whether it is required. When an automation runs, the data a step receives or returns is checked against its contract:

• A required field that is missing, or a value of the wrong type, stops the step with an error you can follow up in the run history.
• Fields the contract does not mention are dropped, so the steps that follow see only the fields you declared.

The top-level fields of a contract become the typed inputs or outputs of the step that uses it. Each one appears on the step as its own connection point, ready to wire to other steps, and a field's description travels with it.

Contracts are kept apart from the data schemas behind your forms. A form's data schema describes the entries your team logs, and you change it by editing the form. A contract never backs a form and never describes an entry. The contracts list shows contracts only, and if you open a form's data schema in the contract editor, Pyron points you back to the form builder instead.

Shapes a contract can hold

The data automations exchange with other systems is often nested, so a contract can describe more than the flat questions of a form. Alongside the familiar field types — text, numbers, dates, true-or-false values and choice lists — a contract can hold:

• An object: a group of named fields inside one field, such as an address with a street, a town and a postcode.
• A list of objects: a repeating group, such as the line items on an order.
• A map: an open set of named values whose names are not known in advance.

Conditional fields and shared choice lists work in a contract the same way they do in a form. See conditional questions for how conditions reveal fields.

Editing one

Contracts live in the Setup area, alongside the other tools for building automations. The contracts section lists every contract by name, with when it was last updated.

To create a contract:

1. In Setup, open the contracts section and select New contract.
2. Type its name where the header says Untitled contract: a name that says what the data is. The name is what you choose from when you set up a step.
3. Add a field for each piece of data, and set each field's label, key, type and whether it is required.
4. An object or a list of objects shows its own fields underneath it — "Fields of Address", "Each item of Lines" — with its own Add field.
5. Save the contract.

To change a contract, select it in the list, make your changes and save. Each row's actions menu also opens or deletes that contract. If the contracts section does not appear in Setup, your role does not include it; see roles and permissions.

The editor is the same one you use to build forms, with a few differences that follow from a contract's job:

• Fields start out required. Mark a field optional when the data can legitimately leave it out.
• Each field has a Key in its settings, and keys are matched letter for letter against the data, so set each key exactly as the outside system or your code names it, capitalisation included. If a service sends orderId, the key is orderId.
• You can limit a value, under Constraints in its settings: a minimum or maximum length, a pattern text must match, a lowest or highest number, or a minimum or maximum number of items in a list. Limits are checked when the automation runs, not while you type a fixed value into a step's settings.
• Where a form has Preview, a contract has JSON: a read-only view of the contract's definition, because there is nothing to fill in.

Renaming and removing fields

Until you first save a contract, you can rename and remove its fields freely. Once it is saved, its top-level field names are the names automations connect to, so changing one can break a step that depends on it.

When you rename or remove a top-level field in a saved contract, Pyron checks which automations use the contract:

• If none do, the change goes ahead straight away.
• If some do, Pyron names them, warns that the change may break their wiring, and asks you to confirm. After you confirm, open each of those automations and reconnect the affected steps.

Fields nested inside an object or a list of objects can be renamed without this check.

Deleting a contract

You can delete a contract from its row's menu, and Pyron asks you to confirm because the deletion is permanent. A contract that an automation uses cannot be deleted. The confirmation explains why and stays open, so remove the contract from those steps first and then delete it.

Where contracts are used

Contracts are picked in the settings of the automation steps that exchange structured data. The picker in those settings lists your contracts only, never the data schemas behind forms. Once you choose one, the step's inputs or outputs redraw to match its top-level fields.

Each of these steps uses its contract a little differently:

• Asking an AI model: you can choose a shared contract, or write the shape on the step itself. Leave the input shape unset and the step takes one untyped input; ask for a structured answer and its shape becomes the step's outputs.
• Running your own code: the output contract is required, and the value your code returns is checked against it. The input contract is optional, so leave it empty when your code reads nothing in.
• Calling an outside system: the reply is checked against the contract, and its fields become outputs you can wire onward. When the step uses an operation from a saved outbound connection, the reply's shape comes from that operation, so you do not choose a contract.
• Fetching page by page: every item is checked against the contract, and the contract also types the combined list of results.

For how to add these steps and wire them together, see the building blocks and building an automation. The automation steps catalog lists every step and its settings.