The Drupal 8 configuration schema cheat sheet

After over a month of concentrated work, Drupal 8 was ready today to finally flip the switch and enforce strict configuration schema adherence in all TestBase derived tests in core. See the announcement in the core group.

If you are a Drupal 8 contrib developer and provided some configuration schema earlier (or you integrate with an existing core system like blocks, views, fields, etc.) then your tests may now fail with configuration schema errors. Unless of course all your configuration schema is correct: #highfive for you then.

Otherwise I thought you'll have questions. There is of course the existing configuration schema documentation that I helped write. However if you are a visual person and want to get an understanding of the basics fast, I thought a cheat sheet would be a great tool. So sat down today and produced this one in the hopes it will help you all! Enjoy!

Please provide feedback for improvements in the comments, and I'll update the sheet as appropriate.


  • 1.0: Initial version
  • 1.1: Different background colour for schemas for readability; Fixed incorrect [key] and [%parent] examples; some small fixes; thanks Wim Leers
  • 1.2: Better wording for parent example labels, clarify naming of internal type vs. top level type; thanks Wim Leers
  • 1.3: Fixed config name matching in both examples on second page; fixed 'messages' key matching in last example; minor typos; thanks Michael Prasuhn
  • 1.4: Update for simplified sequence format introduced in
  • 1.5: Update for new base type for configuration files, config_object, see
  • 2.0: Posted at, see there
PDF icon ConfigSchemaCheatSheet1.5.pdf63.81 KB


jibran's picture

Thank you for all your work on config schema.

Gábor Hojtsy's picture

I got some great feedback from Wim Leers for improvements. Welcome more feedback if something is not clear, so I can take those into account for any revisions.

Michael Prasuhn's picture

What is the rule for when a . in a file name should be replaced with an underscore in schema definition? The example on the first page seem to use dots, but on the second page my_module.message becomes my_module_message in the schema.

Gábor Hojtsy's picture

You should would avoid naming internal types in a way that may clash with your filenames. In the second example, the file names may be my_module.message.whatever. So if you name your internal type with that pattern then it may match on a concrete file which would be totally incorrect. So for your internal types, I would suggest using underscores liberally. There are no clear rules for how you should name your types, but another best practice that the sheet follows is to always prefix your type names with your module name.

Michael Prasuhn's picture

i understand the use of underscores in internal types, but it still seems like in the examples on the second page, the types wouldn't match: my_module_message.* wouldn't match against the contents of my_module.message.single.yaml? Am I missing something?

Gábor Hojtsy's picture

Right, there are two errors on the second page (in v1.2), the first line of the first yellow box should be my_module.message.* (dot before message). Good find :) That would match the config key. The rest of the matching looks good. The other errors is in the second yellow box. The mapping key for the messages should be messages (plural) not message. Will fix these in 1.3. Good find!

Gábor Hojtsy's picture

Updates in 1.3. I found both key matching schemas were wrong on the second pages. Haha. Fixed now. Thanks for noticing and letting me know.

Brian Gallagher's picture

Can you add 'ignore' as a listed option in the Basic Schema Types chart as well? It shouldn't be used often, but it's good to know it is an option (and it's used a few times in core schemas).

Thanks for a great resource!

Add new comment