Config Validation

Helpers for configuration validation using voluptuous schemas.

The homeassistant.helpers.config_validation module provides validators and schemas for configuration validation using the voluptuous library.

Common Validators

Basic Types

boolean

Validate and coerce a boolean value.

value · Any · required

Value to validate (accepts bool, str, number)

return · bool

Validated boolean value

import homeassistant.helpers.config_validation as cv

result = cv.boolean("yes")  # Returns: True
result = cv.boolean("0")    # Returns: False
result = cv.boolean(1)      # Returns: True

string

Coerce value to string, except for None.

value · Any · required

Value to coerce

return · str

String representation of value

result = cv.string("hello")  # Returns: "hello"
result = cv.string(123)      # Returns: "123"
# cv.string(None)  # Raises vol.Invalid

Entity and Service Validators

entity_id

Validate entity ID.

value · Any · required

Value to validate

return · str

Validated lowercase entity ID

result = cv.entity_id("Light.Living_Room")  # Returns: "light.living_room"

entity_ids

Validate a list of entity IDs.

value · str | list · required

Comma-separated string or list of entity IDs

return · list[str]

List of validated entity IDs

result = cv.entity_ids("light.living_room, light.bedroom")
# Returns: ["light.living_room", "light.bedroom"]

result = cv.entity_ids(["light.living_room", "light.bedroom"])
# Returns: ["light.living_room", "light.bedroom"]

entity_domain

Validate that entity belongs to specific domain.

domain · str | list[str] · required

Domain(s) to validate against

return · Callable[[Any], str]

Validator function

validate_light = cv.entity_domain("light")
result = validate_light("light.living_room")  # Returns: "light.living_room"
# validate_light("switch.outlet")  # Raises vol.Invalid

service

Validate service name format.

value · Any · required

Value to validate

return · str

Validated service name

result = cv.service("light.turn_on")  # Returns: "light.turn_on"

Numeric Validators

positive_int

Validate positive integer.

positive_int = vol.All(vol.Coerce(int), vol.Range(min=0))

positive_float

Validate positive float.

positive_float = vol.All(vol.Coerce(float), vol.Range(min=0))

port

Validate port number (1-65535).

port = vol.All(vol.Coerce(int), vol.Range(min=1, max=65535))

byte

Validate byte value (0-255).

byte = vol.All(vol.Coerce(int), vol.Range(min=0, max=255))

Geographic Validators

latitude

Validate latitude (-90 to 90).

latitude = vol.All(
    vol.Coerce(float),
    vol.Range(min=-90, max=90),
    msg="invalid latitude"
)

longitude

Validate longitude (-180 to 180).

longitude = vol.All(
    vol.Coerce(float),
    vol.Range(min=-180, max=180),
    msg="invalid longitude"
)

gps

Validate GPS coordinates.

gps = vol.ExactSequence([latitude, longitude])

result = cv.gps([51.5074, -0.1278])  # Valid

Time and Date Validators

time

Validate and transform a time.

value · Any · required

Time value to validate

return · time

Validated time object

result = cv.time("14:30:00")  # Returns: time(14, 30, 0)

date

Validate and transform a date.

value · Any · required

Date value to validate

return · date

Validated date object

time_period

Validate time period (timedelta).

result = cv.time_period("00:05:00")  # Returns: timedelta(minutes=5)
result = cv.time_period(300)         # Returns: timedelta(seconds=300)
result = cv.time_period({"minutes": 5})  # Returns: timedelta(minutes=5)

positive_time_period

Validate positive time period.

positive_time_period = vol.All(time_period, positive_timedelta)

Template Validators

template

Validate a jinja2 template.

value · Any · required

Template string to validate

return · Template

Validated Template object

result = cv.template("{{ states('sensor.temperature') }}")

dynamic_template

Validate a dynamic (non-static) jinja2 template.

value · Any · required

Template string to validate (must contain template syntax)

return · Template

Validated Template object

result = cv.dynamic_template("{{ now() }}")
# cv.dynamic_template("static")  # Raises vol.Invalid

URL Validators

url

Validate a URL.

value · Any · required

URL to validate

return · str

Validated URL

result = cv.url("https://example.com")  # Valid
result = cv.url("http://example.com")   # Valid

configuration_url

Validate a URL that allows the homeassistant scheme.

result = cv.configuration_url("homeassistant://navigate/lovelace/dashboard")
result = cv.configuration_url("https://example.com")

File System Validators

path

Validate it’s a safe path.

value · Any · required

Path to validate

return · str

Validated path

result = cv.path("/config/custom_components")  # Valid path

isfile

Validate that the value is an existing file.

result = cv.isfile("/config/configuration.yaml")  # Valid if file exists

isdir

Validate that the value is an existing directory.

result = cv.isdir("/config")  # Valid if directory exists

Schema Helpers

has_at_least_one_key

Validate that at least one key exists.

schema = vol.Schema(
    vol.All(
        {
            vol.Optional("name"): str,
            vol.Optional("id"): int,
        },
        cv.has_at_least_one_key("name", "id")
    )
)

has_at_most_one_key

Validate that zero keys exist or one key exists.

schema = vol.Schema(
    vol.All(
        {
            vol.Optional("action"): str,
            vol.Optional("service"): str,
        },
        cv.has_at_most_one_key("action", "service")
    )
)

deprecated

Log key as deprecated and provide a replacement.

key · str · required

Deprecated key name

replacement_key · str | None · default: "None"

Replacement key name

default · Any | None · default: "None"

Default value

raise_if_present · bool · default: "False"

Whether to raise exception if key is present

schema = vol.Schema(
    vol.All(
        {
            vol.Optional("name"): str,
        },
        cv.deprecated("entity_namespace", replacement_key="name")
    )
)

make_entity_service_schema

Create an entity service schema.

schema · dict | None · required

Service data schema

extra · int · default: "vol.PREVENT_EXTRA"

Extra keys handling (vol.PREVENT_EXTRA or vol.ALLOW_EXTRA)

return · VolSchemaType

Entity service schema

SERVICE_TURN_ON_SCHEMA = cv.make_entity_service_schema(
    {
        vol.Optional("brightness"): vol.All(vol.Coerce(int), vol.Range(0, 255)),
        vol.Optional("color_temp"): vol.All(vol.Coerce(int), vol.Range(153, 500)),
    }
)

Pre-built Schemas

PLATFORM_SCHEMA_BASE

Base schema for platform configuration.

PLATFORM_SCHEMA = cv.PLATFORM_SCHEMA_BASE.extend({
    vol.Required("api_key"): cv.string,
    vol.Optional("scan_interval"): cv.positive_time_period,
})

ENTITY_SERVICE_FIELDS

Fields for entity service schemas (entity_id, device_id, area_id, floor_id, label_id).

TARGET_SERVICE_FIELDS

Fields for target service schemas (supports entity registry IDs).

Constants

• CONF_PLATFORM - “platform” key
• CONF_ENTITY_ID - “entity_id” key
• CONF_DEVICE_ID - “device_id” key
• CONF_AREA_ID - “area_id” key
• CONF_NAME - “name” key
• CONF_SCAN_INTERVAL - “scan_interval” key