json-schema-form-vue3/README.md

A Vue 3 component for editing JSON Schema with nested object and array support

# JSON Schema Form Vue3 + Element Plus

A Vue 3 component for editing JSON Schema with nested object and array support, built with Element Plus.

[中文文档](./README_zh.md)

## Installation

```bash
npm install @json-schema-form-vue3
```

## Features

- Support for all JSON Schema types
- Nested object properties
- Array type with customizable item types
- Clean and modern UI with Element Plus
- Full TypeScript support
- Easy to use v-model interface

## Quick Start

### 1. Install Dependencies

```bash
npm install json-schema-form-vue3 element-plus
```

### 2. Use in Your Component

You can use the component in two ways:

#### Global Registration

```typescript
import { createApp } from 'vue'
import JsonSchemaFormVue3 from 'json-schema-form-vue3'
import 'json-schema-form-vue3/style.css'  // Don't forget to import styles

const app = createApp(App)
app.use(JsonSchemaFormVue3)
```

Then in your components:
```vue
<template>
  <json-schema-form v-model="schema" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { JsonSchema } from 'json-schema-form-vue3'

const schema = ref<JsonSchema>({
  type: 'object',
  properties: {
    name: {
      type: 'string',
      title: 'Name'
    },
    age: {
      type: 'number',
      title: 'Age'
    },
    hobbies: {
      type: 'array',
      title: 'Hobbies',
      items: {
        type: 'string'
      }
    },
    address: {
      type: 'object',
      title: 'Address',
      properties: {
        street: {
          type: 'string',
          title: 'Street'
        },
        city: {
          type: 'string',
          title: 'City'
        }
      }
    }
  },
  required: ['name', 'age']
})
</script>
```

## Component API

### Props

| Property | Type | Required | Default | Description |
|----------|------|----------|----------|-------------|
| modelValue | JsonSchema \| SchemaProperty | Yes | - | The JSON Schema object bound through v-model |
| isRootLevel | boolean | No | true | Whether this is a root level editor (affects UI display) |

### Events

| Event Name | Parameter Type | Description |
|------------|---------------|-------------|
| update:modelValue | JsonSchema \| SchemaProperty | Emitted when the schema changes |

## Type Definitions

```typescript
interface SchemaProperty {
  type: JSONSchema7TypeName; // 'string' | 'number' | 'integer' | 'object' | 'array' | 'boolean' | 'null'
  title?: string;
  description?: string;
  properties?: Record<string, SchemaProperty>;
  items?: SchemaProperty;
  required?: string[];
}

interface JsonSchema {
  type: 'object';
  properties: Record<string, SchemaProperty>;
  required?: string[];
  $schema?: string;
  $id?: string;
  $comment?: string;
  title?: string;
  description?: string;
}
```

## Advanced Usage

### Nested Objects Example

```vue
<template>
  <json-schema-form v-model="schema" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import JsonSchemaForm from 'json-schema-form-vue3'
import type { JsonSchema } from 'json-schema-form-vue3'

const schema = ref<JsonSchema>({
  type: 'object',
  properties: {
    user: {
      type: 'object',
      title: 'User Information',
      properties: {
        basicInfo: {
          type: 'object',
          title: 'Basic Information',
          properties: {
            name: {
              type: 'string',
              title: 'Name'
            },
            age: {
              type: 'number',
              title: 'Age'
            }
          },
          required: ['name']
        },
        contact: {
          type: 'object',
          title: 'Contact Information',
          properties: {
            email: {
              type: 'string',
              title: 'Email'
            },
            phone: {
              type: 'string',
              title: 'Phone'
            }
          }
        }
      }
    }
  }
})
</script>
```

### Array Type Example

```vue
<template>
  <json-schema-form v-model="schema" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import JsonSchemaForm from 'json-schema-form-vue3'
import type { JsonSchema } from 'json-schema-form-vue3'

const schema = ref<JsonSchema>({
  type: 'object',
  properties: {
    tags: {
      type: 'array',
      title: 'Tags',
      items: {
        type: 'string'
      }
    },
    contacts: {
      type: 'array',
      title: 'Contacts',
      items: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
            title: 'Name'
          },
          phone: {
            type: 'string',
            title: 'Phone'
          }
        }
      }
    }
  }
})
</script>
```

## Development

Build from source:

```bash
git clone <repository-url>
cd json-schema-form-vue3
npm install
npm run build
```

For more information about Vue 3 TypeScript project setup, visit [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).