LCARdS

Appearance

Validation Service ​

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

Overview ​

The Validation Service provides runtime config validation using a schema registry. When a card receives a config object, validation catches structural errors and unknown fields early, before rendering starts.

Key Files ​

FileRole
core/validation-service/index.jsService entry point
core/validation-service/SchemaRegistry.jsStores schemas keyed by card type; register/lookup
core/validation-service/DataSourceValidator.jsValidates data_sources block
core/validation-service/OverlayValidator.jsValidates MSD overlay definitions
core/validation-service/TokenValidator.jsDetects invalid token syntax in string fields
core/validation-service/ValueValidator.jsType + range checking for scalar fields
core/validation-service/ErrorFormatter.jsFormats error objects into human-readable messages
core/validation-service/schemas/Per-card JSON schema definitions

Schema Registration ​

Each card class exposes a static registerSchema() method. These are called in src/lcards.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();
// ... 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:

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

Public API ​

MethodReturnsDescription
validateConfig(cardType, config){ valid, errors, warnings }Validate a config object against the card's registered schema
getSchema(cardType)Object|nullRetrieve the raw JSON schema for a card type
getRegisteredTypes()string[]All card types with registered schemas
javascript
import { validateConfig } from '../core/validation-service/index.js';

// Returns { valid: boolean, errors: string[], warnings: string[] }
const result = validateConfig('lcards-button', this.config);

if (!result.valid) {
  lcardsLog.warn('[MyCard] Config validation failed:', result.errors);
}

Console Access ​

javascript
window.lcards.debug.singleton('validationService')
// → { type: 'ValidationService', initialized: true, registeredSchemas: 8, cacheSize: 14 }
javascript
const vs = window.lcards.core.validationService

vs.getRegisteredTypes()                // all card types with schemas
vs.getSchema('lcards-button')          // raw schema object
vs.validateConfig('lcards-slider', {}) // run validation directly

TokenValidator ​

TokenValidator validates {theme:token.path} references used in card config fields. Given a theme manager, it checks that the token path exists in the active theme, resolves to a valid value, and does not form a circular reference. It is applied automatically during config validation — you do not need to call it directly.

Error Output Format ​

validateConfig() returns:

javascript
{
  valid: boolean,
  errors: string[],   // blocking issues — card should not render
  warnings: string[]  // non-fatal suggestions
}

Example error messages (generated by ErrorFormatter):

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 ID "light.bedroom_lamp" is not valid (use format: domain.entity_id)

Error Display ​

Validation errors surface in two places:

  1. Browser console — structured log messages with field paths
  2. Card editor — the YAML tab shows inline error markers via CodeMirror integration

See Also ​