@squiz/dx-json-schema-lib

@squiz/dx-json-schema-lib

JSON Schema validation and resolution library for Squiz DX platform, with specialized support for primitive types like SquizLink and SquizImage.

Features

• ✅ JSON Schema validation and resolution
• ✅ Support for custom primitive types (SquizLink, SquizImage, FormattedText)
• ✅ AllOf conditional schema support with data preservation
• ✅ Resolvable types integration (Matrix Assets, etc.)
• ✅ High performance with comprehensive test coverage

Usage

import { JSONSchemaService } from '@squiz/dx-json-schema-lib';
import { TypeResolverBuilder } from '@squiz/dx-json-schema-lib/jsonTypeResolution';
import { SquizLinkType, SquizImageType } from '@squiz/dx-json-schema-lib/primitiveTypes';

// Create service with primitive type support
const typeResolver = new TypeResolverBuilder()
  .addPrimitive(SquizLinkType)
  .addPrimitive(SquizImageType)
  .build();

const service = new JSONSchemaService(typeResolver, schema);

// Resolve input data
const resolvedData = await service.resolveInput(inputData, inputSchema);

AllOf Conditional Schema Support

This library provides robust support for allOf conditional schemas, including data preservation for SquizLink and SquizImage arrays within conditional structures:

// ✅ FULLY SUPPORTED: Single-level allOf conditions
{
  "type": "object",
  "properties": {
    "contentType": { "type": "string", "enum": ["basic", "advanced"] }
  },
  "allOf": [
    {
      "if": { "properties": { "contentType": { "const": "advanced" } } },
      "then": {
        "properties": {
          "links": {
            "type": "array",
            "items": { "type": "SquizLink" }
          }
        }
      }
    }
  ]
}

Known Limitations

Complex Deeply Nested AllOf Structures

Limitation: The current implementation has a known edge case with deeply nested allOf conditional schemas within array structures.

Example of unsupported pattern:

// ❌ COMPLEX EDGE CASE: Multi-level nested allOf in arrays
{
  "type": "object", 
  "properties": {
    "sections": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sectionType": { "type": "string" }
        },
        "allOf": [                    // ✅ Level 1 allOf - WORKS
          {
            "if": { "properties": { "sectionType": { "const": "content" } } },
            "then": {
              "properties": {
                "contentGroups": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "groupType": { "type": "string" }
                    },
                    "allOf": [        // ❌ Level 2 allOf - EDGE CASE
                      {
                        "if": { "properties": { "groupType": { "const": "links" } } },
                        "then": {
                          "properties": {
                            "groupLinks": {
                              "type": "array",
                              "items": { "type": "SquizLink" }
                            }
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

Impact:

• This pattern represents a rare edge case in real-world schemas
• Known practical production use cases work perfectly

Workaround:

• Flatten deeply nested conditional structures where possible
• Use separate schema definitions for complex nested conditions
• Consider restructuring schemas to avoid multiple levels of array-embedded allOf patterns

Future Enhancement: This limitation could be addressed in a future version by implementing:

• Recursive allOf detection across multiple nesting levels
• Enhanced pointer-based data preservation for deeply nested structures
• Advanced JSON Schema library processing overrides for complex recursive scenarios