Add ref support

Author: Oleg

src/commonMain/kotlin/smirnov/oleg/json/pointer/extenstions.kt

@@ -27,6 +27,36 @@ operator fun JsonPointer.div(property: String): JsonPointer = JsonPointer(
   }
 )
 
+operator fun JsonPointer.plus(otherPointer: JsonPointer): JsonPointer {
+  if (this is EmptyPointer) {
+    return otherPointer
+  }
+  if (otherPointer is EmptyPointer) {
+    return this
+  }
+  return JsonPointer(
+    buildString {
+      val pointer = this@plus.toString()
+      append(pointer)
+      if (pointer.endsWith(JsonPointer.SEPARATOR)) {
+        setLength(length - 1)
+      }
+      val other = otherPointer.toString()
+      append(other)
+    }
+  )
+}
+
+fun JsonPointer.relative(other: JsonPointer): JsonPointer {
+  if (this is EmptyPointer) {
+    return other
+  }
+  require(other !is EmptyPointer) { "empty pointer is not relative to any" }
+  val currentValue = this.toString()
+  val otherValue = other.toString()
+  return JsonPointer(otherValue.substringAfter(currentValue))
+}
+
 fun JsonElement.at(pointer: JsonPointer): JsonElement? {
   return when (pointer) {
     is EmptyPointer -> this

src/commonMain/kotlin/smirnov/oleg/json/schema/JsonSchema.kt

@@ -6,16 +6,18 @@ import kotlinx.serialization.json.JsonObject
 import smirnov.oleg.json.pointer.JsonPointer
 import smirnov.oleg.json.schema.internal.DefaultAssertionContext
 import smirnov.oleg.json.schema.internal.JsonSchemaAssertion
+import smirnov.oleg.json.schema.internal.RefId
 import smirnov.oleg.json.schema.internal.SchemaLoader
 import kotlin.jvm.JvmStatic
 
 class JsonSchema internal constructor(
   private val baseId: String,
   private val assertion: JsonSchemaAssertion,
-  private val references: Map<String, JsonSchemaAssertion>,
+  private val references: Map<RefId, JsonSchemaAssertion>,
 ) {
   fun validate(value: JsonElement, errorCollector: ErrorCollector): Boolean {
-    return assertion.validate(value, DefaultAssertionContext(JsonPointer.ROOT), errorCollector)
+    val context = DefaultAssertionContext(JsonPointer.ROOT, references)
+    return assertion.validate(value, context, errorCollector)
   }
 
   companion object {

src/commonMain/kotlin/smirnov/oleg/json/schema/ValidationError.kt

@@ -22,4 +22,9 @@ data class ValidationError(
    * Additional details about error
    */
   val details: Map<String, String> = emptyMap(),
+
+  /**
+   * The absolute path to triggered assertion if the $ref was used
+   */
+  val absoluteLocation: JsonPointer? = null,
 )

src/commonMain/kotlin/smirnov/oleg/json/schema/internal/AssertionContext.kt

@@ -9,14 +9,20 @@ internal interface AssertionContext {
 
   fun at(index: Int): AssertionContext
   fun at(property: String): AssertionContext
+  fun resolveRef(refId: RefId): JsonSchemaAssertion
 }
 
 internal data class DefaultAssertionContext(
   override val objectPath: JsonPointer,
+  private val references: Map<RefId, JsonSchemaAssertion>,
 ) : AssertionContext {
   override fun at(index: Int): AssertionContext = copy(objectPath = objectPath[index])
 
   override fun at(property: String): AssertionContext {
     return copy(objectPath = objectPath / property)
   }
+
+  override fun resolveRef(refId: RefId): JsonSchemaAssertion {
+    return requireNotNull(references[refId]) { "$refId is not found" }
+  }
 }

src/commonMain/kotlin/smirnov/oleg/json/schema/internal/RefId.kt

@@ -0,0 +1,9 @@
+package smirnov.oleg.json.schema.internal
+
+import kotlin.jvm.JvmInline
+
+@JvmInline
+internal value class RefId(private val id: String) {
+  val fragment: String
+    get() = id.substringAfter(rootReference)
+}

src/commonMain/kotlin/smirnov/oleg/json/schema/internal/RefSchemaAssertion.kt

@@ -0,0 +1,29 @@
+package smirnov.oleg.json.schema.internal
+
+import kotlinx.serialization.json.JsonElement
+import smirnov.oleg.json.pointer.JsonPointer
+import smirnov.oleg.json.pointer.plus
+import smirnov.oleg.json.pointer.relative
+import smirnov.oleg.json.schema.ErrorCollector
+
+internal class RefSchemaAssertion(
+  private val basePath: JsonPointer,
+  private val refId: RefId,
+) : JsonSchemaAssertion {
+  private val refIdPath: JsonPointer = JsonPointer(refId.fragment)
+  private lateinit var refAssertion: JsonSchemaAssertion
+
+  override fun validate(element: JsonElement, context: AssertionContext, errorCollector: ErrorCollector): Boolean {
+    if (!::refAssertion.isInitialized) {
+      refAssertion = context.resolveRef(refId)
+    }
+    return refAssertion.validate(element, context) {
+      errorCollector.onError(
+        it.copy(
+          schemaPath = basePath + refIdPath.relative(it.schemaPath),
+          absoluteLocation = it.absoluteLocation ?: it.schemaPath,
+        )
+      )
+    }
+  }
+}

src/commonMain/kotlin/smirnov/oleg/json/schema/internal/ReferenceValidator.kt

@@ -0,0 +1,88 @@
+package smirnov.oleg.json.schema.internal
+
+import smirnov.oleg.json.pointer.JsonPointer
+
+internal object ReferenceValidator {
+  data class ReferenceLocation(
+    val schemaPath: JsonPointer,
+    val refId: RefId,
+  )
+  fun validateReferences(references: Set<RefId>, usedRef: Set<ReferenceLocation>) {
+    val missingRefs: Map<RefId, List<ReferenceLocation>> = usedRef.asSequence()
+      .filter { it.refId !in references }
+      .groupBy { it.refId }
+    require(missingRefs.isEmpty()) {
+      "cannot resolve references: ${
+        missingRefs.entries.joinToString(prefix = "{", postfix = "}") { (ref, locations) ->
+          "\"${ref.fragment}\": ${locations.map { "\"${it.schemaPath}\"" }}"
+        }
+      }"
+    }
+    checkCircledReferences(usedRef)
+  }
+
+  private val alwaysRunAssertions = hashSetOf("/allOf/", "/anyOf/", "/oneOf/")
+
+  private fun checkCircledReferences(usedRefs: Set<ReferenceLocation>) {
+    val locationToRef: Map<String, String> = usedRefs.associate { (schemaPath, refId) ->
+      schemaPath.toString() to refId.fragment
+    }
+
+    val circledReferences = hashSetOf<CircledReference>()
+    fun checkRunAlways(path: String): Boolean {
+      return alwaysRunAssertions.any { path.contains(it) }
+    }
+    for ((location, refFragment) in locationToRef) {
+      val (otherLocation, otherRefFragment) = locationToRef.entries.find { it.key.startsWith(refFragment) }
+        ?: continue
+      if (!location.startsWith(otherRefFragment)) {
+        continue
+      }
+      if (checkRunAlways(location) && checkRunAlways(otherLocation)) {
+        circledReferences += CircledReference(
+          firstLocation = location,
+          firstRef = refFragment,
+          secondLocation = otherLocation,
+          secondRef = otherRefFragment,
+        )
+      }
+    }
+    require(circledReferences.isEmpty()) {
+      "circled references: ${
+        circledReferences.joinToString {
+          "${it.firstLocation} ref to ${it.firstRef} and ${it.secondLocation} ref to ${it.secondRef}"
+        }
+      }"
+    }
+  }
+
+  private class CircledReference(
+    val firstLocation: String,
+    val firstRef: String,
+    val secondLocation: String,
+    val secondRef: String,
+  ) {
+    override fun equals(other: Any?): Boolean {
+      if (this === other) return true
+      if (other == null || this::class != other::class) return false
+
+      other as CircledReference
+
+      return (firstLocation == other.firstLocation
+          && firstRef == other.firstRef
+          && secondLocation == other.secondLocation
+          && secondRef == other.secondRef)
+          || (firstLocation == other.secondLocation
+          && firstRef == other.secondRef
+          && secondLocation == other.firstLocation
+          && secondRef == other.firstRef)
+    }
+
+    override fun hashCode(): Int {
+      return firstLocation.hashCode() +
+          firstRef.hashCode() +
+          secondLocation.hashCode() +
+          secondRef.hashCode()
+    }
+  }
+}

src/commonMain/kotlin/smirnov/oleg/json/schema/internal/SchemaLoader.kt

@@ -9,6 +9,7 @@ import smirnov.oleg.json.pointer.JsonPointer
 import smirnov.oleg.json.pointer.div
 import smirnov.oleg.json.pointer.get
 import smirnov.oleg.json.schema.JsonSchema
+import smirnov.oleg.json.schema.internal.ReferenceValidator.ReferenceLocation
 import smirnov.oleg.json.schema.internal.factories.array.ContainsAssertionFactory
 import smirnov.oleg.json.schema.internal.factories.array.ItemsAssertionFactory
 import smirnov.oleg.json.schema.internal.factories.array.MaxItemsAssertionFactory
@@ -67,15 +68,17 @@ private val factories: List<AssertionFactory> = listOf(
 
 private const val DEFINITIONS_PROPERTY: String = "definitions"
 private const val ID_PROPERTY: String = "\$id"
+private const val REF_PROPERTY: String = "\$ref"
 
-private const val rootReference = '#'
+internal const val rootReference = '#'
 
 class SchemaLoader {
   fun load(schemaDefinition: JsonElement): JsonSchema {
     val baseId = extractBaseID(schemaDefinition)
     val context = defaultLoadingContext(baseId)
     loadDefinitions(schemaDefinition, context)
     val schemaAssertion = loadSchema(schemaDefinition, context)
+    ReferenceValidator.validateReferences(context.references.keys, context.usedRef)
     return JsonSchema(baseId, schemaAssertion, context.references)
   }
 
@@ -118,17 +121,34 @@ private fun loadSchema(
       FalseSchemaAssertion(path = context.schemaPath)
     }
 
-    else -> factories.filter { it.isApplicable(schemaDefinition) }
-      .map {
-        it.create(schemaDefinition, context)
-      }.let(::AssertionsCollection)
+    is JsonObject -> {
+      if (schemaDefinition.containsKey(REF_PROPERTY)) {
+        loadRefAssertion(schemaDefinition, context)
+      } else {
+        factories.filter { it.isApplicable(schemaDefinition) }
+          .map {
+            it.create(schemaDefinition, context)
+          }.let(::AssertionsCollection)
+      }
+    }
+    // should never happen
+    else -> throw IllegalArgumentException("schema must be either a valid JSON object or boolean")
   }.apply(context::register)
 }
 
+private fun loadRefAssertion(definition: JsonObject, context: DefaultLoadingContext): JsonSchemaAssertion {
+  val refElement = requireNotNull(definition[REF_PROPERTY]) { "$REF_PROPERTY is not set" }
+  require(refElement is JsonPrimitive && refElement.isString) { "$REF_PROPERTY must be a string" }
+  val refValue = refElement.content
+  val refId: RefId = context.ref(refValue)
+  return RefSchemaAssertion(context.schemaPath / REF_PROPERTY, refId)
+}
+
 private data class DefaultLoadingContext(
   private val baseId: String,
   override val schemaPath: JsonPointer = JsonPointer.ROOT,
-  val references: MutableMap<String, JsonSchemaAssertion> = hashMapOf(),
+  val references: MutableMap<RefId, JsonSchemaAssertion> = hashMapOf(),
+  val usedRef: MutableSet<ReferenceLocation> = hashSetOf(),
 ) : LoadingContext {
   override fun at(property: String): DefaultLoadingContext {
     return copy(schemaPath = schemaPath / property)
@@ -143,11 +163,17 @@ private data class DefaultLoadingContext(
       || (element is JsonPrimitive && element.booleanOrNull != null))
 
   fun register(assertion: JsonSchemaAssertion) {
-    val referenceId = "$baseId$rootReference$schemaPath"
+    val referenceId = buildRefId("$rootReference$schemaPath")
     references.put(referenceId, assertion)?.apply {
       throw IllegalStateException("duplicated definition $referenceId")
     }
   }
+
+  fun ref(refId: String): RefId {
+    return buildRefId(refId).also { usedRef += ReferenceLocation(schemaPath, it) }
+  }
+
+  private fun buildRefId(path: String): RefId = RefId("$baseId$path")
 }
 
 private fun defaultLoadingContext(baseId: String): DefaultLoadingContext = DefaultLoadingContext(baseId)

src/commonTest/kotlin/smirnov/oleg/json/schema/JsonSchemaTest.kt

@@ -12,7 +12,7 @@ import kotlinx.serialization.json.buildJsonArray
 import kotlinx.serialization.json.buildJsonObject
 import smirnov.oleg.json.pointer.JsonPointer
 import smirnov.oleg.json.schema.JsonSchema
-import smirnov.oleg.json.schema.KEY
+import smirnov.oleg.json.schema.base.KEY
 import smirnov.oleg.json.schema.ValidationError
 
 @Suppress("unused")