Skip to content

Storage & Schema

Schema-driven per-device configuration rendered as UI forms by the host. DeviceStorage plus the JsonSchema* shapes.

camera_ui_sdk.storage

PluginConfig module-attribute 

PluginConfig = dict[str, Any]

Plugin configuration type.

OnSetCallback module-attribute 

OnSetCallback = Callable[[Any, Any], None | Any] | Callable[[Any, Any], Awaitable[None | Any]] | Callable[[Any, Any], Coroutine[Any, Any, None | Any]]

Callback type for onSet handlers.

OnGetCallback module-attribute 

OnGetCallback = Callable[[], None | Any] | Callable[[], Awaitable[None | Any]] | Callable[[], Coroutine[Any, Any, None | Any]]

Callback type for onGet handlers.

JsonSchemaType module-attribute 

JsonSchemaType = Literal['string', 'number', 'boolean', 'array', 'button', 'submit']

Available schema field types for configuration UI.

StringFormat module-attribute 

StringFormat = Literal['date-time', 'date', 'time', 'email', 'uuid', 'ipv4', 'ipv6', 'password', 'qrCode', 'image']

String format types for validation/display.

Used on string-typed schemas to render a specialized UI control:

  • date-time — ISO 8601 date+time picker.
  • date — date-only picker.
  • time — time-only picker.
  • email — email input with format validation.
  • uuid — UUID input with format validation.
  • ipv4 — IPv4 address input.
  • ipv6 — IPv6 address input.
  • password — masked input that hides characters.
  • qrCode — value is rendered as a QR code (read-only display).
  • image — value is a data URL or path; rendered as a thumbnail.

ButtonColor module-attribute 

ButtonColor = Literal['success', 'info', 'warn', 'danger']

Button color variants.

SchemaConditionOperator module-attribute 

SchemaConditionOperator = Literal['eq', 'neq', 'gt', 'lt', 'in', 'nin']

Comparison operators for conditional field visibility.

T module-attribute 

T = TypeVar('T', str, int, float, bool, list[str], list[int], list[float], list[bool], str | list[str])

Generic type variable for schema default values.

V1 module-attribute 

V1 = ExtTypeVar('V1', default=str)

TypeVar for generic getValue return type.

V2 module-attribute 

V2 = ExtTypeVar('V2', bound=Mapping[str, Any], default=dict[str, Any])

TypeVar for generic storage values type. Compatible with TypedDict.

JsonSchema module-attribute 

JsonSchema = JsonSchemaString | JsonSchemaNumber | JsonSchemaBoolean | JsonSchemaEnum | JsonSchemaArray | JsonSchemaButton | JsonSchemaSubmit

Union of every top-level schema type (with callbacks).

Use this when defining the schemas you pass to defineSchemas, addSchema, or changeSchema. Each entry describes one configurable field rendered in the UI; the discriminator is the type property.

JsonSchemaWithoutKey module-attribute 

JsonSchemaWithoutKey = JsonSchemaStringWithoutCallbacks | JsonSchemaNumberWithoutCallbacks | JsonSchemaBooleanWithoutCallbacks | JsonSchemaEnumWithoutCallbacks

Schema variant without the key field.

Used when the key is provided externally (e.g. as a dict property).

JsonSchemaWithoutCallbacks module-attribute 

JsonSchemaWithoutCallbacks = JsonSchemaStringWithoutCallbacks | JsonSchemaNumberWithoutCallbacks | JsonSchemaBooleanWithoutCallbacks | JsonSchemaEnumWithoutCallbacks | JsonSchemaArrayWithoutCallbacks

Union type of schemas without callbacks. Use this for nested schemas (e.g., array items).

SchemaCondition

Bases: TypedDict

Condition that controls when a field is visible. The field is shown only when the condition evaluates to true against the current form values.

Combine multiple conditions on a field via a list — all must pass (logical AND).

Example

Show apiKey only when authMode equals token::

{
    "key": "apiKey",
    "type": "string",
    "title": "API Key",
    "description": "",
    "condition": {"key": "authMode", "value": "token"},
}

Show port only when protocol is one of the listed values::

{"key": "protocol", "operator": "in", "value": ["http", "https"]}

key instance-attribute 

key: Required[str]

Key of another field whose value drives visibility.

value instance-attribute 

value: Required[Any]

Expected value — single value, or list for in / nin.

operator instance-attribute 

operator: SchemaConditionOperator

Comparison operator (default: eq).

JsonFactorySchema

Bases: TypedDict

Base schema interface for all schema types. Contains common fields like type, key, title, description.

type instance-attribute 

type: JsonSchemaType

Field type.

key instance-attribute 

key: str

Unique field identifier.

title instance-attribute 

title: str

Display title.

description instance-attribute 

description: str

Field description/help text.

JsonBaseSchemaWithoutCallbacks

Bases: JsonFactorySchema, Generic[T]

Base schema without callbacks - used for nested schemas. Extends factory schema with common display options.

group instance-attribute 

group: str

Optional group name for organizing fields.

hidden instance-attribute 

hidden: bool

Hide field from UI.

required instance-attribute 

required: bool

Mark field as required.

readonly instance-attribute 

readonly: bool

Make field read-only.

placeholder instance-attribute 

placeholder: str

Placeholder text for empty fields.

defaultValue instance-attribute 

defaultValue: T

Default value when not set.

condition instance-attribute 

condition: SchemaCondition | list[SchemaCondition]

Condition for conditional field visibility. List = all must be true (AND).

JsonBaseSchema

Bases: JsonBaseSchemaWithoutCallbacks[T], Generic[T]

Base schema with callbacks - full schema interface. Adds storage and callback options for dynamic behavior.

store instance-attribute 

store: bool

Whether to persist this field to storage.

onSet instance-attribute 

onSet: OnSetCallback

Callback when value changes.

onGet instance-attribute 

onGet: OnGetCallback

Callback to get computed value.

JsonStringSchema

Bases: TypedDict

String-specific schema options.

format instance-attribute 

format: StringFormat

String format for validation/display.

minLength instance-attribute 

minLength: int

Minimum string length.

maxLength instance-attribute 

maxLength: int

Maximum string length.

JsonNumberSchema

Bases: TypedDict

Number-specific schema options.

minimum instance-attribute 

minimum: int | float

Minimum value.

maximum instance-attribute 

maximum: int | float

Maximum value.

step instance-attribute 

step: int | float

Step increment for number input.

JsonBooleanSchema

Bases: TypedDict

Boolean-specific schema options.

JsonEnumSchema

Bases: TypedDict

Enum/select schema options.

enum instance-attribute 

enum: list[str]

Available options.

multiple instance-attribute 

multiple: bool

Allow multiple selection.

JsonArraySchema

Bases: TypedDict

Array schema options.

opened instance-attribute 

opened: bool

Whether array items are expanded by default.

items instance-attribute 

items: JsonSchemaWithoutCallbacks

Schema for array items.

JsonSchemaString

Bases: JsonBaseSchema[str]

Complete string schema with callbacks.

format instance-attribute 

format: StringFormat

String format for validation/display.

minLength instance-attribute 

minLength: int

Minimum string length.

maxLength instance-attribute 

maxLength: int

Maximum string length.

JsonSchemaStringWithoutCallbacks

Bases: JsonBaseSchemaWithoutCallbacks[str]

String schema without callbacks (for nested use).

JsonSchemaNumber

Bases: JsonBaseSchema[int | float]

Complete number schema with callbacks.

JsonSchemaNumberWithoutCallbacks

Bases: JsonBaseSchemaWithoutCallbacks[int | float]

Number schema without callbacks (for nested use).

JsonSchemaBoolean

Bases: JsonBaseSchema[bool]

Complete boolean schema with callbacks.

JsonSchemaBooleanWithoutCallbacks

Bases: JsonBaseSchemaWithoutCallbacks[bool]

Boolean schema without callbacks (for nested use).

JsonSchemaEnum

Bases: JsonBaseSchema[str | list[str]]

Complete enum schema with callbacks.

JsonSchemaEnumWithoutCallbacks

Bases: JsonBaseSchemaWithoutCallbacks[str | list[str]]

Enum schema without callbacks (for nested use).

JsonSchemaArray

Bases: JsonBaseSchema[list[str] | list[int] | list[float] | list[bool]]

Complete array schema with callbacks.

JsonSchemaArrayWithoutCallbacks

Bases: JsonBaseSchemaWithoutCallbacks[list[str] | list[int] | list[float] | list[bool]]

Array schema without callbacks (for nested use).

JsonSchemaButton

Bases: TypedDict

Button schema - triggers an action without storing a value.

onSet instance-attribute 

onSet: Callable[[], Awaitable[None]] | Callable[[], None]

Click handler.

color instance-attribute 

color: ButtonColor

Button color variant.

JsonSchemaSubmit

Bases: TypedDict

Submit button schema - submits form data and can return updated schema.

onClick instance-attribute 

onClick: Required[Callable[[Any], Awaitable[FormSubmitResponse | None]]]

Submit handler - receives form values, can return toast/schema updates.

ToastMessage

Bases: TypedDict

Toast notification message.

Returned from a submit handler (JsonSchemaSubmit.onClick) inside a FormSubmitResponse to surface a transient banner in the UI — for example to confirm that a credential check succeeded or failed.

type instance-attribute 

type: Literal['info', 'success', 'warning', 'error']

Severity — controls the icon/color of the banner.

message instance-attribute 

message: str

Human-readable message text.

FormSubmitSchema

Bases: TypedDict

Form submit input data.

config instance-attribute 

config: dict[str, Any]

Form configuration values.

FormSubmitResponse

Bases: TypedDict

Form submit response — returned by JsonSchemaSubmit.onClick.

Used to react to a user-triggered submit (e.g. "Test connection", "Pair device") with optional UI feedback. Either field may be set:

  • toast shows a transient banner.
  • schema replaces the current form schema, useful for multi-step flows where the next step depends on the submitted values.

toast instance-attribute 

toast: ToastMessage

Optional toast banner to display after the submit completes.

schema instance-attribute 

schema: list[JsonSchemaWithoutCallbacks]

Optional updated schema definitions (full replacement of fields).

SchemaConfig

Bases: TypedDict

Schema configuration bundle. Contains both schema definitions and current values.

schema instance-attribute 

schema: list[JsonSchema]

Schema definitions.

config instance-attribute 

config: dict[str, Any]

Current configuration values.

DeviceStorage

Bases: Protocol, Generic[V2]

Device storage interface for plugin/camera configuration.

Provides methods to read/write configuration values and manage schemas. Each plugin and camera can have its own storage instance.

Example 
# Get a value with default
threshold = await storage.getValue("motionThreshold", 50)

# Set a value
await storage.setValue("motionThreshold", 75)

# Add a new schema field
await storage.addSchema(
    {
        "type": "number",
        "key": "sensitivity",
        "title": "Sensitivity",
        "description": "Detection sensitivity (0-100)",
        "minimum": 0,
        "maximum": 100,
        "defaultValue": 50,
    }
)

schemas instance-attribute 

schemas: list[JsonSchema]

Current schema definitions.

values instance-attribute 

values: V2

Current configuration values.

getValue async 

getValue(key: str) -> V1 | None

getValue(key: str, default_value: V1) -> V1

getValue(key: str, default_value: V1 | None = None) -> V1 | None

Get a configuration value.

Parameters:

Name Type Description Default
key str

Configuration key

 required
default_value V1 | None

Default value if key doesn't exist

 None

Returns:

Type Description
V1 | None

The configuration value or default

setValue async 

setValue(key: str, new_value: Any) -> None

Set a configuration value.

Parameters:

Name Type Description Default
key str

Configuration key

 required
new_value Any

New value to set

 required

submitValue async 

submitValue(key: str, new_value: Any) -> FormSubmitResponse | None

Submit a value (for submit-type schemas).

Parameters:

Name Type Description Default
key str

Schema key

 required
new_value Any

Submitted value

 required

Returns:

Type Description
FormSubmitResponse | None

Optional response with toast/schema updates

hasValue 

hasValue(key: str) -> bool

Check if a configuration value exists.

Parameters:

Name Type Description Default
key str

Configuration key

 required

getConfig async 

getConfig() -> SchemaConfig

Get the full schema configuration.

Returns:

Type Description
SchemaConfig

Schema definitions and current values

setConfig async 

setConfig(new_config: V2) -> None

Set the full configuration.

Parameters:

Name Type Description Default
new_config V2

New configuration values

 required

addSchema async 

addSchema(schema: JsonSchema) -> None

Add a new schema field.

Parameters:

Name Type Description Default
schema JsonSchema

Schema definition to add

 required

removeSchema 

removeSchema(key: str) -> None

Remove a schema field.

Parameters:

Name Type Description Default
key str

Schema key to remove

 required

changeSchema async 

changeSchema(key: str, new_schema: dict[str, Any]) -> None

Update an existing schema field.

Parameters:

Name Type Description Default
key str

Schema key to update

 required
new_schema dict[str, Any]

Partial schema with updated fields

 required

getSchema 

getSchema(key: str) -> JsonSchema | None

Get a schema definition by key.

Parameters:

Name Type Description Default
key str

Schema key

 required

Returns:

Type Description
JsonSchema | None

Schema or None

hasSchema 

hasSchema(key: str) -> bool

Check if a schema exists.

Parameters:

Name Type Description Default
key str

Schema key

 required

setInternalValue 

setInternalValue(key: str, value: Any) -> None

Set a system-internal value without requiring a schema and persist it.

Parameters:

Name Type Description Default
key str

Internal key (typically prefixed with '_')

 required
value Any

Value to set

 required

save 

save() -> None

Persist all changes to storage.