Why AWS Region Data Doesn't Belong in Your Runtime: Inside jsonmaur/aws-regions

Hook

Every time you import the AWS SDK just to validate a region string or build a dropdown menu, you're pulling in hundreds of thousands of lines of code. There's a better way.

Context

AWS operates 33 regions worldwide, each with cryptic identifiers like 'us-east-1' and 'ap-southeast-2'. Developers constantly need this data: building region selectors in UIs, validating user input, displaying human-readable names, or generating documentation. The obvious solution is importing the AWS SDK, but that's like buying a car dealership when you just need a map.

The traditional approaches all have drawbacks. Hardcoding region lists means updating your code every time AWS launches a new region. Using the AWS SDK adds massive dependencies—the Go SDK alone is over 50MB. Querying AWS APIs at runtime requires credentials and internet connectivity. The jsonmaur/aws-regions repository takes a different path: maintain canonical region data in JSON, then generate zero-dependency libraries for each language. It's build-time data embedding, and it's surprisingly elegant for this use case.

Technical Insight

The architecture centers on a single source of truth: a regions.json file containing structured metadata about every AWS region and availability zone. This isn't just a list of strings—it includes full region names, geographic locations, partition information (standard AWS, GovCloud, China), and availability zone mappings. A shell script reads this JSON and generates idiomatic code for Go and JavaScript, complete with type definitions and accessor functions.

Here's what the generated Go library looks like in practice:

import "github.com/jsonmaur/aws-regions/regions"

// Get all regions
allRegions := regions.GetAll()
for _, region := range allRegions {
    fmt.Printf("%s: %s\n", region.Code, region.Name)
}
// Output: us-east-1: US East (N. Virginia)
//         eu-west-1: Europe (Ireland)

// Validate a region code
if region, ok := regions.Get("us-west-2"); ok {
    fmt.Println(region.Name) // US West (Oregon)
    fmt.Println(region.Zones) // [us-west-2a, us-west-2b, us-west-2c, us-west-2d]
}

// Filter by partition
govCloudRegions := regions.GetByPartition("aws-us-gov")
// Returns only GovCloud regions

The beauty is in what's NOT there. No network calls. No credential management. No AWS SDK initialization. The entire library compiles down to a few kilobytes of data structures embedded in your binary. For a CLI tool that needs region validation, this is the difference between a 5MB binary and a 50MB one.

The code generation script is refreshingly simple—just 50 lines of bash that transforms JSON into Go structs and JavaScript objects. This simplicity is intentional. Complex code generators become maintenance burdens, but this one is transparent enough that contributors can understand and modify it without specialized knowledge. When AWS announces a new region, a maintainer updates the JSON file, runs the generator, and commits the output.

One clever detail: the library includes metadata about availability zone naming quirks. AWS availability zones like 'us-east-1a' don't map to the same physical datacenter across all accounts—AWS randomizes them for load balancing. The library documents which regions have this behavior, preventing a common source of confusion when developers share infrastructure code.

The JavaScript version follows the same pattern but adapts to that ecosystem's conventions:

const regions = require('aws-regions');

// CommonJS or ES modules both work
const usEast = regions.get('us-east-1');
console.log(usEast.name); // 'US East (N. Virginia)'

// Perfect for building UI dropdowns
const regionOptions = regions.getAll().map(r => ({
  value: r.code,
  label: `${r.name} (${r.code})`
}));

This design pattern—canonical data plus code generation—deserves more attention. It's particularly well-suited for relatively stable datasets that need to be consumed in multiple languages. You get type safety, IDE autocomplete, and zero runtime overhead. The tradeoff is accepting that your data might be slightly stale between releases, which is perfectly acceptable for region metadata that changes a few times per year.

Gotcha

The fundamental limitation is freshness. When AWS announced the Hyderabad region (ap-south-2) in November 2022, this library couldn't reflect that until a maintainer updated the JSON and published a new version. If your application absolutely must know about regions the instant AWS launches them, you need a different approach—either the AWS SDK's built-in region data or direct API queries.

Availability zone data is another potential gotcha. The library documents that AZ names are account-specific for certain regions, but it can't solve the underlying problem. If you're building infrastructure automation that depends on precise AZ mappings, you must query AWS directly using the DescribeAvailabilityZones API. This library gives you the regional picture, not account-specific reality. Additionally, the library provides no information about which AWS services are available in which regions—a region existing doesn't mean SageMaker or AppRunner runs there. For service availability, you'll need to consult AWS documentation or use the Service Quotas API.

Verdict

Use if: You're building CLIs, web UIs, or documentation generators that need AWS region metadata without the AWS SDK dependency. It's perfect for input validation, dropdown menus, or anywhere you need human-readable region names. Use it when binary size matters, when you're operating offline, or when you just need a clean data structure without authentication complexity. Skip if: You need real-time region data, require service availability information per region, work in languages other than Go or JavaScript (you'll be parsing JSON manually), or build account-specific tooling where AZ mappings must be precise. Also skip if you're already importing the AWS SDK for other purposes—at that point, use its built-in region constants rather than adding another dependency.