Skip to content

l0.DependencyControl.JsonSchema

JsonSchema = require "l0.DependencyControl.JsonSchema"

local JsonSchema = require("l0.DependencyControl.JsonSchema")

JsonSchema

JSON schema loading and validation utilities. Depends on the lua-schema library for validation, which must be manually installed via LuaRocks and/or otherwise made available on the Lua path by the user.

Constructor 

jsonSchema = JsonSchema schemaOrSchemaPath, logger

local jsonSchema = JsonSchema(schemaOrSchemaPath, logger)

Loads and parses a JSON schema, ready to validate against.

param type description
schemaOrSchemaPath table|string The JSON schema, either as a path to the schema file or a pre-parsed table.
logger? Logger Logger for load/parse errors (defaults to a shared JsonSchema logger).

Instance methods

validate 

jsonSchema\validate data

jsonSchema:validate(data)

Validates a Lua value against the loaded schema. Best-effort: returns the validation result rather than raising, so callers can warn and continue. Returns nil (plus a message) when validation couldn't be performed at all.

param type description
data table The value to validate.

Returns:

  • valid boolean? — True/false on a completed validation, nil if it couldn't run.
  • err string? — The validation errors if validation failed, or an error message when validation could not be performed.

Class methods

getSchemasInDirectory 

JsonSchema\getSchemasInDirectory schemaDir, fileNamePattern

JsonSchema:getSchemasInDirectory(schemaDir, fileNamePattern)

Finds the versioned schema files in a directory, mapping each file's declared version to its path.

param type description
schemaDir string Directory to scan.
fileNamePattern? string Lua pattern matched against each filename, capturing the version (default matches vX.Y.Z.json).

Returns:

  • schemaPathsByVersion table<string, string>? — Version → full file path, or nil when the directory can't be read or holds no matching file.
  • err string? — The failure message accompanying a nil result.

validateAny 

JsonSchema\validateAny data, schemasByVersion, dataSchemaVersion

JsonSchema:validateAny(data, schemasByVersion, dataSchemaVersion)

Validates data against the best-matching schema from the provided versions. A document's own root $schema names its version authoritatively; otherwise the given version hint is tried first, then each remaining schema highest-version-first.

param type description
data table The value to validate.
schemasByVersion table<string, string|JsonSchema> Version → schema file path or ready instance.
dataSchemaVersion? string|fun(data: table): string? Version hint for data with no $schema: a fixed version, or a function that derives it from the data (e.g. a feed reading its own dependencyControlFeedFormatVersion, a field that predates $schema).

Returns:

  • valid boolean? — True/false on a completed validation, nil if none could run.
  • version string? — The schema version validated against, or nil when none matched.
  • err string? — Validation errors on failure, or a message when validation couldn't run.

Fields

field type description
JSON_SCHEMA_ID_KEYWORD string