The Type System

Scriptum is statically typed. Every input, output, stream field, and env var declares a type, and the compiler tracks the type of every step binding through the whole program. This section covers the primitive types, the list<T> container, inline object shapes, user-declared enums, and constraints.

This page covers the foundations — primitives, lists, and object shapes. The two narrower topics each have their own page:

• Enums — declaring and using reusable, closed sets of allowed values.
• Constraints — numeric, string, and list validation rules you attach to a field type.

Primitive types

Field declarations accept these built-in primitives. Several have aliases (shown in parentheses) that resolve to the same type.

Declaring each is just name : type:

input
  topic        : text
  depth        : number = 3
  max_results  : integer = 20
  verbose      : boolean = false
  created_at   : timestamp
  payload      : binary
  metadata     : object = {}

A bare object is untyped — it accepts any JSON value and the compiler does not validate field access on it (you must use ? or ??, see Expressions & References). Use a typed object shape (below) when you know the structure.

Lists: list<T>

list<T> is the container type. The element type T can be any primitive, an object shape, an enum, or another list.

input
  tags     : list<text>
  scores   : list<number>
  matrix   : list<list<number>>

output
  sources  : list           -- bare `list` is shorthand for list<any>

A bare list (no <T>) is equivalent to list<any> — an untyped list. Prefer list<text> or a typed object element when you can.

Lists of objects

A list<object> output can declare the element’s object schema with indented child fields:

output
  results : list<object>
      title     : text
      url       : text
      relevance : number

The compiler then validates results[0].title and friends against this shape.

Inline object shapes

You can declare a typed object inline by nesting named fields. This gives you field-level validation on structured values.

output
  report : object
      summary  : text
      word_count : integer
      tags       : list<text>

How types flow

Tool inputs and outputs are typed too (every tool declares a schema). The compiler converts those schemas into the same type representation and propagates types across the whole script: a binding takes its type from the tool’s output schema, an each loop variable takes the element type of the collection, and so on. This is what lets the compiler catch a bad field access or a type-mismatched input before the thread runs. The mechanics of references and field access are covered next in Expressions & References.

Next: closed value sets with Enums, and validation rules with Constraints.