Validation Service

Config schema validation for all LCARdS card types: window.lcards.core.validationService

Overview

Config validation is split across two singletons:

CoreConfigManager (window.lcards.core.configManager) owns the per-card-type schema registry (registerCardSchema() / getCardSchema()) and calls validation automatically as the last step of its four/five-layer processConfig() merge pipeline.
CoreValidationService (window.lcards.core.validationService) does the actual structural (JSON-schema-style) validation via validate(data, schema, context). It also owns optional token-reference and data-source-reference validators, and a small legacy registry of generic schemas (card-config, entity-reference, action-config, position, size) used internally.

Key Files

File	Role
`core/validation-service/index.js`	`CoreValidationService`: structural validation (`validate()`), plus internal `CoreSchemaRegistry` (5 built-in generic schemas) and `CoreErrorFormatter` (used automatically inside `validate()`)
`core/validation-service/TokenValidator.js`	Validates `{theme:token.path}` / token-path references against a `ThemeManager`; called manually via `validationService.validateTokens()`
`core/validation-service/DataSourceValidator.js`	Validates `source` / `data_source` / `sources` fields on data-source-capable config types (currently `lcards-chart`/`chart`); called manually via `validationService.validateDataSources()`
`core/validation-service/ErrorFormatter.js`	Standalone formatter that turns a validation result into a multi-line human-readable string, used by `validationService.formatErrors()`
`core/config-manager/index.js`	`CoreConfigManager`: per-card-type schema registry (`_cardSchemas`), config merge pipeline, and the `_validateConfig()` step that calls `validationService.validate()`
`src/cards/schemas/*.js`	Per-card JSON schema definitions (e.g. `button-schema.js`, `msd-schema.js`)

Schema Registration

Each card class exposes a static registerSchema() method. These are called in src/lcards-main.js after all core services initialise:

javascript

// lcards.js (called once at startup, after core is ready)
if (LCARdSButton.registerSchema) LCARdSButton.registerSchema();
if (LCARdSElbow.registerSchema) LCARdSElbow.registerSchema();
if (LCARdSMSDCard.registerSchema) LCARdSMSDCard.registerSchema();
// ... one call per card type

Inside registerSchema(), the card calls configManager.registerCardSchema():

javascript

// Inside your card class
static registerSchema() {
    const configManager = window.lcards?.core?.configManager;
    if (!configManager) return;

    const schema = getMyCardSchema({ /* runtime options, e.g. available presets */ });
    configManager.registerCardSchema('my-card', schema, { version: __LCARDS_VERSION__ });
}

To add a new card type to validation:

Add a schema file at src/cards/schemas/my-card-schema.js
Add static registerSchema() to your card class calling configManager.registerCardSchema('my-card', schema)
Call MyCard.registerSchema() in src/lcards-main.js after core initialisation

Once registered, configManager.processConfig(userConfig, 'my-card', context) automatically validates the merged config against that schema on every call; there's no separate opt-in step.

Public API

`CoreConfigManager` (schema registry + orchestration)

Method	Returns	Description
`registerCardSchema(cardType, schema, options?)`	`void`	Register a JSON schema for a card type. `options.version` defaults to `'1.0'`
`getCardSchema(cardType)`	`Object\|null`	The raw registered schema, or `null`
`processConfig(userConfig, cardType, context?)`	`Promise<{ valid, mergedConfig, errors, warnings, provenance }>`	Runs the full merge pipeline, then validates the merged result against the registered schema (skipped silently if no schema is registered for `cardType`)
`getDebugInfo()`	`Object`	`{ initialized, stats, registeredCards: { schemas, defaults }, dependencies }`

`CoreValidationService` (structural validation)

Method	Returns	Description
`validate(data, schema, context?)`	`{ valid, errors, warnings, data, schema }`	Validate `data` against a schema object, or a string name from the internal generic registry (`'card-config'`, `'entity-reference'`, `'action-config'`, `'position'`, `'size'`)
`validateTokens(config, context?)`	`{ errors, warnings }`	Runs `TokenValidator`: requires `setThemeManager()` to have been called first; returns `{ errors: [], warnings: [] }` otherwise. Not invoked automatically by `validate()` or by `configManager`; call it explicitly
`validateDataSources(config, context?)`	`{ errors, warnings }`	Runs `DataSourceValidator`: requires `setDataSourceManager()` first. Not invoked automatically either
`setThemeManager(themeManager)`	`void`	Wires up `validateTokens()`
`setDataSourceManager(dataSourceManager)`	`void`	Wires up `validateDataSources()`
`formatErrors(validationResult)`	`string`	Multi-line human-readable summary via the standalone `ErrorFormatter`
`getStats()`	`Object`	`{ validationsPerformed, errorsFound, warningsFound, cacheHits, entityChecks }`
`clearCache()`	`void`	Clears the validation-result cache and the entity-existence cache
`getDebugInfo()`	`Object`	See Console Access below

javascript

// Card-type validation (the common path) goes through configManager, not validationService directly:
const configManager = window.lcards.core.configManager;
const result = await configManager.processConfig(this.config, 'lcards-button', { hass: this.hass });
if (!result.valid) {
  lcardsLog.warn('[MyCard] Config validation failed:', result.errors);
}

// Direct structural validation against an arbitrary schema object:
const vs = window.lcards.core.validationService;
const result2 = vs.validate({ entity: 'light.bedroom' }, myJsonSchema);

The config, editor, and MSD pipeline code paths all call CoreValidationService.validate() directly. TokenValidator/DataSourceValidator work correctly once wired up via setThemeManager()/setDataSourceManager(), but validateTokens()/validateDataSources() must be called explicitly; validate() runs structural and entity validation only.

Console Access

SnapshotLive object

javascript

window.lcards.debug.singleton('validationService')
// → {
//   initialized: true,
//   hasHASS: true,
//   config: {
//     strict: false, validateEntities: true, cacheResults: true, debug: false,
//     validateTokens: true, validateDataSources: true, stopOnError: false
//   },
//   stats: { validationsPerformed: 42, errorsFound: 3, warningsFound: 5, cacheHits: 18, entityChecks: 12 },
//   cacheSize: 24,
//   entityCacheSize: 12,
//   availableSchemas: ['card-config', 'entity-reference', 'action-config', 'position', 'size']
// }

javascript

const vs = window.lcards.core.validationService

vs.validate(config, schema, context)     // run structural validation directly
vs.getStats()                            // { validationsPerformed, errorsFound, warningsFound, cacheHits, entityChecks }
vs.clearCache()                          // clear validation + entity caches
vs.formatErrors(result)                  // human-readable multi-line summary

const cm = window.lcards.core.configManager
cm.getCardSchema('lcards-button')        // registered JSON schema for a card type

Note: availableSchemas in the snapshot lists the legacy generic schemas built into CoreValidationService (card-config, entity-reference, action-config, position, size); it does not include per-card-type schemas (lcards-button, msd, etc.), which live in configManager instead. Use cm.getCardSchema('lcards-button') for those.

Error Output Format

CoreValidationService.validate() (and CoreConfigManager.processConfig(), which wraps it) returns:

javascript

{
  valid: boolean,
  errors: Array<{ type, field, message, formattedMessage, suggestion, severity, context }>,
  warnings: Array<{ type, field, message, formattedMessage, suggestion, severity, context }>
}

errors/warnings are objects, not plain strings: each entry carries a machine-readable type (e.g. 'required_field', 'invalid_type', 'invalid_enum', 'out_of_range', 'missing_entity'), the field path, and a formattedMessage produced automatically by the internal CoreErrorFormatter. Example formattedMessage values:

Required field "entity" is missing
Field "style.color" must be string, got number
Field "preset" must be one of: lozenge, pill, bullet, rectangle
Field "style.color" value 999 is out of valid range
Entity "light.bedroom_lamp" not found in Home Assistant

Entity references are checked only as a warning (missing_entity) when validateEntities is enabled and HASS is available; an unknown entity never blocks a save.

TokenValidator

TokenValidator (constructor(themeManager), validate(config, context)) walks a config object looking for theme-token-shaped string values and checks that each resolves against the active theme via ThemeTokenResolver. It's available on validationService.tokenValidator once setThemeManager() has been called, but (as noted above) nothing in the current codebase calls validationService.validateTokens() automatically; a card or pipeline stage that wants token validation must call it explicitly.

Error Display

Validation errors surface in two places:

Browser console: structured log messages with field paths (via lcardsLog.warn() at call sites)
Card editor: LCARdSBaseEditor._validateConfig() calls validationService.validate() directly against the schema from configManager.getCardSchema() and stores the result for the YAML tab's inline error markers

Validation Service ​

Overview ​

Key Files ​

Schema Registration ​

Public API ​

CoreConfigManager (schema registry + orchestration) ​

CoreValidationService (structural validation) ​

Console Access ​

Error Output Format ​

TokenValidator ​

Error Display ​

See Also ​

Validation Service

Overview

Key Files

Schema Registration

Public API

`CoreConfigManager` (schema registry + orchestration)

`CoreValidationService` (structural validation)

Console Access

Error Output Format

TokenValidator

Error Display

See Also