From c87281edc4b321513f05f6528e75d06ade6e2d50 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Mon, 2 Sep 2024 15:17:15 +0200 Subject: [PATCH] Document requirements for entity service schemas (#2301) * Documented requirements for entity service schema * Update docs/dev_101_services.md Co-authored-by: Robert Resch --------- Co-authored-by: Robert Resch --- docs/dev_101_services.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/dev_101_services.md b/docs/dev_101_services.md index 658752e9..0c5adccd 100644 --- a/docs/dev_101_services.md +++ b/docs/dev_101_services.md @@ -234,7 +234,14 @@ The following example shows how to provide an icon for the `advanced_options` se Sometimes you want to provide extra actions to control your entities. For example, the Sonos integration provides action to group and ungroup devices. Entity service actions are special because there are many different ways a user can specify entities. It can use areas, a group or a list of entities. -You need to register entity service actions in your platforms, like `/media_player.py`. These service actions will be made available under your domain and not the media player domain. Example code: +You need to register entity service actions in your platforms, like `/media_player.py`. These service actions will be made available under your domain and not under the platform domain (e.g. media player domain). A schema can be passed to `async_register_entity_service` if the entity service action has fields. The schema must be either of: + +- A dictionary which will automatically be passed to `cv._make_entity_service_schema` +- A validator returned by `cv._make_entity_service_schema` +- A validator returned by `cv._make_entity_service_schema`, wrapped in a `vol.Schema` +- A validator returned by `cv._make_entity_service_schema`, wrapped in a `vol.All` + +Example code: ```python from homeassistant.helpers import config_validation as cv, entity_platform, service