@makehq/forman-schema 1.2.5 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Forman Schema
 
-A utility for converting between Forman Schema and JSON Schema.
+Conversion and validation utilities for Forman Schema.
 
 ## Installation
 
@@ -54,6 +54,121 @@ const jsonSchemaField = {
 const formanSchema = toFormanSchema(jsonSchemaField);
 ```
 
+### Validation
+
+Validate Forman values against a Forman Schema. Two entry points are available:
+
+- `validateForman(values, schema, options?)` — validate without domains.
+- `validateFormanWithDomains(domains, options?)` — validate multiple domains at once.
+
+Both return `{ valid: boolean, errors: { path: string, message: string }[] }`.
+
+#### Basic validation
+
+```typescript
+import { validateForman } from '@makehq/forman-schema';
+
+const values = { array: [1, 2, 3], text: 'hello' };
+const schema = [
+    { name: 'array', type: 'array', spec: { type: 'number' } },
+    { name: 'text', type: 'text' },
+];
+
+const result = await validateForman(values, schema);
+// { valid: true, errors: [] }
+```
+
+#### Strict mode (unknown fields)
+
+```typescript
+const values = { text: 15, unknown: true };
+const schema = [
+    {
+        name: 'text',
+        type: 'text',
+    },
+];
+
+const result = await validateForman(values, schema, { strict: true });
+// {
+//   valid: false,
+//   errors: [
+//     { path: 'default.text', message: "Expected type 'string', got type 'number'" },
+//     { path: 'default', message: "Unknown field 'unknown'" }
+//   ]
+// }
+```
+
+#### Select with nested fields
+
+```typescript
+const values = { sheet: 'sheet 1', row: 1 };
+const schema = [
+    {
+        name: 'sheet',
+        type: 'select',
+        options: [
+            { value: 'sheet 1', nested: [{ name: 'row', type: 'number', required: true }] },
+            { value: 'sheet 2' },
+        ],
+    },
+];
+
+const result = await validateForman(values, schema);
+```
+
+#### Remote options and nested stores
+
+You can resolve options or nested field stores by providing `resolveRemote(path, data)`.
+
+```typescript
+const values = { sheet: 'sheet 1', column: 'A1' };
+const schema = [
+    {
+        name: 'sheet',
+        type: 'select',
+        options: {
+            store: 'rpc://sheets',
+            nested: [{ name: 'column', type: 'select', options: 'rpc://columns' }],
+        },
+    },
+];
+
+const result = await validateForman(values, schema, {
+    async resolveRemote(path, data) {
+        if (path === 'rpc://sheets') return [{ value: 'sheet 1' }, { value: 'sheet 2' }];
+        if (path === 'rpc://columns') return [{ value: 'A1' }, { value: 'B1' }];
+        throw new Error('Unknown resource');
+    },
+});
+```
+
+#### Multi-domain validation
+
+Use `validateFormanWithDomains` to validate cross-domain schemas (e.g., `default` and `additional`).
+
+```typescript
+import { validateFormanWithDomains } from '@makehq/forman-schema';
+
+const result = await validateFormanWithDomains(
+    {
+        default: {
+            values: { ... },
+            schema: defaultSchema
+        },
+        additional: {
+            values: { ... },
+            schema: additionalSchema
+        },
+    },
+    {
+        async resolveRemote(path, data) {
+            // resolve API-backed options/nested fields here
+        },
+    },
+);
+```
+
 ## Supported Types
 
 ### Forman Schema Types