TFNFR40 - Structured JSON and YAML Values

ID: TFNFR40 - Category: Code Style - Structured JSON and YAML Values

Structured values that are passed as JSON or YAML MUST be constructed with jsonencode or yamlencode, rather than a literal JSON or YAML heredoc. Native HCL objects, lists, conditionals, and for expressions keep the structure reviewable and let Terraform perform correct escaping.

body = jsonencode({
  properties = {
    enabled = var.enabled
    names   = [for item in var.items : item.name]
  }
})

Terraform interpolation (${...}), template directives (%{...}), unknown values, and dynamically generated lists or maps are not exceptions: construct the native HCL value and pass it to the encoder.

A heredoc MAY be used only when the value is not JSON or YAML, or when the receiving system requires opaque source text for a downstream templating engine or syntax that jsonencode or yamlencode cannot represent without changing its meaning. The heredoc must not use Terraform interpolation to assemble JSON or YAML in that case, and its reason must be clear from the surrounding configuration.

See terraform_heredoc_usage for enforcement and the supported override.