Skip to content

FEATURES.md

Latest commit

 

History

History
264 lines (211 loc) · 8.06 KB

FEATURES.md

File metadata and controls

264 lines (211 loc) · 8.06 KB
Raw

KtSON Features and Test Coverage

Supported JSON Schema Specifications

Draft 2019-09 ✅

  • Full compliance with JSON Schema Draft 2019-09
  • All core validation keywords
  • $recursiveRef / $recursiveAnchor dynamic recursion

Draft 2020-12 ✅

  • Full compliance with JSON Schema Draft 2020-12
  • All core validation keywords
  • prefixItems support for tuple validation
  • $dynamicRef / $dynamicAnchor dynamic scope resolution

Validation Keywords Coverage

Type Validation ✅

  • type - All types: string, number, integer, boolean, object, array, null
  • Multiple types support

String Validation ✅

  • minLength - Minimum string length
  • maxLength - Maximum string length
  • pattern - Regular expression validation
  • format - Format validation:
    • email
    • uri
    • date
    • time
    • date-time
    • ipv4
    • ipv6
    • uuid
    • hostname
    • idn-email
    • iri
    • iri-reference
    • regex

Numeric Validation ✅

  • minimum - Minimum value (inclusive)
  • maximum - Maximum value (inclusive)
  • exclusiveMinimum - Minimum value (exclusive)
  • exclusiveMaximum - Maximum value (exclusive)
  • multipleOf - Value must be multiple of

Object Validation ✅

  • properties - Property schemas
  • required - Required properties
  • additionalProperties - Additional properties validation
  • patternProperties - Pattern-based property schemas
  • minProperties - Minimum number of properties
  • maxProperties - Maximum number of properties
  • propertyNames - Property name validation
  • dependentRequired - Dependent required properties
  • dependentSchemas - Dependent schemas
  • unevaluatedProperties - Annotation-based, with full propagation through all applicators

Array Validation ✅

  • items - Item schema validation
  • prefixItems - Tuple validation (2020-12)
  • additionalItems - Additional items in tuples (2019-09)
  • minItems - Minimum array length
  • maxItems - Maximum array length
  • uniqueItems - Unique items constraint
  • contains - Contains validation
  • minContains - Minimum matching items
  • maxContains - Maximum matching items
  • unevaluatedItems - Annotation-based, with contains annotation (matching indices only)

Combining Schemas ✅

  • allOf - Must match all schemas
  • anyOf - Must match at least one schema
  • oneOf - Must match exactly one schema
  • not - Must not match schema

Conditional Validation ✅

  • if - Conditional schema
  • then - Schema to apply if condition matches
  • else - Schema to apply if condition doesn't match

Generic Keywords ✅

  • const - Constant value validation
  • enum - Enumeration validation

Boolean Schemas ✅

  • true - Accepts any instance
  • false - Rejects any instance

References and Anchors ✅

  • $ref — JSON Pointer and named anchor resolution, respects $id resource boundaries
  • $ref — External schema loading via pluggable schemaLoader callback
  • $anchor — Named anchors within a schema resource
  • $dynamicAnchor / $dynamicRef — Draft 2020-12 dynamic scope resolution
  • $recursiveAnchor / $recursiveRef — Draft 2019-09 dynamic recursion
  • $id — Schema resource boundaries with RFC 3986 relative URI resolution
  • $defs / definitions — Schema definition storage
  • Sibling keywords evaluated alongside $ref (Draft 2019-09+ behaviour)
  • Percent-decoding of URI fragments (RFC 6901 §6)

Official Test Suite

Test Suite: json-schema-org/JSON-Schema-Test-Suite

Metric Value
Total tests 2,653
Passing 2,653 ✅
Failing 0
Pass rate 100%

Test Coverage

Draft 2019-09 Test Suite ✅

Total test cases: 35+

  1. Type Validation (8 tests)

    • String, integer, number, boolean, null, object, array types
    • Multiple types

  2. String Validation (6 tests)

    • minLength, maxLength, pattern
    • email, date-time, uuid formats

  3. Number Validation (5 tests)

    • minimum, maximum
    • exclusiveMinimum, exclusiveMaximum
    • multipleOf

  4. Object Validation (10 tests)

    • properties, required
    • additionalProperties (boolean and schema)
    • patternProperties
    • minProperties, maxProperties
    • propertyNames
    • dependentRequired, dependentSchemas

  5. Array Validation (7 tests)

    • items (single and tuple)
    • minItems, maxItems
    • uniqueItems
    • contains, minContains, maxContains

  6. Const and Enum (2 tests)

  7. Combining Schemas (4 tests)

    • allOf, anyOf, oneOf, not

  8. Conditional Schemas (1 test)

    • if-then-else

  9. Boolean Schemas (2 tests)

  10. Schema Validation (2 tests)

Draft 2020-12 Test Suite ✅

Total test cases: 40+

All Draft 2019-09 tests plus:

  • prefixItems validation
  • Enhanced format validation
  • Real-world schemas (user profiles, API responses)
  • Complex combinations

Edge Cases and Thread-Safety Tests ✅

Total test cases: 50+

  1. Empty and Null Values (6 tests)

    • Empty strings, arrays, objects
    • Null values and combinations

  2. Boundary Values (5 tests)

    • Zero-length strings
    • Very large numbers
    • Exact boundary validation
    • Exclusive boundaries

  3. Deeply Nested Structures (3 tests)

    • Nested objects
    • Nested arrays
    • Nested allOf

  4. Pattern and Regex (4 tests)

    • Empty patterns
    • Complex regex
    • Special characters
    • Overlapping patterns

  5. Numeric Precision (3 tests)

    • Floating point multipleOf
    • Very small values
    • Integer vs number distinction

  6. Circular References (1 test)

    • Recursive schema definitions

  7. Special String Formats (4 tests)

    • Various email formats
    • IPv4 addresses
    • UUID formats
    • Date and time formats

  8. Error Messages (2 tests)

    • Meaningful error messages
    • Path inclusion in errors

  9. Thread Safety (6 tests)

    • Concurrent validations (100 concurrent)
    • Different schemas concurrently
    • Validation failures under concurrency
    • Concurrent schema validation (50 schemas)
    • High concurrency (1000 concurrent)
    • State isolation

  10. Schema Version Detection (3 tests)

    • Draft 2019-09 detection
    • Draft 2020-12 detection
    • Default version handling

  11. Large Data Sets (2 tests)

    • Large arrays (10,000 items)
    • Large objects (1,000 properties)

Thread Safety Features ✅

  1. Stateless design - No mutable shared state between validations
  2. Immutable validator - JsonValidator instance can be shared freely across threads
  3. Concurrent validation - Tested with up to 1,000 concurrent operations
  4. Configurable depth limit - Protects against stack overflow in untrusted schemas

Performance Characteristics ✅

  1. Efficient validation - Single-pass validation where possible
  2. Large data support - Tested with 10,000+ element arrays
  3. Memory efficient - No unnecessary copying of data
  4. Concurrent performance - Linear scaling with multiple cores

Error Reporting ✅

  1. Detailed error messages - Clear description of validation failures
  2. Path tracking - Full JSON path to error location
  3. Keyword identification - Which keyword failed
  4. Multiple errors - Reports all validation errors, not just first one

API Design ✅

  1. Type-safe - Leverages Kotlin's type system
  2. Synchronous - Simple blocking API, no coroutines required
  3. Idiomatic Kotlin - Follows Kotlin conventions
  4. Easy to use - Simple, intuitive API
  5. Thread-safe - Single JsonValidator instance safe for concurrent use

Production Ready ✅

  • 100% official JSON Schema test suite pass rate (2,653 / 2,653)
  • Comprehensive unit tests (179+ additional test cases)
  • Thread-safe implementation
  • Configurable recursion depth protection
  • Performance tested with large datasets
  • Detailed documentation
  • Standard Gradle build
  • Maven publishable
  • Zero linter errors