Validate the input

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 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
  • 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.


This section contains snippets for the validation we use.

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'

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

Limit the values

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


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


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


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


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

    'article_cache': ('Article Cache', 'MB'),
    'average_download_rate': ('Average Speed', 'MB/s'),

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