Creating .schema.yml for form configfor Drupal 8 , 9 , 10 , and 11

Home » Drupal Form Api » Creating .schema.yml for form config
Last updated :  
8.x , 9.x , 10.x , 11.x

Defining a .schema.yml file for your module's configuration settings is a crucial step in ensuring your data is well-structured, validated, and understood by Drupal's configuration management system. This lesson will guide you through crafting a schema YAML file for the configuration settings you manage using the ConfigFormBase class in your module.

What is a .schema.yml File?

The .schema.yml file defines the structure of your module's configuration data. By providing a blueprint of your configuration settings, this file helps Drupal validate and understand the types, cardinalities, and defaults for each configuration item stored within your module.

Why Define a Configuration Schema?

  • Data Validation: Ensures configuration data is validated against expected types and structures.
  • Consistency: Standardizes how configuration data is described and managed across modules.
  • Support for Multilingual: Enables translation support by defining translatable elements in your configuration.

Creating Your .schema.yml File

Let's consider you have a module with a configuration form for storing an API key. You will create a mymodule.schema.yml file to define this setting:

 


mymodule.settings:
    type: config_object
    label: 'My Module settings'
    mapping:
        api_key:
            type: string
            label: 'API Key'
            description: 'The API key for external service access.'

 

Diving into the Schema

Here's a breakdown of this file:

  • mymodule.settings: Specifies the configuration ID being defined, matching the configuration names used in the module.
  • type: config_object: Declares that the settings are part of a configuration object, which is a group of key-value pairs managed by Drupal's configuration system.
  • label: Provides a human-readable name for the configuration set, useful in the admin interface.
  • mapping: Defines nested mappings for individual configuration items, such as api_key in this instance.
  • api_key Type: Specifies the data type—in this case, string—that the api_key is expected to be.
  • api_key Label and Description: Adds metadata for the key to enhance understanding and translation capabilities.

Best Practices for Defining Configuration Schemas

  • Descriptive Labels: Provide clear titles and descriptions to improve administrator understanding and translation.
  • Type Accuracy: Use the most appropriate type (e.g., integer, string, boolean) for each configuration item to ensure correct validation.
  • Scalability: Structure configuration keys to accommodate future growth and additional settings.
  • Avoid Over-Complexity: Keep schemas straightforward to simplify management and decrease errors during data import/export.

Conclusion

Creating a .schema.yml file for your Drupal module's configuration settings is a vital step in structuring data and enhancing the configuration management system's capabilities. Properly defined schemas ensure your module's settings are secure, validated, and comprehensible, both for administrators and when extending functionality.

What's Next?

The next lesson will discuss using ConfigFormBase::save() for configuration storage, demonstrating how to efficiently persist configuration changes made through your custom forms. Stay tuned!