sass-valid

Sass schema-driven validation — per the Error Message Specification.

---

Installation

npm install sass-valid sass-funcs sass-error

Requires sass or sass-embedded >= 1.33.0 — install one, not both (sass-embedded recommended). Also requires sass-funcs and sass-error.

---

Configuration

All constants are configurable via @use ... with (...):

@use 'sass-valid' as v with (
  $VALIDATION_MODE_SELECTED: 'strict',
  $ERROR_HINT_TEXT: 'Refer to the schema'
);

Variable	Default	Description
$VALUE_ID_ALLOWED_TYPES	('string', 'number', 'bool')	Allowed Sass types for map keys (entity attributes, schema fields)
$FIELD_REQUIRED	'is-required'	Schema field name for the required flag
$FIELD_ALLOWED_TYPES	'allowed-types'	Schema field name for allowed types
$FIELD_ALLOWED_VALUES	'allowed-values'	Schema field name for allowed values
$FIELD_VALIDATOR	'validator'	Schema field name for the custom validator name
$ERROR_HINT_TEXT	'See schema for allowed values'	Hint appended when the options list is truncated
$ERROR_LABEL_ENTRY	'ENTRY'	Default label for collection member keys in error codes
$ERROR_LABEL_FIELD	'FIELD'	Default label for schema field keys in error codes
$ERROR_ENTRY_LABELS	('ENTRY', 'FIELD')	Allowed values for $custom-entry-label
$VALIDATION_MODE_SELECTED	'rigid'	Default validation mode

Note: See the Error Message Specification for details on how error codes and labels are structured.

---

Module: Valid

@use 'sass-valid' as v;

Function	Description
validate	Validates an entity map against a schema definition

---

v.validate($schema, $entity, ...)

Validates an entity map against a schema. The schema is checked against a built-in metaschema on first use and the result is cached — repeated calls with the same schema incur no extra cost.

Parameter	Type	Default	Description
$schema	Map		Schema definition map
$entity	Map		Entity map to validate
$entity-type	String	'entity'	Label for the entity type in error messages
$entity-name	String	'unnamed'	Label for the entity name in error messages
$mode	String	$VALIDATION_MODE_SELECTED	Validation mode: 'permissive', 'rigid', or 'strict'
$custom-entry-label	String	$ERROR_LABEL_ENTRY	Label for entry-level error codes: 'ENTRY' or 'FIELD'
$schema-id	String | Null	null	Cache key override; use when the same $entity-type maps to different schemas
$validators	Map	()	Map of validator name strings to Sass function references

Returns Null on success, String error message on failure (see Error Message Specification) — pass to @error to raise.

$schema: (
  'name': ('is-required': true,  'allowed-types': 'string'),
  'role': ('is-required': true,  'allowed-types': 'string', 'allowed-values': ('admin', 'user', 'guest')),
  'age':  ('is-required': false, 'allowed-types': 'number'),
);

v.validate($schema, ('name': 'Alice', 'role': 'admin'), 'person', 'Alice')
// → null

v.validate($schema, ('name': 'Alice', 'role': 42), 'person', 'Alice')
// → '[PERSON_ROLE_TYPE] Person "Alice" @ role: Incorrect type "number" → Expected: string'

v.validate($schema, ('name': 'Alice', 'role': 'owner'), 'person', 'Alice')
// → '[PERSON_ROLE_VALUE] Person "Alice" @ role: Invalid value "owner" → Allowed: admin | user | guest'

v.validate($schema, ('name': 'Alice', 'role': 'admin', 'rank': 1), 'person', 'Alice')
// → '[PERSON_RANK_UNKNOWN] Person "Alice": Unknown attribute "rank" → Remove "rank" [context: mode "rigid"]'

---

Schema Definition

A schema is a Sass map where each key is an attribute name and each value is a rules map:

$schema: (
  '<attribute>': (
    'is-required': <bool>,
    // optional — defaults to false
    'allowed-types': '<type>',
    // required — Sass type name or list of names
    'allowed-values': (
        <val>,
        ...,
      ),
    // optional — allowed values, or a nested schema map
    'validator': '<name>',
    // optional — custom validator key
  ),
  ...,
);

The field names 'is-required', 'allowed-types', 'allowed-values', and 'validator' are configurable via $FIELD_REQUIRED, $FIELD_ALLOWED_TYPES, $FIELD_ALLOWED_VALUES, and $FIELD_VALIDATOR.

Field	Type	Required	Description
'is-required'	Bool	No	Whether the attribute must be present. Always true in 'strict' mode.
'allowed-types'	String | List	Yes	One or more Sass type names: 'number', 'string', 'list', 'bool', 'map'
'allowed-values'	* | Map	No	Allowed values as a flat list, or a nested schema map when the attribute type is 'map'. When a list, each element of the attribute value is checked individually.
'validator'	String	No	Name key matching an entry in $validators

Nested Schemas

When 'allowed-values' is a map and the attribute value is also a map, validate recurses into the nested schema using the same mode and custom validators:

$schema: (
  'config': (
    'is-required': true,
    'allowed-types': 'map',
    'allowed-values': (
      'theme': ('is-required': true,  'allowed-types': 'string', 'allowed-values': ('light', 'dark')),
      'scale': ('is-required': false, 'allowed-types': 'number'),
    ),
  ),
);

v.validate($schema, ('config': ('theme': 'dark', 'scale': 1.5)), 'settings', 'app')
// → null

v.validate($schema, ('config': ('theme': 'blue')), 'settings', 'app')
// → '[SETTINGS_THEME_VALUE] Settings "app" @ config > theme: Invalid value "blue" → Allowed: light | dark'

---

Validation Modes

Mode	Unknown attributes	Missing optional attributes
'permissive'	Allowed	Skipped
'rigid'	Error	Skipped
'strict'	Error	Error

The default mode is 'rigid'. Override per-call via $mode, or globally via $VALIDATION_MODE_SELECTED:

v.validate($schema, $entity, 'person', 'Alice', $mode: 'permissive')  // extra fields allowed
v.validate($schema, $entity, 'person', 'Alice', $mode: 'rigid')       // default
v.validate($schema, $entity, 'person', 'Alice', $mode: 'strict')      // all fields required

---

Custom Validators

A custom validator is a Sass function that performs checks on an attribute value beyond type and 'allowed-values' validation. It is called after both pass and must return null on success or an error string on failure.

Register validators by passing a map of name strings to Sass function references via $validators. A validator name present in a schema but absent from this map triggers an "unresolved function" error at runtime.

Custom validator functions receive these positional arguments:

Position	Name	Type	Description
1	$entity	Map	The full entity map
2	$attribute	String	The attribute name being validated
3	$attribute-rules	Map	The schema rules map for this attribute
4	$code-base	String	Error code prefix (e.g. 'PERSON_AGE')
5	$entity-type-cap	String	Capitalized entity type (e.g. 'Person')
6	$entity-name	String	The entity name (e.g. 'Alice')
7	$current-path	List	Current path list (e.g. ('age',))
8	$custom-entry-label	String	Entry label for error codes

Returns Null on success, String error message on failure.

@use 'sass-valid' as v;
@use 'sass:meta';
@use 'sass:map';

@function -positive-number($entity, $attribute, $rules, $code, $type, $name, $path, $label) {
  $value: map.get($entity, $attribute);
  @if $value <= 0 {
    @return '[#{$code}_VALUE] #{$type} "#{$name}" @ #{$attribute}: Invalid value "#{$value}" → Expected: positive number';
  }
  @return null;
}

$schema: (
  'count': ('is-required': true, 'allowed-types': 'number', 'validator': 'positive-number'),
);

$validators: ('positive-number': meta.get-function('-positive-number'));

v.validate($schema, ('count': 5),  'item', 'box', $validators: $validators)
// → null

v.validate($schema, ('count': -1), 'item', 'box', $validators: $validators)
// → '[ITEM_COUNT_VALUE] Item "box" @ count: Invalid value "-1" → Expected: positive number'

---

Migration

v1 → v2

• $custom-validators renamed to $validators
• ARGUMENT_CUSTOM_VALIDATORS_TYPE renamed to ARGUMENT_VALIDATORS_TYPE

---

Back to top