Validation & Diagnostics

Every generated class has a matching validator so runtime data can be checked with a similar fidelity as the type system. This guide shows how to compose them, interpret diagnostics, and plug them into tooling.

Import patterns

import type { Organization } from '@avensio/jsonld-schema/classes/Organization'
import { validateOrganization } from '@avensio/jsonld-schema/validation/classes/Organization.validator'

• Type imports reference the generated interfaces under classes/.
• Validator modules live under validation/classes/ (for objects) and validation/properties/ (for property-specific checks).

Running validators

Validators return a Promise<Diagnostic[]>. An empty array means success; otherwise, loop through diagnostics to present friendly errors.

const diagnostics = await validateOrganization(candidate)

if (diagnostics.length) {
  diagnostics.forEach(diag => {
    console.warn(`${diag.severity.toUpperCase()}: ${diag.message} at ${diag.path ?? '<root>'}`)
  })
}

Diagnostic shape

Each diagnostic follows the Diagnostic interface exported from dist/validation/core.d.ts:

• severity: error or warning
• message: human-readable description
• path: JSON pointer-style path to the offending value
• code: optional identifier for programmatic handling

Unit tests under test/validators.datatypes.test.ts and test/validators.classes.test.ts provide concrete expectations for primitive validators (isText, isUrl, etc.) and complex classes. Use them as references when adding new edge cases.

Common helpers

dist/validation/index.js re-exports utility validators such as validateArrayOfText, validateTypedObjectField, and primitive guard functions (isNumber, isUrl). Combine them when crafting bespoke validators or when validating partial payloads outside the generated class surface.

Workflow tips

1. Prefer generated class validators for end-to-end checks—they enforce contexts, required properties, and allowed ranges.
2. Reach for property validators when validating streaming data (e.g. user input for a single field) to avoid loading full class definitions.
3. Keep diagnostics as part of API responses or CLI output so downstream tooling can highlight every violation in one pass.