Compose files are YAML. YAML has three building blocks, and every line of a compose.yaml is one of them.

Indentation is the structure

A key's children are the lines below it that are indented further. Use spaces, never tabs. Compose files use two spaces per level by convention.

services:                         # mapping: key "services"
  greeter:                        #   mapping: one service named "greeter"
    image: stackmonsters/greeter:1.0
    ports:                        #     value is a list
      - "8080:8080"               #       one list item (a string)
    environment:                  #     value is a mapping
      GREETING: Hello
      NAME: platform team

services
└── greeter
    ├── image        = "stackmonsters/greeter:1.0"
    ├── ports        = ["8080:8080"]
    └── environment  = { GREETING: "Hello", NAME: "platform team" }

Siblings start in the same column. Move environment: two spaces left and it is no longer a field of greeter; it becomes a second service named environment.

Lists versus mappings

Some Compose keys accept either form. environment is one of them:

environment:          # mapping form
  GREETING: Hello
  NAME: platform team

environment:          # list form
  - GREETING=Hello
  - NAME=platform team

Pick one per block. A block that starts as a list cannot continue as a mapping.

Scalars and quoting

YAML guesses types. Quote values when the guess could be wrong:

Let Compose check the file

docker compose config parses compose.yaml, validates it and prints the resolved result. It changes nothing. Run it after every edit.

Two kinds of error come back. A YAML error means the file is not valid YAML; Compose names a line at or just before the problem. A validation error means the YAML is fine but a key is in the wrong place.

yaml: line 3: mapping values are not allowed in this context

validating /home/learner/greeter/compose.yaml: services.environment additional properties 'GREETING' not allowed