Skip to content

Conversation

@bendrucker
Copy link
Member

@bendrucker bendrucker commented Oct 16, 2025

Adds a new rule to enforce Terraform's official JSON syntax, which requires a root object rather than an array. HCL supports both syntaxes:

https://github.com/hashicorp/hcl/blob/main/json/spec.md

The HCL syntax-agnostic information model defines a body as an abstract container for attribute definitions and child blocks. A body is represented in JSON as either a single JSON object or a JSON array of objects.

Terraform's documentation specifies that JSON configurations should use a root object with keys for each block type (resource, variable, output, etc.). It inherits HCL's support for arrays and flattening them, but it never documents this.

Changes

  • Adds terraform_json_syntax rule that detects array syntax at the root of .tf.json files.
  • Uses encoding/json to unmarshal and check the root type structure.
  • Emits a warning when array syntax is detected, pointing users to the official Terraform JSON syntax documentation.

Testing

  • Added unit tests covering valid object syntax, invalid array syntax, non-JSON files, and malformed JSON.

References

Adds a new rule to enforce Terraform's documented JSON syntax
(object at root) over HCL's also-valid array syntax.

While HCL supports array syntax at the root, Terraform documentation
specifies using a JSON object. This rule warns users when they use
array syntax, helping them follow Terraform's standard.

- Enabled by default (warning severity)
- Included in 'all' and 'recommended' presets
- Comprehensive tests and documentation
@bendrucker bendrucker marked this pull request as ready for review October 16, 2025 02:48
@bendrucker bendrucker requested a review from wata727 October 16, 2025 02:48
@bendrucker bendrucker changed the title feat: add terraform_json_syntax rule add terraform_json_syntax rule Oct 16, 2025
- Refactor canMergeValues to use cleaner recursive pattern
- Simplify merge decision logic in the fixer
- Maintain all existing behavior while improving code clarity
@bendrucker
Copy link
Member Author

Trimmed the error and added autofix. It's a lot of code compared to just handling detection, but it's also a major annoyance/confusion to eliminate for users.

@bendrucker bendrucker requested a review from wata727 October 17, 2025 02:51
@bendrucker bendrucker merged commit c646c32 into main Oct 17, 2025
6 checks passed
@bendrucker bendrucker deleted the terraform-json-syntax-rule branch October 17, 2025 23:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants