feat(schema-form): add array support and AJV validation

DSingh0304 · DSingh0304 · commit fb8581c33eb6 · 2026-01-16T12:42:48.000+05:30
- Add ArrayField component using useFieldArray for object arrays - Add string array support using TagsInput - Create validation.ts with AJV integration - Add createSchemaResolver for React Hook Form - Map AJV errors to user-friendly messages - Test with real proxy-rewrite plugin schema - Add tabs to demo page for schema comparison Addresses feedback from Issue #2986
diff --git a/.gitignore b/.gitignore
@@ -32,3 +32,5 @@ dist-ssr
 /playwright/.cache/
 
 .eslintcache
+jsonschema-poc/POC_SUMMARY.md
+jsonschema-poc/README.md
diff --git a/package.json b/package.json
@@ -23,6 +23,8 @@
     "@monaco-editor/react": "^4.7.0",
     "@tanstack/react-query": "^5.74.4",
     "@tanstack/react-router": "^1.116.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "antd": "^5.24.8",
     "axios": "^1.13.2",
     "clsx": "^2.1.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/components/form/SchemaForm/ArrayField.tsx b/src/components/form/SchemaForm/ArrayField.tsx
@@ -0,0 +1,143 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/* eslint-disable i18next/no-literal-string */
+import { ActionIcon, Button, Fieldset, Group, Stack, Text } from '@mantine/core';
+import type { Control, FieldValues } from 'react-hook-form';
+import { useFieldArray } from 'react-hook-form';
+import IconPlus from '~icons/material-symbols/add';
+import IconTrash from '~icons/material-symbols/delete-outline';
+
+import { SchemaField } from './SchemaField';
+import type { JSONSchema7 } from './types';
+
+export type ArrayFieldProps = {
+    name: string;
+    schema: JSONSchema7;
+    control: Control<FieldValues>;
+    required?: boolean;
+};
+
+/**
+ * ArrayField - Renders a dynamic array of fields using useFieldArray
+ *
+ * Handles:
+ * - Arrays of objects with Add/Remove functionality
+ * - Nested object schemas within array items
+ */
+export const ArrayField = ({ name, schema, control, required: _required }: ArrayFieldProps) => {
+    const { fields, append, remove } = useFieldArray({
+        control,
+        name,
+    });
+
+    const itemSchema = schema.items as JSONSchema7;
+
+    // Generate default values for new items based on schema
+    const getDefaultItem = (): Record<string, unknown> => {
+        if (itemSchema.type !== 'object' || !itemSchema.properties) {
+            return {};
+        }
+
+        const defaultItem: Record<string, unknown> = {};
+        Object.entries(itemSchema.properties).forEach(([key, propSchema]) => {
+            const prop = propSchema as JSONSchema7;
+            if (prop.default !== undefined) {
+                defaultItem[key] = prop.default;
+            } else if (prop.type === 'string') {
+                defaultItem[key] = '';
+            } else if (prop.type === 'number' || prop.type === 'integer') {
+                defaultItem[key] = 0;
+            } else if (prop.type === 'boolean') {
+                defaultItem[key] = false;
+            }
+        });
+        return defaultItem;
+    };
+
+    const handleAdd = () => {
+        append(getDefaultItem());
+    };
+
+    const formatLabel = (fieldName: string): string => {
+        const name = fieldName.split('.').pop() || fieldName;
+        return name
+            .split('_')
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    };
+
+    return (
+        <Fieldset legend={schema.title || formatLabel(name)} mt="md">
+            <Stack gap="md">
+                {schema.description && (
+                    <Text size="sm" c="dimmed">
+                        {schema.description}
+                    </Text>
+                )}
+
+                {fields.length === 0 && (
+                    <Text size="sm" c="dimmed" fs="italic">
+                        No items added yet. Click "Add Item" to begin.
+                    </Text>
+                )}
+
+                {fields.map((field, index) => (
+                    <Fieldset key={field.id} variant="filled">
+                        <Group justify="space-between" mb="sm">
+                            <Text size="sm" fw={500}>
+                                Item {index + 1}
+                            </Text>
+                            <ActionIcon
+                                variant="subtle"
+                                color="red"
+                                size="sm"
+                                onClick={() => remove(index)}
+                                aria-label={`Remove item ${index + 1}`}
+                            >
+                                <IconTrash />
+                            </ActionIcon>
+                        </Group>
+
+                        <Stack gap="sm">
+                            {itemSchema.properties &&
+                                Object.entries(itemSchema.properties).map(
+                                    ([key, propSchema]) => (
+                                        <SchemaField
+                                            key={`${name}.${index}.${key}`}
+                                            name={`${name}.${index}.${key}`}
+                                            schema={propSchema as JSONSchema7}
+                                            control={control}
+                                            required={itemSchema.required?.includes(key)}
+                                        />
+                                    )
+                                )}
+                        </Stack>
+                    </Fieldset>
+                ))}
+
+                <Button
+                    variant="light"
+                    leftSection={<IconPlus />}
+                    onClick={handleAdd}
+                    size="sm"
+                >
+                    Add Item
+                </Button>
+            </Stack>
+        </Fieldset>
+    );
+};
diff --git a/src/components/form/SchemaForm/SchemaField.tsx b/src/components/form/SchemaForm/SchemaField.tsx
@@ -20,7 +20,9 @@ import type { Control, FieldValues } from 'react-hook-form';
 import { FormItemNumberInput } from '../NumberInput';
 import { FormItemSelect } from '../Select';
 import { FormItemSwitch } from '../Switch';
+import { FormItemTextArray } from '../TextArray';
 import { FormItemTextInput } from '../TextInput';
+import { ArrayField } from './ArrayField';
 import type { JSONSchema7 } from './types';
 
 export type SchemaFieldProps = {
@@ -61,6 +63,36 @@ export const SchemaField = (
         );
     }
 
+    // Handle arrays
+    if (schema.type === 'array' && schema.items) {
+        const itemSchema = schema.items as JSONSchema7;
+
+        // Simple string/number arrays → TagsInput
+        if (itemSchema.type === 'string' || itemSchema.type === 'number') {
+            return (
+                <FormItemTextArray
+                    name={name}
+                    control={control}
+                    label={schema.title || formatLabel(name)}
+                    description={schema.description}
+                    placeholder={`Add ${formatLabel(name).toLowerCase()} and press Enter`}
+                />
+            );
+        }
+
+        // Object arrays → Use ArrayField with useFieldArray
+        if (itemSchema.type === 'object') {
+            return (
+                <ArrayField
+                    name={name}
+                    schema={schema}
+                    control={control}
+                    required={required}
+                />
+            );
+        }
+    }
+
     // Handle enums → Select dropdown
     if (schema.enum) {
         return (
diff --git a/src/components/form/SchemaForm/index.tsx b/src/components/form/SchemaForm/index.tsx
@@ -239,5 +239,7 @@ function findDiscriminators(oneOf: JSONSchema7['oneOf']): string[] {
     return Array.from(discriminators);
 }
 
+export { ArrayField } from './ArrayField';
 export { SchemaField } from './SchemaField';
 export type { JSONSchema7 } from './types';
+export { createSchemaResolver, validateWithSchema } from './validation';
diff --git a/src/components/form/SchemaForm/types.ts b/src/components/form/SchemaForm/types.ts
@@ -50,6 +50,8 @@ export interface JSONSchema7 {
     properties?: Record<string, JSONSchema7>;
     required?: string[];
     additionalProperties?: boolean | JSONSchema7;
+    minProperties?: number;
+    maxProperties?: number;
 
     // Enum
     enum?: unknown[];
diff --git a/src/components/form/SchemaForm/validation.ts b/src/components/form/SchemaForm/validation.ts
@@ -0,0 +1,171 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import Ajv, { type ErrorObject } from 'ajv';
+import addFormats from 'ajv-formats';
+import type { FieldErrors, FieldValues } from 'react-hook-form';
+
+import type { JSONSchema7 } from './types';
+
+// Create AJV instance with formats support
+const ajv = new Ajv({
+    allErrors: true, // Report all errors, not just the first one
+    verbose: true, // Include schema and data in error objects
+    strict: false, // Be lenient with schema keywords
+});
+
+// Add format validators (email, uri, date, etc.)
+addFormats(ajv);
+
+/**
+ * Validates form data against a JSON Schema using AJV
+ * @param schema - The JSON Schema to validate against
+ * @param data - The form data to validate
+ * @returns Object containing isValid flag and any errors
+ */
+export function validateWithSchema<T extends FieldValues>(
+    schema: JSONSchema7,
+    data: T
+): { isValid: boolean; errors: FieldErrors<T> } {
+    const validate = ajv.compile(schema);
+    const isValid = validate(data);
+
+    if (isValid) {
+        return { isValid: true, errors: {} as FieldErrors<T> };
+    }
+
+    // Map AJV errors to React Hook Form format
+    const errors = mapAjvErrorsToFormErrors<T>(validate.errors || []);
+    return { isValid: false, errors };
+}
+
+/**
+ * Maps AJV error objects to React Hook Form field errors format
+ * AJV uses JSON Pointer format (e.g., "/headers/add/0/name")
+ * React Hook Form uses dot notation (e.g., "headers.add.0.name")
+ */
+function mapAjvErrorsToFormErrors<T extends FieldValues>(
+    ajvErrors: ErrorObject[]
+): FieldErrors<T> {
+    const errors: Record<string, { type: string; message: string }> = {};
+
+    ajvErrors.forEach((error) => {
+        // Convert AJV instance path to form field path
+        // AJV: "/headers/add/0/name" -> RHF: "headers.add.0.name"
+        let fieldPath = error.instancePath
+            .replace(/^\//, '') // Remove leading slash
+            .replace(/\//g, '.'); // Replace slashes with dots
+
+        // Handle root-level errors (required fields at root)
+        if (error.keyword === 'required' && error.params.missingProperty) {
+            const missingProp = error.params.missingProperty as string;
+            fieldPath = fieldPath ? `${fieldPath}.${missingProp}` : missingProp;
+        }
+
+        // Handle additionalProperties error
+        if (error.keyword === 'additionalProperties' && error.params.additionalProperty) {
+            const extraProp = error.params.additionalProperty as string;
+            fieldPath = fieldPath ? `${fieldPath}.${extraProp}` : extraProp;
+        }
+
+        // Skip if no field path (root-level schema errors)
+        if (!fieldPath && !['required', 'minProperties'].includes(error.keyword)) {
+            return;
+        }
+
+        // Generate user-friendly error message
+        const message = generateErrorMessage(error);
+
+        // Don't overwrite existing errors for the same field
+        if (!errors[fieldPath || '_root']) {
+            errors[fieldPath || '_root'] = {
+                type: error.keyword,
+                message,
+            };
+        }
+    });
+
+    return errors as unknown as FieldErrors<T>;
+}
+
+/**
+ * Generates a user-friendly error message from an AJV error
+ */
+function generateErrorMessage(error: ErrorObject): string {
+    const { keyword, params, message } = error;
+
+    switch (keyword) {
+        case 'required':
+            return `${formatFieldName(params.missingProperty as string)} is required`;
+        case 'type':
+            return `Must be a ${params.type}`;
+        case 'minLength':
+            return `Must be at least ${params.limit} characters`;
+        case 'maxLength':
+            return `Must be at most ${params.limit} characters`;
+        case 'minimum':
+            return `Must be at least ${params.limit}`;
+        case 'maximum':
+            return `Must be at most ${params.limit}`;
+        case 'pattern':
+            return `Invalid format`;
+        case 'enum':
+            return `Must be one of: ${(params.allowedValues as string[]).join(', ')}`;
+        case 'minItems':
+            return `Must have at least ${params.limit} items`;
+        case 'maxItems':
+            return `Must have at most ${params.limit} items`;
+        case 'format':
+            return `Invalid ${params.format} format`;
+        case 'additionalProperties':
+            return `Unknown field: ${params.additionalProperty}`;
+        default:
+            return message || 'Invalid value';
+    }
+}
+
+/**
+ * Formats a field name for display in error messages
+ * e.g., "oauth_client_id" -> "OAuth Client ID"
+ */
+function formatFieldName(name: string): string {
+    if (!name) return 'This field';
+    return name
+        .split('_')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+
+/**
+ * Creates a React Hook Form resolver that uses AJV for validation
+ * This can be passed to useForm({ resolver: createSchemaResolver(schema) })
+ */
+export function createSchemaResolver(schema: JSONSchema7) {
+    return async <T extends FieldValues>(data: T) => {
+        const { isValid, errors } = validateWithSchema(schema, data);
+
+        if (isValid) {
+            return { values: data, errors: {} };
+        }
+
+        return {
+            values: {},
+            errors,
+        };
+    };
+}
+
+export { ajv };
diff --git a/src/routes/schema_form_demo.tsx b/src/routes/schema_form_demo.tsx

Original file line number	Diff line number	Diff line change
`@@ -239,5 +239,7 @@ function findDiscriminators(oneOf: JSONSchema7['oneOf']): string[] {`
`239`	`239`	`return Array.from(discriminators);`
`240`	`240`	`}`
`241`	`241`
	`242`	`+export { ArrayField } from './ArrayField';`
`242`	`243`	`export { SchemaField } from './SchemaField';`
`243`	`244`	`export type { JSONSchema7 } from './types';`
	`245`	`+export { createSchemaResolver, validateWithSchema } from './validation';`