Cue Kind Definition

myString:  string
myInt:     int
myFloat:   float
myBool:    bool
myBytes:   bytes
myNull:    null

// String enum
status: "pending" | "active" | "archived"

// Type or null (optional)
description: string | null

// Multiple types
value: int | string

// Optional string with default
description: string | *""

// Optional bool with default
enabled: bool | *true

// Optional int with default
replicas: int | *1

// Optional enum with default
priority: "low" | "medium" | "high" | *"medium"

// Numeric bounds
port:    int & >=1 & <=65535
count:   int & >=0
percent: float & >=0 & <=100

// String length
name:    string & strings.MinRunes(1) & strings.MaxRunes(63)

// Regex patterns
slug:    string & =~"^[a-z][a-z0-9-]*$"
email:   string & =~"^[^@]+@[^@]+\\.[^@]+$"
semver:  string & =~"^v?[0-9]+\\.[0-9]+\\.[0-9]+"

// Non-empty string
title:   string & != ""

// List of any type
items: [...]

// List of strings (scalars — inline fine)
tags: [...string]

// List of objects — always use a #Definition, never inline the struct
// ❌ Avoid:
// rules: [...{ path: string, method: string }]

// ✅ Preferred:
#Rule: {
    path:   string
    method: "GET" | "POST" | "PUT" | "DELETE"
}
rules: [...#Rule]

// Fixed-size list
pair: [string, int]  // exactly 2 elements: a string and an int

// Map from string to string
labels: {[string]: string}

// Map from string to any
annotations: {[string]: _}

// Nested struct
metadata: {
    name:      string
    namespace: string | *"default"
    labels:    {[string]: string} | *{}
}

// Required
title: string

// Optional (may be absent)
description?: string

// Optional with a specific type
config?: {
    timeout: int | *30
}

import "time"

{
    timeField: string & time.Time
}

import "strings"

name: string & strings.MinRunes(1) & strings.MaxRunes(253)

schema: {
    #Config: {
        timeout: int & >=1 & <=3600 | *30
        retries: int & >=0 & <=10   | *3
    }

    #Rule: {
        path:   string
        weight: int & >=0 & <=100
    }

    #ResourceRef: {
        name:      string & != ""
        namespace: string | *"default"
    }

    spec: {
        config:    #Config
        rules:     [...#Rule] | *[]
        targetRef: #ResourceRef
    }
}

schema: {
    // #Definitions for structs that are large, reused, or appear in lists
    #Config: {
        timeout: int & >=1 & <=3600 | *30
        retries: int & >=0 & <=10   | *3
    }

    #Rule: {
        path:   string
        weight: int & >=0 & <=100
    }

    spec: {
        // Required scalar fields
        title:    string & != ""
        category: "issue" | "feature" | "bug"

        // Optional scalars with defaults
        description: string | *""
        priority:    "low" | "medium" | "high" | *"medium"
        enabled:     bool | *true
        count:       int & >=0 | *0

        // Named definition for a larger/reused struct
        config: #Config

        // Small, simple, single-use struct — inline is fine
        contact: {
            name:  string
            email: string
        }

        // List of scalars (inline fine)
        tags: [...string] | *[]

        // List of objects — prefer a named definition
        rules: [...#Rule] | *[]

        // Map (always inline)
        labels: {[string]: string} | *{}
    }

    // status is written only by the operator/reconciler, never by users.
    status: {
        lastObservedGeneration: int | *0
        state:   string | *""   // e.g. "Ready", "Provisioning", "Error"
        message: string | *""
        // e.g. name of a resource provisioned by the reconciler:
        // provisionedConfigMap: string | *""
    }
}

## Common Mistakes

**Don't use `?` on spec fields that need defaults in Go:**
```cue
// Bad — Go will get zero value, hard to distinguish "not set" from empty
description?: string

// Better — explicit default
description: string | *""

// Bad — this should be in status
spec: {
    lastUpdated: string  // server writes this
}

// Good
status: {
    lastUpdated: string
}

// Bad — accepts empty string
name: string

// Good — rejects empty string at API level
name: string & != ""