Documentation

Structs

Structs are nominal typed data containers for type-safe data passing. Unlike schemas (used for resource configurations), structs are general-purpose data structures.

Basic Syntax

Block Style

struct StructName {
    type propertyName
    type propertyWithDefault = defaultValue
}

Inline Style

struct Point { number x, number y }

Examples

Simple Struct

struct Point {
    number x
    number y
}

struct Rectangle {
    number width
    number height
    number x = 0
    number y = 0
}

Struct with Various Types

struct User {
    string name
    string email
    number age
    boolean active = true
    string[] roles = []
}

Instantiation

Constructor Syntax

Create struct instances by calling the struct name as a function:

struct Point { number x, number y }

// Positional arguments
var p1          = Point(10, 20)

// With defaults (if defined)
struct Config {
    number port = 8080
    string host = "localhost"
}

var c1          = Config()           // Uses all defaults
var c2          = Config(3000)       // port=3000, host="localhost"
var c3          = Config(3000, "0.0.0.0")  // port=3000, host="0.0.0.0"

Auto-Coercion from Object Literals

When a variable has an explicit struct type, object literals are automatically converted:

struct Config {
    number port = 8080
    string host = "localhost"
}

// Auto-coerced to Config instance
var Config c    = { port: 3000 }
// c.host == "localhost" (default)
// c.port == 3000 (overridden)

var Config full = { port: 443, host: "api.example.com" }

Accessing Properties

struct Point { number x, number y }

var p      = Point(10, 20)

var xCoord = p.x  // 10
var yCoord = p.y  // 20

Mutability

Struct instances are mutable - properties can be changed after creation:

struct Point { number x, number y }

var p = Point(10, 20)
p.x   = 100  // Valid - mutates the property
p.y   = 200

// p is now Point(100, 200)

Structs with Inputs and Outputs

Structs work fully with inputs and outputs in both files and components.

Struct Inputs

struct Point { number x, number y = 0 }

// In a component
component Shape {
    input Point origin                    // Required struct input
    input Point center            = Point(0, 0)      // With default
    input Point[] corners                 // Array of structs
}

// Standalone in a file
input Point origin                = Point(10, 20)

Struct Outputs

struct Point { number x, number y }

// In a component
component Shape {
    input number width  = 100
    output Point center = Point(width/2, width/2)  // Computed from inputs
}

// Standalone in a file
output Point center     = Point(50, 50)
output Point[] corners  = [Point(0,0), Point(100,100)]

Auto-Coercion in Inputs

input Point origin = { x: 10, y: 20 }  // Auto-coerced to Point

Structs in Schemas and Resources

struct Point { number x, number y }

schema Shape {
    Point origin
}

resource Shape myShape {
    origin = Point(10, 20)      // Constructor syntax
    // OR
    origin = { x: 10, y: 20 }   // Object literal (auto-coerced)
}

Nested Struct Inputs/Outputs

struct Point { number x, number y }
struct Rectangle { Point topLeft, Point bottomRight }

component Canvas {
    input Rectangle bounds = Rectangle(Point(0,0), Point(100,100))
    output Point center    = Point(
        (bounds.topLeft.x + bounds.bottomRight.x) / 2,
        (bounds.topLeft.y + bounds.bottomRight.y) / 2
    )
}

Property Decorators

@description

struct ServerConfig {
    @description("Port number for the server")
    number port = 8080

    @description("Hostname to bind to")
    string host = "localhost"
}

@cloud

Mark properties as cloud-generated (set by provider):

struct AWSResource {
    string name

    @cloud
    string arn  // Set by cloud provider, cannot be initialized
}

Validation Decorators

struct UserInput {
    @nonEmpty
    @minLength(3)
    string username

    @minValue(0)
    @maxValue(120)
    number age

    @validate(regex: "^[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}$")
    string email
}

Nested Structs

Structs can contain other structs:

struct Address {
    string street
    string city
    string country
    string postalCode
}

struct Person {
    string name
    number age
    Address address
}

var person = Person(
    "John Doe",
    30,
    Address("123 Main St", "New York", "USA", "10001")
)

var city   = person.address.city  // "New York"

Struct vs Schema

FeatureStructSchema
PurposeData containersResource definition
Type SystemNominal (name matters)Structural
InstantiationConstructor callVia resources
Auto-coercionYes (from objects)No
MutabilityMutableDepends on resource
// Nominal typing - names must match
struct Point { number x, number y }
struct Coordinate { number x, number y }

var Point p = Point(10, 20)      // OK
var Point c = Coordinate(10, 20) // ERROR: type mismatch

Arrays of Structs

struct Point { number x, number y }

var points  = [
    Point(0, 0),
    Point(10, 20),
    Point(30, 40)
]

for point in points {
    var sum = point.x + point.y
}

Structs as Function Parameters

struct Rectangle {
    number width
    number height
}

fun area(Rectangle rect) number {
    return rect.width * rect.height
}

var r = Rectangle(10, 20)
var a = area(r)  // 200

Next: Learn about Functions - reusable blocks of code.

On this page

Basic SyntaxBlock StyleInline StyleExamplesSimple StructStruct with Various TypesInstantiationConstructor SyntaxAuto-Coercion from Object LiteralsAccessing PropertiesMutabilityStructs with Inputs and OutputsStruct InputsStruct OutputsAuto-Coercion in InputsStructs in Schemas and ResourcesNested Struct Inputs/OutputsProperty Decorators@description@cloudValidation DecoratorsNested StructsStruct vs SchemaArrays of StructsStructs as Function Parameters