HCL vs. JSON: Configuration language uses, pros and cons

Importance of HCL and JSON

HashiCorp developed HCL to use with its Terraform configuration management tool.

HCL and JSON are suitable for specific infrastructure as code (IaC) scenarios. For example, HCL works with on-premises and cloud configurations, including infrastructure devices, software-defined networking and PaaS. Organizations that use the Terraform configuration management tool use HCL.

JSON’s primary role is to transfer data between systems, such as servers and web applications. Other uses include the following:

• Configuration management. JSON is used for application and system configurations in IaC scenarios, including settings, parameters and preferences.
• Storage of structured data in NoSQL databases. JSON documents take advantage of NoSQL’s flexibility and scalability.
• Data imports and exports. JSON’s flexibility and readability are useful for lightweight data transfers.
• Log reporting. JSON documents provide an easy way to consolidate and parse log file events and performance data.

JSON and HCL are often contrasted against YAML, a configuration management language ideal for products like Ansible. Any of the three may be viable in various uses.

JSON syntax

The heart of JSON’s structure is key-value pairs, found within braces. Keys are strings enclosed in double quotes, unique to the document and typically written with underscore characters rather than spaces. Values are strings, numbers, Booleans, objects (in braces), arrays (in brackets) or null values — similar to the data types that HCL supports.

JSON files typically end with .json. JSON files do not include comments, which can make settings difficult to understand.

JSON’s key-value format enhances its readability. Consider the following pairs:

appName: App1
appVersion: 1.2.3

This example uses Boolean values to enable or disable features:

logging: true

Finally, consider this set of database instructions:

"host": "localhost",
"port": "5000",
"username": "dbadmin",
"password": "Pa$$w0rd",

HCL syntax

HCL defines blocks with braces. These blocks are configuration elements. Like JSON, HCL uses key-value pairs within each block. This capability enables HCL to define resources and similar configurations, which identifies them by strings, numbers, Booleans and other data types.

HCL uses the .hcl or .tf file extension. It supports comments with JavaScript delimiters. Begin single-line comments with two forward slashes. Multiline comments start with /* and end with */ enclosures.

HCL is JSON-compatible. They both use key pairs, though HCL has a few that JSON does not. They use the same types of key pairs, including Booleans and numbers, but under a different format. HCL uses the equal sign, while JSON uses the colon. These configuration files are similar and generally satisfy the same purposes. However, HCL is fully compatible with JSON, while JSON is not fully compatible with HCL.

Work with JSON and HCL files

JSON and HCL documents are text files, so nearly any authoring tool works with them. Use text editors, not word processors. Even simple editors, like Vim, have options for JSON plugins.

Dedicated tools enhance capabilities with features like syntax highlighting, error checking and formatting. Editing tools to consider for JSON include the following:

• Jq. A lightweight and flexible command-line tool that processes JSON files, including structuring, authoring and searching with familiar Linux features.
• JSON Editor Online. An editor that includes validation capabilities.
• JSONMate. A powerful and user-friendly online JSON editor.

Editing tools for HCL include the following:

• Atom. An HCL editor that offers syntax highlighting.
• Hcledit. A command-line editor for HCL files.

Some tools can edit JSON and HCL documents. However, some tools require plugins or extensions to work with HCL. Compatible tools for both configuration files include the following:

• IntelliJ IDEA.
• Notepad++.
• Sublime Text.
• Visual Studio Code.

Many of these authoring tools include validation capabilities. Think carefully before placing sensitive JSON code in online validators.

The editors above often alert users to syntax and structural errors. If the file is not original, use JSON validators — or Terraform for HCL — to check the syntax and structure of existing files and identify mistakes before they get into the production code. Free online validators include the following:

• JSON Formatter & Validator.
• JSONLint.
• Scaler’s JSON Validator.

File security

Neither HCL nor JSON includes built-in file security. Best practices for file security include the following:

• Use HCL or JSON files from trusted sources.
• Evaluate configuration file contents to ensure you know what each setting does.
• Use version control to maintain current settings.
• Test configuration files carefully.
• Utilize file encryption to protect files.

Advantages and disadvantages

JSON’s simple structure and smaller file size enable systems to transfer quicker. This makes JSON useful for data exchanges and simple configurations over complex and extensive configuration files, like YAML and XML.

JSON involves less coding and is often easier to troubleshoot than some other formats. It uses JavaScript syntax with a few notable considerations. JSON does not support comments like HCL does. JSON also ignores white spaces, whereas formats such as YAML rely on them. JSON’s strict adherence to syntax rules may make it difficult to author and troubleshoot. However, those already familiar with JavaScript will likely become comfortable with JSON.

Admins dedicated to the HashiCorp tools, such as Terraform and Vault, will quickly become familiar with HCL. HCL maps well to JSON, which makes file conversions simple and reliable. Note that HCL does work with non-HashiCorp utilities.

Use JSON to manage data or pass information between servers and web apps. Look to HCL, YAML or XML to manage extensive multi-cloud or hybrid cloud environments.

Damon Garn owns Cogspinner Coaction and provides freelance IT writing and editing services. He has written multiple CompTIA study guides, including the Linux+, Cloud Essentials+ and Server+ guides, and contributes extensively to TechTarget Editorial, The New Stack and CompTIA Blogs.