> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joyfill.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Validation

Schema validation in JoyDoc ensures that documents conform to the expected structure and version compatibility. It validates the document's JSON schema against the official JoyDoc schema definition and checks version compatibility.

### Manual Schema Validation

You can also validate schemas manually:

```jsx theme={null}
import { validateSchema } from '@joyfill/components';

const schemaError = validateSchema(doc);

if (schemaError) {
  console.log('Schema validation failed:', schemaError);
} else {
  console.log('Document schema is valid');
}

```

## Enabling/Disabling Schema Validation

### Default Behavior

Schema validation is **enabled by default** in the JoyDoc component.

### Enabling Schema Validation

Schema validation is enabled by default, but you can explicitly enable it:

```jsx theme={null}
<JoyDoc
  doc={document}
  mode="edit"
  features={{
    validateSchema: true  // Explicitly enables schema validation
  }}
/>

```

### Disabling Schema Validation

To disable schema validation, set `features.validateSchema` to `false`:

```jsx theme={null}
<JoyDoc
  doc={document}
  mode="edit"
  features={{
    validateSchema: false  // Disables schema validation
  }}
/>

```

## How Schema Validation Works

### Basic Usage

Schema validation is automatically performed by the JoyDoc component when enabled:

```jsx theme={null}
import { JoyDoc } from '@joyfill/components';

// Schema validation is enabled by default
<JoyDoc
  doc={document}
  mode="edit"
	features={{
	  validateSchema: true
	}}
  onError={(error) => {
    if (error.code === 'ERROR_SCHEMA_VALIDATION') {
      console.log('Schema validation failed:', error);
    }
  }}
/>

```

## Schema Validation Process

The validation process follows these steps:

1. **Version Compatibility Check**: Verifies the document's schema version is compatible with the current SDK
2. **JSON Schema Validation**: Validates the document structure against the official JoyDoc schema
3. **Error Reporting**: Returns detailed error information if validation fails

## Validation Results

### Success Case

When validation passes, the function returns `undefined`:

```jsx theme={null}
const result = validateSchema(validDoc);
console.log(result); // undefined (no errors)

```

### Error Cases

When validation fails, an error object is returned with the following structure:

```jsx theme={null}
{
  code: 'ERROR_SCHEMA_VALIDATION' | 'ERROR_SCHEMA_VERSION',
  message: 'Error description',
  details: {
    schemaVersion: '2.0.0',
    sdkVersion: '3.1.4'
  },
  errors?: [...] // Only present for schema validation errors
}

```

## Error Types

### 1. Schema Version Error

**Code**: `ERROR_SCHEMA_VERSION`

Occurs when the document's schema version is incompatible with the current SDK version.

```jsx theme={null}
{
  code: 'ERROR_SCHEMA_VERSION',
  message: 'Error detected with targeted schema version.',
  error: 'The targeted version of 1.0.0 is not supported. Version 2.0.0 must be used.',
  details: {
    schemaVersion: '2.0.0',
    sdkVersion: '3.1.4'
  }
}

```

**Common causes:**

* Using an outdated document format
* Document created with an older SDK version
* Manual document editing with incorrect version

### 2. Schema Validation Error

**Code**: `ERROR_SCHEMA_VALIDATION`

Occurs when the document structure doesn't match the expected schema.

```jsx theme={null}
{
  code: 'ERROR_SCHEMA_VALIDATION',
  message: 'Error detected during schema validation',
  details: {
    schemaVersion: '2.0.0',
    sdkVersion: '3.1.4'
  },
  errors: [
    {
      instancePath: '/fields/0',
      schemaPath: '#/properties/fields/items/required',
      keyword: 'required',
      params: { missingProperty: 'type' },
      message: "must have required property 'type'"
    }
  ]
}

```

**Common causes:**

* Missing required properties
* Invalid field types
* Malformed document structure
* Corrupted document data

## Error Handling

### In JoyDoc Component

Handle schema validation errors using the `onError` callback:

```jsx theme={null}
<JoyDoc
  doc={document}
  mode="edit"
  features={{
	  validateSchema: true
  }}
  onError={(error) => {
    switch (error.code) {
      case 'ERROR_SCHEMA_VERSION':
        console.error('Schema version incompatible:', error.error);
        // Handle version incompatibility
        break;
      case 'ERROR_SCHEMA_VALIDATION':
        console.error('Schema validation failed:', error.errors);
        // Handle schema validation errors
        break;
      default:
        console.error('Unknown error:', error);
    }
  }}
/>

```

## Implementation Example

```jsx theme={null}
import React, { useState, useEffect } from "react";
import { JoyDoc, validateSchema } from "@joyfill/components";

function DocumentEditor() {
  const [doc, setDoc] = useState(null);
  const [schemaError, setSchemaError] = useState(null);

  useEffect(() => {
    if (doc) {
      const error = validateSchema(doc);
      setSchemaError(error);
    }
  }, [doc]);

  const handleError = (error) => {
    if (error.code === "ERROR_SCHEMA_VALIDATION") {
      setSchemaError(error);
    }
  };

  return (
    <div>
      {/* Schema Error Display */}
      {schemaError && (
        <div
          style={{
            padding: "20px",
            margin: "20px",
            border: "2px solid #f44336",
            borderRadius: "8px",
            backgroundColor: "#ffebee",
          }}
        >
          <h3 style={{ color: "#c62828", margin: "0 0 10px 0" }}>
            Schema Validation Error
          </h3>
          <p style={{ margin: "0 0 10px 0" }}>{schemaError.message}</p>

          {schemaError.code === "ERROR_SCHEMA_VERSION" && (
            <p style={{ margin: "0 0 10px 0" }}>
              <strong>Error:</strong> {schemaError.error}
            </p>
          )}

          <p style={{ margin: "0 0 10px 0" }}>
            <strong>Schema Version:</strong> {schemaError.details.schemaVersion}
          </p>
          <p style={{ margin: "0 0 10px 0" }}>
            <strong>SDK Version:</strong> {schemaError.details.sdkVersion}
          </p>

          {schemaError.errors && (
            <details style={{ marginTop: "10px" }}>
              <summary style={{ cursor: "pointer", fontWeight: "bold" }}>
                Validation Details
              </summary>
              <pre
                style={{
                  marginTop: "10px",
                  padding: "10px",
                  backgroundColor: "#f5f5f5",
                  borderRadius: "4px",
                  overflow: "auto",
                  fontSize: "12px",
                }}
              >
                {JSON.stringify(schemaError.errors, null, 2)}
              </pre>
            </details>
          )}
        </div>
      )}

      <JoyDoc
        doc={doc}
        mode="edit"
        onError={handleError}
        features={{
          validateSchema: true, // Explicitly enable schema validation
        }}
      />
    </div>
  );
}

export default DocumentEditor;
```

## Key points:

* **Schema validation is enabled by default** in JoyDoc components
* **Version compatibility** is checked using major version numbers
* **Two types of errors**: Schema version errors and schema validation errors
* **Always handle errors** using the `onError` callback
* **Validate documents** before processing to prevent runtime errors
* **Use manual validation** for programmatic document validation