@ouas/validator

The OpenUI Adaptive Standard (OUAS) Validation Engine.

This package implements the core 7-step validation pipeline and config migrator. It ensures that any Layout Config generated by an AI agent is syntactically correct, matches the application's manifest, complies with custom component-level constraints, and is perfectly safe to render.

Installation

pnpm add @ouas/validator
# or
npm install @ouas/validator

Core Features

1. 7-Step Validation Pipeline

The validator runs the following sequence of checks:

1. Schema Check: Validates layout config structure against the standard JSON Schema via Ajv. Also enforces a strict 4KB size limit on configs to prevent payload bloat.
2. App ID Matching: Ensures config.app_id matches manifest.app_id.
3. Component Existence: Ensures every component ID used exists in the Manifest.
4. Field Existence: Confirms all referenced fields are valid options on that specific component.
5. Required Fields Check: Validates that all fields marked as required in the manifest are present in visible_fields in the layout.
6. Constraint Rules: Verifies custom restrictions (e.g., matching the manifest's min_fields_visible rules).
7. Data Source Validation: Checks component-to-data-source bindings for structural mismatches.

2. Layout Schema Validation

Checks metadata rules, string bounds, and region count limits (maximum 20 regions).

3. Config Migrator

Migrates older config JSON objects to work with newer versions of the Component Manifest standard using version markers.

API & Usage Examples

Validating a Layout Config

import { validateLayoutConfig } from '@ouas/validator';
import type { Manifest, LayoutConfig } from '@ouas/validator';

const manifest: Manifest = {
  ouas_version: "1.0.0",
  app_id: "com.example.app",
  app_name: "My App",
  generated_at: new Date().toISOString(),
  components: [
    {
      id: "email-row",
      display_name: "Email Row",
      category: "list",
      data_source: "emails",
      fields: {
        sender: { type: "string", required: true },
        subject: { type: "string", required: false }
      },
      variants: ["comfortable"],
      slots: []
    }
  ],
  data_sources: [],
  constraints: {}
};

const badConfig: LayoutConfig = {
  ouas_version: "1.0.0",
  config_id: "cfg-001",
  app_id: "com.example.app",
  user_id: "user-123",
  created_at: new Date().toISOString(),
  layout: {
    type: "single-column",
    regions: [
      {
        id: "main",
        component: "email-row",
        variant: "comfortable",
        visible_fields: ["subject"] // ERROR: Missing required 'sender' field!
      }
    ]
  }
};

const result = validateLayoutConfig(badConfig, manifest);

if (!result.valid) {
  console.error("Validation failed with errors:", result.errors);
  /* Output:
     [{
       code: "REQUIRED_FIELD_HIDDEN",
       message: "Required field 'sender' of component 'email-row' is not visible in region 'main'.",
       field: "sender"
     }]
  */
}

Checking Config String Sizes

import { checkConfigSizeLimits } from '@ouas/validator';

const rawJsonString = JSON.stringify(config);
const sizeErrors = checkConfigSizeLimits(rawJsonString);

if (sizeErrors.length > 0) {
  console.warn("Payload size validation failed:", sizeErrors);
}

License

MIT © OUAS Team