Schemas

Schemas define structured data types for resource configurations. They provide type safety and validation for cloud resource properties.

Basic Syntax

schema SchemaName {
    type propertyName
    type propertyWithDefault = defaultValue
}

Simple Schema

schema DatabaseConfig {
    string host
    number port = 5432
    boolean ssl = true
}

Schema with All Types

schema ServerConfig {
    // Required properties (no default)
    string name
    string region
    // Optional properties (with defaults)
    string instanceType     = "t3.micro"
    number port             = 8080
    boolean public          = false
    // Array property
    string[] securityGroups = []
    // Object property
    object tags             = {}
}

Using Schemas with Resources

Schemas define the type of a resource:

schema AwsS3Bucket {
    string name
    string region      = "us-east-1"
    boolean versioning = false
}
resource AwsS3Bucket photos {
    name               = "my-photos-bucket"
    versioning         = true
}

Property Decorators

@cloud

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

schema AwsInstance {
    string name                      // User-set
    @cloud string arn                // Cloud-generated, not importable
    @cloud(importable) string id     // Cloud-generated, can be used for import
    @cloud string publicIp           // Cloud-generated
}
resource AwsInstance server {
    name                = "web-server"
    // arn, id, publicIp are NOT set here
    // They come from AWS after apply
}
// Access cloud-generated properties
output string serverArn = server.arn
output string serverId  = server.id

@allowed

Restrict property values to a whitelist:

schema ServerConfig {
    @allowed(["default", "dedicated", "host"])
    string tenancy    = "default"
    @allowed(["gp2", "gp3", "io1", "io2"])
    string volumeType = "gp3"
    @allowed([80, 443, 8080, 8443])
    number port       = 80
}

@description

Add documentation to properties:

schema DatabaseConfig {
    @description("The database hostname or IP address")
    string host
    @description("Port number for database connections")
    number port = 5432
    @description("Enable SSL/TLS encryption")
    boolean ssl = true
}

@sensitive

Mark sensitive properties:

schema DatabaseConfig {
    string host
    number port = 5432
    @sensitive
    string password
    @sensitive
    string connectionString
}

Validation Decorators

schema UserConfig {
    @minLength(3)
    @maxLength(50)
    string username
    @minValue(18)
    @maxValue(120)
    number age
    @validate(regex: "^[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}$")
    string email
    @nonEmpty
    string[] roles
}

Schema Inheritance

Schemas can reference other schemas:

schema NetworkConfig {
    string vpcId
    string subnetId
    string[] securityGroups = []
}
schema ServerConfig {
    string name
    string instanceType     = "t3.micro"
    NetworkConfig network  // Nested schema
}
resource ServerConfig server {
    name                    = "web-server"
    network                 = {
        vpcId: "vpc-123",
        subnetId: "subnet-456"
    }
}

Inline Style

Schemas can be declared in a single line:

schema Point { number x; number y }
schema Color { number r; number g; number b; number a = 1.0 }

Schema vs Struct

Feature	Schema	Struct
Purpose	Resource configuration	Data containers
Type System	Structural typing	Nominal typing
Instantiation	Via resources	Via constructor
Cloud Properties	Supports `@cloud`	No `@cloud` support
Mutability	Depends on resource	Mutable

Use schemas for cloud resource configurations. Use structs for general data structures in your code.

Next: Learn about Structs - nominal typed data containers.