@authvia/ajv-schema-forms

A Vue 3 library for generating forms from JSON Schema using JSON Forms. This library provides a simple way to create dynamic forms with validation based on JSON Schema specifications.

Vue 3 Usage

Presuming you already have a Vue3 application configured usage is pretty straight forward.

1. Install the module: npm install --save @authvia/ajv-schema-forms
2. Register plugins

  // Make sure vuetify is set to auto import components.
  app.use(vuetify)
  app.use(ajvSchemaFormPlugin)

If vuetify styles are not enabled in your vue 3 project your index.html will need to add these two CSS resources.

<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/vuetify.min.css" rel="stylesheet" />
<link href="https://cdn.materialdesignicons.com/5.4.55/css/materialdesignicons.min.css" rel="stylesheet" />

Components

av-schema-form

The main component for rendering forms from JSON Schema.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | schema | Schema | Yes | - | JSON Schema defining the form structure and validation rules | | uischema | Object | No | undefined | JSON Forms UI Schema defining the form layout and presentation | | data | Object | No | {} | Initial data to populate the form | | variant | String | No | 'filled' | Vuetify input variant: 'filled', 'outlined', 'plain', 'underlined', 'solo', 'solo-inverted', 'solo-filled'. Note: This is now controlled by the variant property in uischema | | orientation | String | No | 'vertical' | Form layout orientation: 'vertical' (stacked) or 'horizontal' (side-by-side). Note: This is now controlled by the type in uischema (VerticalLayout or HorizontalLayout) | | disabled | Boolean | No | false | Disables all interaction with the form | | loading | Boolean | No | false | Puts the form in a loading visual state | | showSubmitButton | Boolean | No | true | Controls whether the submit button is shown | | errors | Object | No | {} | Validation errors to display on the form |

Events

• submit: Emitted when the form is submitted with valid data

Slots

• submit-button: Custom submit button slot

Schema vs UISchema

The component supports separate schema and uischema props for better separation of concerns:

• schema: Contains the data structure, validation rules, and data-specific properties
• uischema: Contains UI presentation rules and UI-specific properties

Schema (Data Structure)

const schema = {
  type: 'object',
  required: ['name', 'email'],
  properties: {
    name: {
      $id: '#root/name',
      title: 'Name',
      type: 'string',
      description: 'Enter your full name',
      maxLength: 50
    },
    email: {
      $id: '#root/email',
      title: 'Email',
      type: 'string',
      format: 'email',
      description: 'Enter your email address'
    }
  }
}

UISchema (UI Presentation)

const uischema = {
  type: 'VerticalLayout',
  elements: [
    {
      type: 'Control',
      scope: '#/properties/name',
      label: 'Name',
      options: {
        multi: true // Makes it a textarea
      }
    },
    {
      type: 'Control',
      scope: '#/properties/email',
      label: 'Email',
      options: {
        format: 'email'
      }
    }
  ]
}

Example

<template>
  <av-schema-form 
    :schema="mySchema" 
    :uischema="myUISchema"
    @submit="handleSubmit"
    variant="outlined"
  />
</template>

<script setup>
import { AvSchemaForm } from '@authvia/ajv-schema-forms'

const mySchema = {
  type: 'object',
  required: ['name', 'email'],
  properties: {
    name: {
      $id: '#root/name',
      title: 'Name',
      type: 'string',
      description: 'Enter your full name'
    },
    email: {
      $id: '#root/email',
      title: 'Email',
      type: 'string',
      format: 'email',
      description: 'Enter your email address'
    }
  }
}

const myUISchema = {
  type: 'VerticalLayout',
  elements: [
    {
      type: 'Control',
      scope: '#/properties/name',
      label: 'Name',
      options: {
        multi: true
      }
    },
    {
      type: 'Control',
      scope: '#/properties/email',
      label: 'Email'
    }
  ]
}

const handleSubmit = (data) => {
  console.log('Form submitted:', data)
}
</script>

Usage Examples

Basic Usage

<template>
  <av-schema-form
    :schema="schema"
    :uischema="uischema"
    @submit="handleSubmit"
  />
</template>

With Variants and Orientation

<template>
  <!-- Outlined variant with horizontal layout -->
  <av-schema-form
    :schema="schema"
    :uischema="{ type: 'HorizontalLayout', variant: 'outlined', elements: [...] }"
    @submit="handleSubmit"
  />
  
  <!-- Solo variant with vertical layout -->
  <av-schema-form
    :schema="schema"
    :uischema="{ type: 'VerticalLayout', variant: 'solo', elements: [...] }"
    @submit="handleSubmit"
  />
</template>

With Pre-filled Data

<template>
  <av-schema-form
    :schema="schema"
    :uischema="uischema"
    :data="initialData"
    @submit="handleSubmit"
  />
</template>

<script setup>
const initialData = {
  name: 'John Doe',
  email: '[email protected]',
  category: 'Gold'
}
</script>

With Arrays

<template>
  <av-schema-form
    :schema="schema"
    :uischema="uischema"
    @submit="handleSubmit"
  />
</template>

<script setup>
const schema = {
  type: 'object',
  properties: {
    comments: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          message: { type: 'string', title: 'Message' },
          priority: { type: 'string', enum: ['Low', 'Medium', 'High'] }
        }
      }
    }
  }
}

const uischema = {
  type: 'VerticalLayout',
  elements: [
    {
      type: 'Control',
      scope: '#/properties/comments',
      options: {
        addButtonLabel: 'Add Comment',
        detail: {
          type: 'VerticalLayout',
          elements: [
            { type: 'Control', scope: '#/properties/message' },
            { type: 'Control', scope: '#/properties/priority' }
          ]
        }
      }
    }
  ]
}
</script>

JSON Schema Support

This component uses JSON Forms for rendering and validation, providing robust support for:

• String, number, integer, and boolean types
• Enum values with dropdown selection
• Money format with cents conversion
• Multiline text areas
• Pattern validation
• Min/max length and value constraints
• Required field validation

UI-Specific Properties

The following properties are handled in the uischema:

• format: 'money' - Renders money input with cents conversion
• multi: true - Renders textarea instead of text input
• multiplier: number - Applies multiplier to money fields
• readonly: boolean - Makes field read-only

Migration from AJV

This library has been migrated from manual AJV validation to JSON Forms for better maintainability and feature support. The API remains largely the same, but validation is now handled automatically by JSON Forms.

Schema/UISchema Separation

The latest version introduces clean separation between data structure (schema) and UI presentation (uischema), providing better maintainability and flexibility.

Layout Control

Form orientation is now controlled by the type property in the uischema:

• VerticalLayout: Form fields are stacked vertically (default)
• HorizontalLayout: Form fields are arranged side-by-side horizontally

Variant Control

Form styling variant is now controlled by the variant property in the uischema:

• filled: Default filled style (default)
• outlined: Outlined border style
• plain: Minimal styling
• underlined: Bottom border only
• solo: Elevated appearance
• solo-inverted: Inset appearance
• solo-filled: Elevated with background

This approach follows JSON Forms conventions and provides more granular control over form styling.

Array Support

The component now supports JSON Schema array types with full CRUD operations:

• Dynamic arrays: Add/remove items dynamically
• Complex items: Array items can be objects with multiple properties
• Nested validation: Each array item follows the schema validation rules
• Custom labels: Configurable add/remove button labels
• Detail layouts: Customizable layout for array item details

Arrays are rendered using JSON Forms' built-in array renderer, providing a user-friendly interface for managing collections of data.