Compose: Healthcheck start_period is not supported but documentation says it is

[jdel]

Documentation states that from 2.1, start_period is supported in healthchecks, but it is not.
Source: https://docs.docker.com/compose/compose-file/compose-file-v2/#healthcheck

This compose will fail with services.nginx.healthcheck value Additional properties are not allowed ('start_period' was unexpected):

version: '2.2'
services:
  nginx:
    image: nginx:stable
    healthcheck:
      test: ["CMD", "curl", "-f", "localhost"]
      interval: 30s
      timeout: 5s
      retries: 1
      start_period: 30s

Changing version to 2.1, 3, 3.1, 3.2, 3.3 yields the same error message.

For reference:

$ docker-compose version                                                                                                                                            
docker-compose version 1.14.0, build c7bdf9e
docker-py version: 2.3.0
CPython version: 2.7.12
OpenSSL version: OpenSSL 1.0.2j  26 Sep 2016

$ docker version                                                                                                                                                      
Client:
 Version:      17.06.2-ce
 API version:  1.30
 Go version:   go1.8.3
 Git commit:   cec0b72
 Built:        Tue Sep  5 20:12:06 2017
 OS/Arch:      darwin/amd64

Server:
 Version:      17.06.2-ce
 API version:  1.30 (minimum version 1.12)
 Go version:   go1.8.3
 Git commit:   cec0b72
 Built:        Tue Sep  5 19:59:19 2017
 OS/Arch:      linux/amd64
 Experimental: false

[sepich]

It is already supported in stack compose 3.4 since docker 17.09 - https://github.com/docker/cli/pull/475
But we using same docker-compose.yml also for 'docker-compose build' and v3.4 still unsupported via docker-compose 1.16.1

ERROR: Version in "./docker-compose.yml" is unsupported. You might be seeing this error because you're using the wrong Compose file version. Either specify a supported version (e.g "2.2" or "3.3") and place your service definitions under the `services` key, or omit the `version` key and place your service definitions at the root of the file to use version 1.
For more on the Compose file format versions, see https://docs.docker.com/compose/compose-file/

[shin-]

From the docs:

Note: The start_period option is a more recent feature and is only available with the 2.3 file format.

[Clcanny]

You can use start_period option in 3.7 version.

Client:
 Version:           18.06.0-ce
 API version:       1.38
 Go version:        go1.10.3
 Git commit:        0ffa825
 Built:             Wed Jul 18 19:05:26 2018
 OS/Arch:           darwin/amd64
 Experimental:      false

Server:
 Engine:
  Version:          18.06.0-ce
  API version:      1.38 (minimum version 1.12)
  Go version:       go1.10.3
  Git commit:       0ffa825
  Built:            Wed Jul 18 19:13:46 2018
  OS/Arch:          linux/amd64
  Experimental:     true

You can look at this website:

Note: start_period is only supported for v3.4 and higher of the compose file format.

[mtazzari]

I can get start_period to work properly using Compose file v3.7 and docker 18.09, however I got really confused by the docs:

• start_period is a property in the Compose file, while
• start-period is a docker command line parameter, see the Engine docs here.

It took me a while to realise the hyphen/underscore difference.
I am writing this hoping to save some time to other people...