Schema Validation - Joyfill Documentation

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:

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:

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

Disabling Schema Validation

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

<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:

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:

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

Validation Results

Success Case

When validation passes, the function returns undefined:

const result = validateSchema(validDoc);
console.log(result); // undefined (no errors)

Error Cases

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

{
  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.

{
  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.

{
  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:

<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

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

​Manual Schema Validation

​Enabling/Disabling Schema Validation

​Default Behavior

​Enabling Schema Validation

​Disabling Schema Validation

​How Schema Validation Works

​Basic Usage

​Schema Validation Process

​Validation Results

​Success Case

​Error Cases

​Error Types

​1. Schema Version Error

​2. Schema Validation Error

​Error Handling

​In JoyDoc Component

​Implementation Example

​Key points: