Type System And Constraints

Last validated: 2026-05-14

This page covers declaration types for input, output, stream, and typed env fields.

Field Syntax

General form:

name : type [constraint ...] [= default] [-- comment]

Examples:

input
  artifact_id : text length(1, 256) pattern("^[a-z][a-z0-9_-]*$")
  top_k : number range(1, 1000) = 10

Supported Type Forms

Primitive

text
number
boolean
integer
float

Parser accepts primitive names as identifiers. Runtime validation decides which primitives are meaningful for downstream execution.

Parameterized

list<text>
list<number>
map<text, number>

Bare list is allowed and treated as list<any>.

Object

object is accepted as an untyped object (any) in current parser.

metadata : object

For richer shape declaration, use list<object> patterns with nested fields where supported (mainly output/stream declarations).

Enum References

User enums are declared at top level and referenced by name.

enum SparseMode = None | Bm25 | External

input
  sparse_mode : SparseMode = None

Note: enum references are resolved during validation (declared name is rewritten from primitive-like type into enum reference type).

Enum Declarations

Inferred Base

enum Dimensions = 128 | 256 | 512 | 1024
enum ApiVersion = "v1" | "v2" | "v3"

Explicit Base

enum HttpStatus : integer = 200 | 201 | 400 | 404 | 500
enum Threshold : number = 0.25 | 0.35 | 0.50
enum Stage : text = "dev" | "staging" | "prod"

Rules:

• Variants must be homogeneous by category.
• Text variants can be bare identifiers or quoted strings.
• Numeric variants can be integer or float.
• Mixing text and numeric variants is rejected.
• Declared base must match inferred variant category (integer variants can widen into declared number).

Constraint Clauses

Constraints appear after type and before default.

Supported clauses:

• range(min, max)
• min(n)
• max(n)
• length(min, max)
• pattern("regex")
• min_items(n)
• max_items(n)
• unique

Examples:

input
  score : number range(0.0, 1.0)
  retries : integer min(0) max(10)
  title : text length(1, 256)
  slug : text pattern("^[a-z0-9-]+$")
  labels : list<text> min_items(1) max_items(20) unique

Defaults

Defaults use expression syntax and are stored as default values in contract metadata.

input
  enabled : boolean = true
  top_k : integer = 20
  tags : list<text> = ["ops", "urgent"]
  cfg : object = { provider: "public", tier: "gold" }

Output/Stream Nested List Object Pattern

In output/stream declarations, list item schemas can be expressed with nested fields.

output
  findings : list
    id : text
    score : number
    category : text

This pattern is parsed as a list of object-like typed items.

Env Typing

env fields can also use type and constraints.

env
  BATCH_SIZE : integer min(1) max(1000) = 64
  API_BASE : text pattern("^https://")

Practical Guidance

1. Keep input/output/stream contracts explicit and constrained.
2. Prefer enums over free-text for finite option sets.
3. Add constraints where retry/approval/runtime safety depends on shape limits.
4. Use defaults only for true optional behavior; keep critical values required.