cloudformation-schema-go

cloudformation-schema-go

Go types for CloudFormation specifications, intrinsic functions, template parsing, enum validation, registry schema access, and code generation utilities.

Shared foundation for:

• wetwire-aws - Declarative IaC in Go
• cfn-lint-go - CloudFormation linter in Go

Packages

spec/

CloudFormation Resource Specification types and fetching.

import (
    "time"
    "github.com/lex00/cloudformation-schema-go/spec"
)

// Download and cache the CF spec (use nil for defaults)
cfSpec, err := spec.FetchSpec(nil)

// Or with custom options
cfSpec, err := spec.FetchSpec(&spec.FetchOptions{
    CacheDir: "/custom/cache",
    MaxAge:   24 * time.Hour,  // Re-download if cache older than 24h
})

// Look up resource types
bucket := cfSpec.GetResourceType("AWS::S3::Bucket")
required := bucket.GetRequiredProperties()

intrinsics/

CloudFormation intrinsic functions with JSON marshaling.

import "github.com/lex00/cloudformation-schema-go/intrinsics"

// Intrinsic functions
ref := intrinsics.Ref{LogicalName: "MyBucket"}
getAtt := intrinsics.GetAtt{LogicalName: "MyRole", Attribute: "Arn"}
sub := intrinsics.Sub{String: "${AWS::Region}-bucket"}

// Pseudo-parameters
region := intrinsics.AWS_REGION
accountID := intrinsics.AWS_ACCOUNT_ID

template/

Parse CloudFormation YAML/JSON templates to intermediate representation.

import "github.com/lex00/cloudformation-schema-go/template"

// Parse a template file
tmpl, err := template.ParseTemplate("template.yaml")

// Access resources
for name, resource := range tmpl.Resources {
    fmt.Printf("%s: %s\n", name, resource.ResourceType)
}

// Reference graph for dependency analysis
deps := tmpl.ReferenceGraph["MyFunction"]  // ["MyRole", "MyBucket"]

enums/

Enum constants and validation, generated from aws-sdk-go-v2.

import "github.com/lex00/cloudformation-schema-go/enums"

// Use constants for IDE autocomplete
runtime := enums.LambdaRuntimePython312

// Validate enum values
allowed := enums.GetAllowedValues("lambda", "Runtime")
valid := enums.IsValidValue("lambda", "Runtime", "python3.12")

// List all services with enums
services := enums.Services()  // ["accessanalyzer", "acm", ...]

// List all enum names for a service
enumNames := enums.GetEnumNames("lambda")  // ["Architecture", "Runtime", ...]

registry/

CloudFormation Resource Provider Schemas (JSON Schema Draft-07) — per-resource schemas with property constraints for all 1500+ resource types.

import "github.com/lex00/cloudformation-schema-go/registry"

// Get the default manager (uses bundled schemas)
mgr := registry.DefaultManager()

// Look up a resource schema
rs, err := mgr.GetResourceSchema("AWS::Lambda::Function")
if err != nil {
    log.Fatal(err)
}

// Resolve a property by dot-separated path
prop := rs.ResolveProperty("FunctionName")
if prop != nil {
    fmt.Println("Pattern:", prop.Pattern)
    fmt.Println("MinLength:", prop.MinLength)
    fmt.Println("MaxLength:", prop.MaxLength)
}

// Resolve nested properties
codeProp := rs.ResolveProperty("Code.S3Bucket")

// Check required properties
fmt.Println("Required:", rs.Required) // ["Code", "Role"]

// Read-only properties (JSON pointer format)
fmt.Println("ReadOnly:", rs.ReadOnlyProperties) // ["/properties/Arn", ...]

// Check if a resource type is known
exists, _ := mgr.HasResourceSchema("AWS::S3::Bucket")

// List all resource type names
names, _ := mgr.ResourceTypeNames()
fmt.Println(len(names)) // ~1500+

Schemas are sourced from the CloudFormation Resource Provider Schema ZIP archive published by AWS. They are bundled via go:embed so no network access is needed at runtime.

codegen/

Utilities for code generation: case conversion, identifier sanitization, and topological sorting.

import "github.com/lex00/cloudformation-schema-go/codegen"

// Case conversion
codegen.ToSnakeCase("BucketName")     // "bucket_name"
codegen.ToPascalCase("bucket_name")   // "BucketName"

// Go keyword handling
codegen.IsGoKeyword("type")           // true
codegen.IsGoKeyword("bucket")         // false

// Identifier sanitization (ensures valid Go identifiers)
codegen.SanitizeGoIdentifier("123start")   // "_123start"
codegen.SanitizeGoIdentifier("with-dash")  // "withdash"
codegen.SanitizeGoIdentifier("type")       // "type_"

// Topological sort for dependency ordering
nodes := []string{"A", "B", "C"}
deps := map[string][]string{"A": {"B"}, "B": {"C"}, "C": {}}
sorted := codegen.TopologicalSort(nodes, func(n string) []string {
    return deps[n]
})
// Result: ["C", "B", "A"] (dependencies first)

Installation

go get github.com/lex00/cloudformation-schema-go

Regenerating Enums

Enum constants are generated from aws-sdk-go-v2:

go generate ./enums/...

Regenerating Registry Schemas

Registry schemas are downloaded from the AWS CloudFormation Schema ZIP archive:

go generate ./registry/...

This downloads the latest schemas from https://schema.cloudformation.us-east-1.amazonaws.com/CloudformationSchema.zip and extracts them to registry/schemas/.

License

MIT - See LICENSE for details.