The Drupal 8 configuration schema cheat sheet

By Gábor Hojtsy, 12 December, 2014

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.

Changes:

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 https://www.drupal.org/node/2414539
1.5: Update for new base type for configuration files, config_object, see https://www.drupal.org/node/2460751
2.0: Posted at http://www.hojtsy.hu/blog/2021-dec-22/major-drupal-configuration-schema…, see there

Thank you for all your work

Thank you for all your work on config schema.

great feedback from Wim Leers

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.

What is the rule for when a .

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.

file names vs. internal types

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.

i understand the use of

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?

last example

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!