# @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

## User API manifests (DXP `manifest.json`)

Validation and the canonical `$schema` URL are exposed on a **separate entry point** so importing the root barrel does not create load-time circular dependencies:

```typescript
import {
  USER_API_MANIFEST_SCHEMA_URL,
  validateUserApiFullManifest,
} from '@squiz/dx-json-schema-lib';
```

## Usage

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

```javascript
// ✅ 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**:

```javascript
// ❌ 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