---
layout: docs
page_title: Syntax - waypoint.hcl
description: |-
  This page describes the syntax of the `waypoint.hcl` configuration language. The waypoint.hcl file uses either HCL or JSON, allowing both human and machine friendly formats. The recommended and typical format is HCL.
---

# Configuration Syntax

This page describes the syntax of the `waypoint.hcl` configuration language.
The waypoint.hcl file uses either HCL or JSON, allowing both human and machine
friendly formats. The recommended and typical format is HCL.

HCL is also used by other HashiCorp products such as Terraform.
It is not necessary to know all of the details of HCL syntax in
order to use Waypoint, and so this page summarizes the most important
details. If you are interested, you can find a full definition of HCL
syntax in
[the HCL native syntax specification](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md).

## Parameters and Stanzas

The `waypoint.hcl` configuration syntax is built around two key syntax constructs:
parameters and stanzas.

### Parameters

A _parameter_ assigns a value to a particular name:

```hcl
image_id = "abc123"
```

The identifier before the equals sign is the _parameter name_, and the expression
after the equals sign is the parameter's value.

The context where the parameter appears determines what names and value types
are valid. Parameter values can also be built up using
[expressions](/docs/configuration/expressions/index.html) which allow the value to
either be specified literally or generated from other values programmatically.

### Stanzas

A _stanza_ is a container for other configuration content:

```hcl
app "web" {
  build {
    use "docker {
      dockerfile = "${path.app}/Dockerfile"
    }
  }

  # ...
}
```

In this example, `app`, `build`, and `use` are all stanzas.

A stanza has a _type_ (such as `app` in this example). Each stanza type defines
zero or more _labels_ that must follow the type keyword. The `app` type
expects one label, which is "web" in the example above.
A particular stanza type may have any number of required labels, or it may
require none as with the nested `build` stanza type.

After the stanza type keyword and any labels, the stanza _body_ is delimited
by the `{` and `}` characters. Within the stanza body, further parameters
and stanzas may be nested, creating a hierarchy of stanzas and their associated
parameters.

All of the stanza types that Waypoint supports are listed in the documentation
sidebar to the left. The documentation uses [placement tables](/docs/waypoint-hcl#placement-tables)
to document the context in which stanzas are valid.

## Comments

Waypoint configuration supports three different syntaxes for comments:

- `#` begins a single-line comment, ending at the end of the line.
- `//` also begins a single-line comment, as an alternative to `#`.
- `/*` and `*/` are start and end delimiters for a comment that might span
  over multiple lines.

The `#` single-line comment style is the default comment style and should be
used in most cases. Automatic configuration formatting tools may automatically
transform `//` comments into `#` comments, since the double-slash style is
not idiomatic.

## Identifiers

Parameter names, stanza type names, variables, etc. are all _identifiers_.

Identifiers can contain letters, digits, underscores (`_`), and hyphens (`-`).
The first character of an identifier must not be a digit, to avoid ambiguity
with literal numbers.
For complete identifier rules, Waypoint implements
[the Unicode identifier syntax](http://unicode.org/reports/tr31/), extended to
include the ASCII hyphen character `-`.

## Character Encoding and Line Endings

Waypoint configuration files must always be UTF-8 encoded. While the
delimiters of the language are all ASCII characters, Waypoint accepts
non-ASCII characters in identifiers, comments, and string values.

Waypoint accepts configuration files with either Unix-style line endings
(LF only) or Windows-style line endings (CR then LF), but the idiomatic style
is to use the Unix convention, and so automatic configuration formatting tools
may automatically transform CRLF endings to LF.
