JSON configuration alternative in Terraform - Deep Dive

Overview - JSON configuration alternative

What is it?

JSON configuration alternative refers to using a different format instead of JSON to write infrastructure code in Terraform. Terraform supports HashiCorp Configuration Language (HCL), which is designed to be easier for humans to read and write. Instead of JSON's strict syntax, HCL uses a cleaner, more natural style with blocks and attributes.

Why it matters

Using HCL instead of JSON makes writing and understanding infrastructure code simpler and less error-prone. Without this alternative, users would struggle with JSON's verbosity and strict formatting, making infrastructure management harder and slower. This can lead to mistakes that affect cloud resources and costs.

Where it fits

Before learning this, you should understand basic Terraform concepts like providers and resources. After this, you can explore advanced Terraform features like modules, state management, and automation pipelines.

Mental Model

Core Idea

Terraform's JSON alternative, HCL, is a human-friendly language designed to describe infrastructure clearly and simply.

Think of it like...

It's like choosing between writing a letter in formal legal language (JSON) versus writing it as a friendly note (HCL) that is easier to read and understand.

Terraform Configuration Formats
┌───────────────┐       ┌───────────────┐
│   JSON File   │       │   HCL File    │
│ { "resource": {│       │ resource "" { │
│   "aws_s3_bucket": {│   │   bucket = "" │
│     "mybucket": {│     │ }             │
│       "bucket": "mybucket"│ │ }             │
│     }           │       │               │
│   }             │       │               │
│ }               │       │               │
└───────────────┘       └───────────────┘

Build-Up - 6 Steps

1

Foundation

What is Terraform Configuration

Concept: Terraform uses configuration files to define cloud resources.

Terraform configuration files tell Terraform what cloud resources to create and how to set them up. These files can be written in JSON or HCL formats.

Result

You understand that Terraform needs configuration files to work.

Knowing that Terraform requires configuration files is the base for learning how to write them effectively.

2

Foundation

Basics of JSON Format in Terraform

Concept: JSON is a strict, machine-readable format used for Terraform configurations.

JSON uses braces {}, quotes, and commas to organize data. Every key and string must be quoted, and commas separate items. For example, a resource is defined inside nested objects.

Result

You can recognize Terraform JSON configuration structure.

Understanding JSON's strict syntax helps appreciate why alternatives exist.

3

Intermediate

Introduction to HCL Syntax

🤔Before reading on: do you think HCL looks more like code or data? Commit to your answer.

Concept: HCL is a domain-specific language designed to be human-friendly and readable.

HCL uses blocks with labels and attributes without requiring quotes everywhere. It looks more like code with clear sections and assignments, making it easier to read and write.

Result

You can identify HCL syntax and see how it differs from JSON.

Knowing HCL's syntax reduces errors and speeds up writing infrastructure code.

4

Intermediate

Comparing JSON and HCL Side-by-Side

🤔Before reading on: which format do you think is easier to edit by hand? Commit to your answer.

Concept: Comparing both formats highlights the practical benefits of HCL over JSON.

JSON requires many quotes and commas, making it verbose. HCL uses simpler blocks and assignments. For example, defining an AWS S3 bucket is shorter and clearer in HCL.

Result

You see why HCL is preferred for manual editing.

Understanding the differences helps choose the right format for your workflow.

5

Advanced

Using JSON with Terraform Commands

🤔Before reading on: do you think Terraform treats JSON and HCL configurations the same internally? Commit to your answer.

Concept: Terraform can process both JSON and HCL files equivalently during execution.

Terraform accepts JSON files with a .tf.json extension and treats them the same as HCL files. This means you can use JSON if you prefer or generate configurations programmatically.

Result

You know how to use JSON files with Terraform commands.

Knowing Terraform's flexibility allows integration with tools that output JSON.

6

Expert

Why HCL is Terraform's Default Language

🤔Before reading on: do you think HCL was designed mainly for machines or humans? Commit to your answer.

Concept: HCL was created to balance human readability with machine parsing efficiency.

HCL was designed by HashiCorp to make infrastructure code easier to write and understand, reducing errors and improving collaboration. JSON was supported for compatibility but is less user-friendly.

Result

You understand the design philosophy behind Terraform's language choice.

Recognizing design goals explains why HCL dominates Terraform usage today.

Under the Hood

Terraform parses both JSON and HCL files into the same internal data structures before planning and applying changes. The parser converts the configuration text into a graph of resources and dependencies. HCL's syntax is easier for humans but compiles down to the same representation as JSON.

Why designed this way?

HashiCorp created HCL to solve the problem of JSON's verbosity and difficulty for humans to write and maintain. They wanted a language that was both easy to read and write, yet still machine-friendly. JSON support was kept for compatibility with tools that generate JSON automatically.

Terraform Configuration Parsing
┌───────────────┐
│  HCL or JSON  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│  Parser Layer │
│ (HCL & JSON)  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Internal Graph│
│  of Resources │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Terraform Plan│
│  & Apply      │
└───────────────┘

Myth Busters - 3 Common Misconceptions

Quick: Is JSON the only way to write Terraform configurations? Commit to yes or no.

Common Belief: Many think JSON is the only format Terraform accepts.

Reality: Terraform primarily uses HCL, a simpler and more readable language, but also supports JSON as an alternative.

Why it matters: Believing JSON is the only option can discourage beginners who find JSON hard to read and write.

Quick: Does Terraform treat JSON and HCL files differently when applying changes? Commit to yes or no.

Common Belief: Some believe Terraform processes JSON and HCL configurations differently.

Reality: Terraform converts both formats into the same internal representation and treats them equally during execution.

Why it matters: Misunderstanding this can lead to unnecessary format conversions or confusion about behavior.

Quick: Is HCL just JSON with a different name? Commit to yes or no.

Common Belief: Some think HCL is just JSON with a friendlier syntax.

Reality: HCL is a distinct language designed specifically for infrastructure, with features like comments and better readability not possible in JSON.

Why it matters: This misconception limits appreciation of HCL's design benefits and features.

Expert Zone

1

HCL supports expressions and functions, enabling dynamic and reusable configurations beyond static JSON.

2

Terraform's JSON support allows programmatic generation of configurations, useful in automated pipelines or tools.

3

HCL files can include comments, which JSON does not support, aiding collaboration and documentation.

When NOT to use

Avoid using JSON for manual editing or complex configurations because it is verbose and error-prone. Use JSON only when configurations are generated automatically by other software or scripts.

Production Patterns

In production, teams write main configurations in HCL for clarity and maintainability, while using JSON for generated modules or automated workflows. This hybrid approach leverages the strengths of both formats.

Connections

Domain-Specific Languages (DSLs)

HCL is a DSL designed for infrastructure configuration.

Understanding HCL as a DSL helps grasp why it balances human readability with machine parsing, a common goal in many specialized languages.

Code Generation

JSON configurations can be generated by programs automatically.

Knowing that JSON is easy to generate programmatically explains why Terraform supports it alongside HCL.

Human-Computer Interaction (HCI)

HCL improves the user experience of writing infrastructure code.

Recognizing HCL as a usability improvement connects cloud infrastructure to broader HCI principles about designing for humans.

Common Pitfalls

#1 Writing Terraform configurations manually in JSON leads to syntax errors.

Wrong approach:

{
"resource": {
"aws_s3_bucket": {
"mybucket": {
"bucket": "mybucket"
}
}
},
"extra_comma": true
}

Correct approach:

{
"resource": {
"aws_s3_bucket": {
"mybucket": {
"bucket": "mybucket"
}
}
}
}

Root cause:

JSON requires strict syntax with no trailing commas; beginners often add extra commas causing errors.

#2 Trying to add comments in JSON configuration files.

Wrong approach:

{
// This is a comment
"resource": {
"aws_s3_bucket": {
"mybucket": {
"bucket": "mybucket"
}
}
}
}

Correct approach:

# This is a comment
resource "aws_s3_bucket" "mybucket" {
bucket = "mybucket"
}

Root cause:

JSON does not support comments, so adding them causes parsing errors; HCL supports comments.

#3 Assuming Terraform will automatically convert JSON to HCL.

Wrong approach:

Writing JSON files and expecting Terraform to output HCL automatically.

Correct approach:

Manually write or convert JSON to HCL if needed; Terraform treats both formats equally but does not convert between them.

Root cause:

Misunderstanding Terraform's format handling leads to confusion about conversion capabilities.

Key Takeaways

Terraform supports two configuration formats: JSON and HCL, with HCL being the preferred human-friendly language.

HCL is designed to be easier to read and write, reducing errors and improving collaboration compared to JSON.

Terraform parses both formats into the same internal structure, so they behave identically during execution.

JSON is useful for automated generation of configurations, while HCL is better for manual editing and complex setups.

Understanding the differences helps choose the right format for your workflow and avoid common mistakes.