KtSON

JSON Schema validator for Kotlin with comprehensive support for JSON Schema Draft 2019-09 and 2020-12.

NOTE

This project is a playground for testing AI agents as a day-to-day tools in programming.
You can see the summaries and results from discussions with AI in the ./docs directory.
Most of the code refactoring were performed by AI agent with supervision and code review done by human.

Table of Contents

• Features
• Tech Stack
• Getting Started
  • Prerequisites
  • Installation
  • Basic Usage
• Available Scripts
• Project Scope
  • Supported JSON Schema Versions
  • Feature Completeness
  • Known Limitations
• Project Status
• Documentation
• Performance
• Code Quality
• License

Features

✅ Comprehensive Validation

• Full type validation (string, number, integer, boolean, object, array, null)
• String constraints (minLength, maxLength, pattern, format)
• Numeric constraints (minimum, maximum, multipleOf, exclusive bounds)
• Object constraints (properties, required, additionalProperties, patternProperties, dependencies)
• Array constraints (items, prefixItems, contains, uniqueItems, minItems, maxItems)

✅ Advanced Schema Features

• Schema references ($ref) with local, fragment, and external schema support
• Pluggable remote schema loading (schemaLoader callback)
• Schema combiners (allOf, anyOf, oneOf, not)
• Conditional validation (if/then/else)
• Unevaluated properties and items (Draft 2020-12)
• Property name validation
• Dependent schemas and required properties

Tech Stack

Core

• Language: Kotlin 2.2.20
• JVM: Java 21
• Build Tool: Gradle 9.1.0

Dependencies

• kotlinx-serialization-json - JSON parsing and manipulation
• kotest - Testing framework
• ktlint - Code style and quality

Package: org.ktson

Getting Started

Prerequisites

• JDK 21 or higher
• Gradle 9.1.0 or higher (or use the included wrapper)

Installation

Gradle (Kotlin DSL)

dependencies {
    implementation("org.ktson:ktson:0.0.1-SNAPSHOT")
}

Gradle (Groovy)

dependencies {
    implementation 'org.ktson:ktson:0.0.1-SNAPSHOT'
}

Maven

<dependency>
    <groupId>org.ktson</groupId>
    <artifactId>ktson</artifactId>
    <version>0.0.2-SNAPSHOT</version>
</dependency>

Basic Usage

Validating JSON Against a Schema

import org.ktson.*
import kotlinx.serialization.json.*

fun main() {
    // Create a JSON schema
    val schemaJson = """
    {
        "type": "object",
        "properties": {
            "name": { "type": "string" },
            "age": { "type": "integer", "minimum": 0 }
        },
        "required": ["name", "age"]
    }
    """
    
    // Create instance data
    val instanceJson = """
    {
        "name": "John Doe",
        "age": 30
    }
    """
    
    // Validate
    val validator = JsonValidator()
    val result = validator.validate(instanceJson, schemaJson, SchemaVersion.DRAFT_2020_12)
    
    when (result) {
        is ValidationResult.Valid -> println("✓ Validation successful!")
        is ValidationResult.Invalid -> {
            println("✗ Validation failed:")
            result.errors.forEach { error ->
                println("  - ${error.path}: ${error.message}")
            }
        }
    }
}

Using JsonElement

import org.ktson.*
import kotlinx.serialization.json.*

val schema = buildJsonObject {
    put("type", "string")
    put("minLength", 3)
    put("maxLength", 10)
}

val instance = JsonPrimitive("hello")

val validator = JsonValidator()
val jsonSchema = JsonSchema.fromElement(schema, SchemaVersion.DRAFT_2020_12)
val result = validator.validate(instance, jsonSchema)

Validating Schema Structure

val validator = JsonValidator(enableMetaSchemaValidation = true)
val schema = JsonSchema.fromString(schemaJson, SchemaVersion.DRAFT_2020_12)

val result = validator.validateSchema(schema)
if (result is ValidationResult.Invalid) {
    println("Invalid schema:")
    result.errors.forEach { println("  - ${it.message}") }
}

Working with $ref

val schema = """
{
    "${'$'}defs": {
        "address": {
            "type": "object",
            "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" }
            }
        }
    },
    "type": "object",
    "properties": {
        "billing": { "${'$'}ref": "#/${'$'}defs/address" },
        "shipping": { "${'$'}ref": "#/${'$'}defs/address" }
    }
}
"""

For more examples, see docs/REF_USAGE_EXAMPLES.md and src/main/kotlin/org/ktson/Example.kt.

Available Scripts

Build

# Build the project
./gradlew build

# Compile only
./gradlew compileKotlin

# Create JAR
./gradlew jar

Testing

# Run all tests (excludes performance tests for speed)
./gradlew test

# Run specific test suite
./gradlew test --tests "Draft201909ValidationTest"
./gradlew test --tests "OfficialTestSuiteRunner"

# Run performance tests (on demand)
./gradlew performanceTest

# Run all tests including performance
./gradlew test performanceTest

Code Quality

# Check code style with ktlint
./gradlew ktlintCheck

# Auto-format code with ktlint
./gradlew ktlintFormat

Project Scope

Supported JSON Schema Versions

• ✅ JSON Schema Draft 2020-12 (primary support)
• ✅ JSON Schema Draft 2019-09 (full support)

Feature Completeness

Feature Category	Status	Coverage
Type Validation	✅ Complete	100%
String Validation	✅ Complete	100% (including Unicode codepoints)
Numeric Validation	✅ Complete	100%
Object Validation	✅ Complete	100%
Array Validation	✅ Complete	100%
Schema Combiners	✅ Complete	100%
Conditional Validation	✅ Complete	100%
References ($ref)	✅ Complete	Local and external (via schemaLoader)
Unevaluated Keywords	✅ Complete	100%
Remote Schema Loading	✅ Complete	Pluggable schemaLoader callback
Format Validation	⚠️ Partial	email, URI, date, time, IPv4, IPv6, UUID, hostname, idn-email, IRI, regex
Official Test Suite	✅ 100%	2,653/2,653 passing

See docs/IMPLEMENTATION_STATUS.md for detailed feature breakdown.

Known Limitations

1. Stack Overflow Risk ✅ RESOLVED

   • ✅ Global recursion depth limiting implemented (default: 1000 levels)
   • ✅ Configurable via maxValidationDepth constructor parameter
   • See docs/STACK_OVERFLOW_RISK_ANALYSIS.md for historical analysis

2. Format Validation

   • Assertion mode only (no annotation-only mode yet)
   • Some formats still unvalidated: idn-hostname, json-pointer, relative-json-pointer, uri-reference

Project Status

Version: 0.0.1-SNAPSHOT
Status: ⚠️ Pre-release (Beta)

Test Coverage

• Custom Tests: 179 tests (100% passing)

  • Draft 2019-09: 47 tests
  • Draft 2020-12: 54 tests
  • Edge cases & thread safety: 39 tests
  • Depth limit protection: 14 tests
  • URI resolver: 25 tests

• Official JSON Schema Test Suite: 2,653 tests

  • ✅ Passing: 2,653 (100%)
  • ❌ Failing: 0

• Performance Tests: 6 tests (100% passing)

  • Tested with schemas up to 50MB
  • Tested with data up to 20MB
  • Concurrent validation verified

Recent Changes

• ✅ Remote schema loading implemented (pluggable schemaLoader callback)
• ✅ 100% official test suite pass rate (2,653/2,653 tests)
• ✅ unevaluatedProperties and unevaluatedItems implemented
• ✅ $dynamicRef / $dynamicAnchor full dynamic scope resolution
• ✅ $recursiveRef / $recursiveAnchor dynamic recursion
• ✅ Stack overflow protection (configurable depth limiting)
• ✅ Converted from async to synchronous API
• ✅ Package migrated from com.ktson to org.ktson

Roadmap

Before 1.0 Release:

• Implement recursion depth limiting ✅ COMPLETED
• Implement unevaluatedProperties and unevaluatedItems ✅ COMPLETED
• Remote schema reference support ✅ COMPLETED
• Add more format validators (hostname, idn-email, iri, regex)
• Improve error messages

Future Enhancements:

• Schema caching improvements
• Streaming validation for large datasets
• GraalVM native image support

Documentation

Comprehensive documentation is available in the docs directory:

Getting Started

• FEATURES.md - Complete feature list
• REF_USAGE_EXAMPLES.md - Reference usage examples
• Example.kt - Code examples

Testing

• TESTING.md - Testing approach and methodology
• OFFICIAL_TEST_SUITE_RESULTS.md - Detailed test results
• PERFORMANCE_TEST_RESULTS.md - Performance benchmarks
• PERFORMANCE_TESTING_SUMMARY.md - Performance test implementation

Technical

• STACK_OVERFLOW_RISK_ANALYSIS.md - Recursion depth analysis (⚠️ Important)
• GRAPHEME_CLUSTER_ISSUE.md - Unicode handling details
• IMPLEMENTATION_STATUS.md - Feature implementation tracking

Migration & History

• MIGRATION_COMPLETE.md - Async to sync migration summary
• ASYNC_TO_SYNC_MIGRATION.md - Detailed migration guide
• PACKAGE_MIGRATION.md - Package refactoring documentation
• VERSION_UPGRADE.md - Version upgrade summary

See docs/README.md for a complete documentation index.

Performance

KtSON demonstrates excellent performance with large and complex schemas:

Test Case	Schema Size	Data Size	Execution Time	Memory Used
Nested Objects	25.2 MB	10.2 MB	84ms	73 MB
Large Arrays	905 KB	80 KB	7ms	1 MB
Complex Properties	534 KB	205 KB	6ms	4 MB
Combiners	221 KB	38 KB	4ms	1 MB
Pattern Properties	63 KB	148 KB	48ms	175 MB
Concurrent (10 threads)	50 MB	20 MB	19ms avg	392 MB

Key Characteristics:

• Fast: Most validations complete in single-digit milliseconds
• Scalable: Handles schemas up to 50MB efficiently
• Thread-safe: Zero synchronization overhead
• Memory efficient: Proportional to schema complexity

See docs/PERFORMANCE_TEST_RESULTS.md for detailed benchmarks.

Code Quality

KtSON follows strict code quality standards:

• Code Style: Enforced with Ktlint 1.7.1
• Style Guide: IntelliJ IDEA default Kotlin conventions
• Test Coverage: 2,500+ tests across multiple suites
• Thread Safety: Verified with concurrent validation tests
• Documentation: Comprehensive inline documentation and separate docs

Check code style:

./gradlew ktlintCheck

Auto-format code:

./gradlew ktlintFormat

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024 KtSON Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Note: This is a pre-release version. The validator passes 100% of the official JSON Schema Test Suite. Recursion depth protection is implemented (default limit: 1000). See STACK_OVERFLOW_RISK_ANALYSIS.md for details on depth limiting.