Symfony 7.4 added JSON schemas for YAML files like services.yaml and routes.yaml, so IDEs can autocomplete and validate them. The files in config/packages/ weren't included and that's where you write or maintain most of your YAML config.

Each bundle defines its own configuration tree, so the schema depends on which bundles your application uses. Symfony 8.2 handles this by generating a JSON Schema dynamically for your application configuration.

Using the Schema in Your Editor

Jérôme Tamarelle
Contributed by Jérôme Tamarelle in #62125

When the container is compiled in debug mode and the symfony/yaml package is installed, Symfony 8.2 writes a config/schema.json file. It merges the configuration trees of every registered bundle, including the when@<env> blocks. The file is regenerated each time the container is compiled, so it always matches the bundles installed in your app.

This is the YAML counterpart of the config/reference.php file that Symfony 7.4 introduced for PHP configuration. Your IDE doesn't pick up the new file automatically, so you need to point it to config/schema.json.

Any editor based on yaml-language-server (Visual Studio Code with the YAML extension, Neovim, Emacs, etc.) reads this comment at the top of the file:

1
2
3
4
5
# config/packages/framework.yaml
# yaml-language-server: $schema=../schema.json
framework:
    secret: '%env(APP_SECRET)%'
    # ...

The path is relative to the edited file, so use ../../schema.json inside config/packages/<env>/. In Visual Studio Code you can also map the schema to every file in config/packages/ at once in .vscode/settings.json:

1
2
3
4
5
{
    "yaml.schemas": {
        "config/schema.json": "config/packages/**/*.yaml"
    }
}

In PhpStorm, add the same mapping in Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings. Your editor can then autocomplete option names and show their descriptions and default values. It also flags unknown or deprecated options and values with the wrong type.

Validating YAML Files with lint:yaml

Jérôme Tamarelle
Contributed by Jérôme Tamarelle in #65394

The lint:yaml command can now check YAML files against a JSON Schema as well as checking their syntax. You can use this in CI to catch configuration errors. Schema validation requires installing the opis/json-schema library:

1
$ composer require opis/json-schema

Then, pass the new --check-schema option:

1
2
3
4
5
# validate the given files against a specific schema
$ php bin/console lint:yaml config/packages/ --check-schema=config/schema.json

# validate each file against its own schema
$ php bin/console lint:yaml config/ --check-schema

The second command reads the same # yaml-language-server: $schema= comment that editors use. In Symfony applications, files in the usual locations don't even need that comment:

  • Files in config/packages/ use the generated config/schema.json.
  • Routes, services, serializer and validator files (config/routes.yaml, config/services.yaml, etc.) use their components' schemas.

Files without a schema are reported as valid, so you can run the command on the whole config/ directory.

Note

The generated schema describes the static configuration tree, so it can't represent some values that bundles accept via runtime normalization (for example, options that accept a list only thanks to a beforeNormalization() closure). In those cases, lint:yaml may report errors for valid configuration.

Published in #Living on the edge