developers.home-assistant/docs/development_validation.md

layout	title	description	date	sidebar	comments	sharing	footer
page	Validate the input	Validation of entries in configuration.yaml	2016-08-11 20:00	true	false	true	true

The configuration.yaml file contains the configuration options for components and platforms. We use voluptuous to make sure that the configuration provided by the user is valid. Some entries are optional or could be required to set up a platform or a component. Others must be a defined type or from an already-defined list.

We test the configuration to ensure that users have a great experience and minimize notifications if something is wrong with a platform or component setup before Home Assistant runs.

Besides voluptuous default types, many custom types are available. For an overview, take a look at the config_validation.py helper.

• Types: string, byte, and boolean
• Entity ID: entity_id and entity_ids
• Numbers: small_float and positive_int
• Time: time, time_zone
• Misc: template, slug, temperature_unit, latitude, longitude, isfile, sun_event, ensure_list, port, url, and icon

To validate platforms using MQTT, valid_subscribe_topic and valid_publish_topic are available.

Some things to keep in mind:

• Use the constants defined in const.py
• Import PLATFORM_SCHEMA from the parent component and extend it
• Preferred order is required first and optional second
• Starting with Home Assistant 0.64 voluptuous requires default values for optional configuration keys to be valid values. Don't use a default which is None like vol.Optional(CONF_SOMETHING, default=None): cv.string, set the default to default="" if required.

{% linkable_title Snippets %}

This section contains snippets for the validation we use.

{% linkable_title Default name %}

It's common to set a default for a sensor if the user doesn't provide a name to use.

DEFAULT_NAME = 'Sensor name'

PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
    ...
    vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string,

{% linkable_title Limit the values %}

You might want to limit the user's input to a couple of options.

DEFAULT_METHOD = 'GET'

PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
    ...
    vol.Optional(CONF_METHOD, default=DEFAULT_METHOD): vol.In(['POST', 'GET']),

{% linkable_title Port %}

All port numbers are from a range of 1 to 65535.

DEFAULT_PORT = 993

PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
    ...
    vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port,

{% linkable_title Lists %}

If a sensor has a pre-defined list of available options, test to make sure the configuration entry matches the list.

SENSOR_TYPES = {
    'article_cache': ('Article Cache', 'MB'),
    'average_download_rate': ('Average Speed', 'MB/s'),
}

PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
    ...
    vol.Optional(CONF_MONITORED_VARIABLES, default=[]):
        vol.All(cv.ensure_list, [vol.In(SENSOR_TYPES)]),