Introduce abstraction for validated elements (#191)

Make validation abstracted from the `JsonElement`

Related to #190
Resolves #193

Author: OptimumCode

gradle.properties

@@ -4,5 +4,5 @@ org.gradle.jvmargs=-Xmx1G
 org.gradle.java.installations.auto-download=false
 org.gradle.daemon=false
 
-version=0.2.4-SNAPSHOT
+version=0.3.0-SNAPSHOT
 group=io.github.optimumcode

json-schema-validator/api/json-schema-validator.api

@@ -94,7 +94,7 @@ public abstract interface class io/github/optimumcode/json/schema/FormatValidato
 	public static final field Companion Lio/github/optimumcode/json/schema/FormatValidator$Companion;
 	public static fun Invalid ()Lio/github/optimumcode/json/schema/FormatValidationResult;
 	public static fun Valid ()Lio/github/optimumcode/json/schema/FormatValidationResult;
-	public abstract fun validate (Lkotlinx/serialization/json/JsonElement;)Lio/github/optimumcode/json/schema/FormatValidationResult;
+	public abstract fun validate (Lio/github/optimumcode/json/schema/model/AbstractElement;)Lio/github/optimumcode/json/schema/FormatValidationResult;
 }
 
 public final class io/github/optimumcode/json/schema/FormatValidator$Companion {
@@ -108,6 +108,8 @@ public final class io/github/optimumcode/json/schema/JsonSchema {
 	public static final fun fromDefinition (Ljava/lang/String;Lio/github/optimumcode/json/schema/SchemaType;)Lio/github/optimumcode/json/schema/JsonSchema;
 	public static final fun fromJsonElement (Lkotlinx/serialization/json/JsonElement;)Lio/github/optimumcode/json/schema/JsonSchema;
 	public static final fun fromJsonElement (Lkotlinx/serialization/json/JsonElement;Lio/github/optimumcode/json/schema/SchemaType;)Lio/github/optimumcode/json/schema/JsonSchema;
+	public final fun validate (Lio/github/optimumcode/json/schema/model/AbstractElement;Lio/github/optimumcode/json/schema/ErrorCollector;)Z
+	public final fun validate (Lio/github/optimumcode/json/schema/model/AbstractElement;Lio/github/optimumcode/json/schema/OutputCollector$Provider;)Ljava/lang/Object;
 	public final fun validate (Lkotlinx/serialization/json/JsonElement;Lio/github/optimumcode/json/schema/ErrorCollector;)Z
 	public final fun validate (Lkotlinx/serialization/json/JsonElement;Lio/github/optimumcode/json/schema/OutputCollector$Provider;)Ljava/lang/Object;
 }
@@ -337,9 +339,15 @@ public abstract interface class io/github/optimumcode/json/schema/extension/Exte
 }
 
 public abstract interface class io/github/optimumcode/json/schema/extension/ExternalAssertion {
+	public abstract fun validate (Lio/github/optimumcode/json/schema/model/AbstractElement;Lio/github/optimumcode/json/schema/extension/ExternalAssertionContext;Lio/github/optimumcode/json/schema/ErrorCollector;)Z
 	public abstract fun validate (Lkotlinx/serialization/json/JsonElement;Lio/github/optimumcode/json/schema/extension/ExternalAssertionContext;Lio/github/optimumcode/json/schema/ErrorCollector;)Z
 }
 
+public final class io/github/optimumcode/json/schema/extension/ExternalAssertion$DefaultImpls {
+	public static fun validate (Lio/github/optimumcode/json/schema/extension/ExternalAssertion;Lio/github/optimumcode/json/schema/model/AbstractElement;Lio/github/optimumcode/json/schema/extension/ExternalAssertionContext;Lio/github/optimumcode/json/schema/ErrorCollector;)Z
+	public static fun validate (Lio/github/optimumcode/json/schema/extension/ExternalAssertion;Lkotlinx/serialization/json/JsonElement;Lio/github/optimumcode/json/schema/extension/ExternalAssertionContext;Lio/github/optimumcode/json/schema/ErrorCollector;)Z
+}
+
 public abstract interface class io/github/optimumcode/json/schema/extension/ExternalAssertionContext {
 	public abstract fun getAnnotationCollector ()Lio/github/optimumcode/json/schema/extension/ExternalAnnotationCollector;
 	public abstract fun getObjectPath ()Lio/github/optimumcode/json/pointer/JsonPointer;
@@ -354,3 +362,28 @@ public abstract interface class io/github/optimumcode/json/schema/extension/Exte
 	public abstract fun getSchemaPath ()Lio/github/optimumcode/json/pointer/JsonPointer;
 }
 
+public abstract interface class io/github/optimumcode/json/schema/model/AbstractElement {
+	public abstract fun toString ()Ljava/lang/String;
+}
+
+public abstract interface class io/github/optimumcode/json/schema/model/ArrayElement : io/github/optimumcode/json/schema/model/AbstractElement, kotlin/sequences/Sequence {
+	public abstract fun get (I)Lio/github/optimumcode/json/schema/model/AbstractElement;
+	public abstract fun getSize ()I
+}
+
+public abstract interface class io/github/optimumcode/json/schema/model/ObjectElement : io/github/optimumcode/json/schema/model/AbstractElement, kotlin/sequences/Sequence {
+	public abstract fun contains (Ljava/lang/String;)Z
+	public abstract fun get (Ljava/lang/String;)Lio/github/optimumcode/json/schema/model/AbstractElement;
+	public abstract fun getKeys ()Ljava/util/Set;
+	public abstract fun getSize ()I
+}
+
+public abstract interface class io/github/optimumcode/json/schema/model/PrimitiveElement : io/github/optimumcode/json/schema/model/AbstractElement {
+	public abstract fun getContent ()Ljava/lang/String;
+	public abstract fun getNumber ()Ljava/lang/Number;
+	public abstract fun isBoolean ()Z
+	public abstract fun isNull ()Z
+	public abstract fun isNumber ()Z
+	public abstract fun isString ()Z
+}
+

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/FormatValidator.kt

@@ -1,11 +1,12 @@
 package io.github.optimumcode.json.schema
 
-import kotlinx.serialization.json.JsonElement
+import io.github.optimumcode.json.schema.model.AbstractElement
 import kotlin.jvm.JvmStatic
 
 /**
- * The [FormatValidator] is used to check whether the [JsonElement] matches the expected format.
- * If the [JsonElement] is not of the required type (e.g. validator expects string but the [JsonElement] is an object)
+ * The [FormatValidator] is used to check whether the [AbstractElement] matches the expected format.
+ * If the [AbstractElement] is not of the required type
+ * (e.g. validator expects string but the [AbstractElement] is an object)
  * the validator **MUST** return [FormatValidator.Valid] result
  */
 @ExperimentalApi
@@ -16,7 +17,7 @@ public interface FormatValidator {
    * @param element JSON element to validate against the expected format
    * @return the result of the validation
    */
-  public fun validate(element: JsonElement): FormatValidationResult
+  public fun validate(element: AbstractElement): FormatValidationResult
 
   public companion object {
     @Suppress("ktlint:standard:function-naming", "FunctionName")

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/JsonSchema.kt

@@ -6,6 +6,8 @@ import io.github.optimumcode.json.schema.internal.DefaultAssertionContext
 import io.github.optimumcode.json.schema.internal.DefaultReferenceResolver
 import io.github.optimumcode.json.schema.internal.IsolatedLoader
 import io.github.optimumcode.json.schema.internal.JsonSchemaAssertion
+import io.github.optimumcode.json.schema.internal.wrapper.wrap
+import io.github.optimumcode.json.schema.model.AbstractElement
 import kotlinx.serialization.json.JsonElement
 import kotlin.jvm.JvmOverloads
 import kotlin.jvm.JvmStatic
@@ -28,6 +30,31 @@ public class JsonSchema internal constructor(
   public fun validate(
     value: JsonElement,
     errorCollector: ErrorCollector,
+  ): Boolean = validate(value.wrap(), errorCollector)
+
+  /**
+   * Validates [value] against this [JsonSchema].
+   * The provided [outputCollectorProvider] will be used to create [OutputCollector]
+   * which collects the validation result.
+   *
+   * @return validation result depending on [outputCollectorProvider]
+   */
+  public fun <T> validate(
+    value: JsonElement,
+    outputCollectorProvider: OutputCollector.Provider<T>,
+  ): T = validate(value.wrap(), outputCollectorProvider)
+
+  /**
+   * Validates [value] against this [JsonSchema].
+   * If the [value] is valid against the schema the function returns `true`.
+   * Otherwise, it returns `false`.
+   *
+   * All reported errors will be reported to [ErrorCollector.onError]
+   */
+  @ExperimentalApi
+  public fun validate(
+    value: AbstractElement,
+    errorCollector: ErrorCollector,
   ): Boolean {
     val context = DefaultAssertionContext(JsonPointer.ROOT, referenceResolver)
     return DelegateOutputCollector(errorCollector).use {
@@ -42,8 +69,9 @@ public class JsonSchema internal constructor(
    *
    * @return validation result depending on [outputCollectorProvider]
    */
+  @ExperimentalApi
   public fun <T> validate(
-    value: JsonElement,
+    value: AbstractElement,
     outputCollectorProvider: OutputCollector.Provider<T>,
   ): T {
     val context = DefaultAssertionContext(JsonPointer.ROOT, referenceResolver)

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/extension/ExternalAnnotationCollector.kt

@@ -1,7 +1,9 @@
 package io.github.optimumcode.json.schema.extension
 
 import io.github.optimumcode.json.schema.AnnotationKey
+import io.github.optimumcode.json.schema.ExperimentalApi
 
+@ExperimentalApi
 public interface ExternalAnnotationCollector {
   /**
    * Adds annotation with provided [key]

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/extension/ExternalAssertion.kt

@@ -1,13 +1,18 @@
 package io.github.optimumcode.json.schema.extension
 
 import io.github.optimumcode.json.schema.ErrorCollector
+import io.github.optimumcode.json.schema.ExperimentalApi
+import io.github.optimumcode.json.schema.internal.wrapper.JsonWrapper
+import io.github.optimumcode.json.schema.model.AbstractElement
 import kotlinx.serialization.json.JsonElement
 
 /**
  * This interface allows you to implement your own schema assertion.
  * This interface **does not** allow implementing custom applicators.
  * Only simple assertions (like: _format_, _type_) can be implemented.
  */
+@Suppress("detekt:ForbiddenComment")
+@ExperimentalApi
 public interface ExternalAssertion {
   /**
    * Validates passes [element].
@@ -24,9 +29,28 @@ public interface ExternalAssertion {
    * @param errorCollector handler for [io.github.optimumcode.json.schema.ValidationError] produced by assertion
    * @return `true` if element is valid against assertion. Otherwise, returns `false`
    */
+  public fun validate(
+    element: AbstractElement,
+    context: ExternalAssertionContext,
+    errorCollector: ErrorCollector,
+  ): Boolean =
+    // TODO: remove it after two minor/major release
+    validate(element.unwrap(), context, errorCollector)
+
+  // TODO: increase level to error in the next release
+  @Deprecated(
+    message = "override validate(AbstractElement, ExternalAssertionContext, ErrorCollector) instead",
+    level = DeprecationLevel.WARNING,
+  )
   public fun validate(
     element: JsonElement,
     context: ExternalAssertionContext,
     errorCollector: ErrorCollector,
-  ): Boolean
-}
+  ): Boolean = throw UnsupportedOperationException()
+}
+
+internal fun AbstractElement.unwrap(): JsonElement =
+  when (this) {
+    is JsonWrapper -> unwrap()
+    else -> error("unsupported element type: ${this::class.simpleName}")
+  }

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/extension/ExternalAssertionContext.kt

@@ -1,7 +1,9 @@
 package io.github.optimumcode.json.schema.extension
 
 import io.github.optimumcode.json.pointer.JsonPointer
+import io.github.optimumcode.json.schema.ExperimentalApi
 
+@ExperimentalApi
 public interface ExternalAssertionContext {
   /**
    * A JSON pointer to the currently validating element in the object that is being validated

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/extension/ExternalAssertionFactory.kt

@@ -1,7 +1,9 @@
 package io.github.optimumcode.json.schema.extension
 
+import io.github.optimumcode.json.schema.ExperimentalApi
 import kotlinx.serialization.json.JsonElement
 
+@ExperimentalApi
 public interface ExternalAssertionFactory {
   /**
    * A keyword that is associated with the [ExternalAssertion] created by this factory.

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/extension/ExternalLoadingContext.kt

@@ -1,7 +1,9 @@
 package io.github.optimumcode.json.schema.extension
 
 import io.github.optimumcode.json.pointer.JsonPointer
+import io.github.optimumcode.json.schema.ExperimentalApi
 
+@ExperimentalApi
 public interface ExternalLoadingContext {
   /**
    * A JSON pointer to the current position in schema associated with currently processing element

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/internal/BooleanSchemaAssertion.kt

@@ -3,13 +3,13 @@ package io.github.optimumcode.json.schema.internal
 import io.github.optimumcode.json.pointer.JsonPointer
 import io.github.optimumcode.json.schema.OutputCollector
 import io.github.optimumcode.json.schema.ValidationError
-import kotlinx.serialization.json.JsonElement
+import io.github.optimumcode.json.schema.model.AbstractElement
 
 internal class FalseSchemaAssertion(
   private val path: JsonPointer,
 ) : JsonSchemaAssertion {
   override fun validate(
-    element: JsonElement,
+    element: AbstractElement,
     context: AssertionContext,
     errorCollector: OutputCollector<*>,
   ): Boolean {
@@ -28,7 +28,7 @@ internal class FalseSchemaAssertion(
 
 internal object TrueSchemaAssertion : JsonSchemaAssertion {
   override fun validate(
-    element: JsonElement,
+    element: AbstractElement,
     context: AssertionContext,
     errorCollector: OutputCollector<*>,
   ): Boolean {

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/internal/JsonSchemaAssertion.kt

@@ -1,7 +1,7 @@
 package io.github.optimumcode.json.schema.internal
 
 import io.github.optimumcode.json.schema.OutputCollector
-import kotlinx.serialization.json.JsonElement
+import io.github.optimumcode.json.schema.model.AbstractElement
 
 internal interface JsonSchemaAssertion {
   /**
@@ -20,7 +20,7 @@ internal interface JsonSchemaAssertion {
    * @return `true` if element is valid against assertion. Otherwise, returns `false`
    */
   fun validate(
-    element: JsonElement,
+    element: AbstractElement,
     context: AssertionContext,
     errorCollector: OutputCollector<*>,
   ): Boolean

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/internal/JsonSchemaRoot.kt

@@ -3,7 +3,7 @@ package io.github.optimumcode.json.schema.internal
 import com.eygraber.uri.Uri
 import io.github.optimumcode.json.pointer.JsonPointer
 import io.github.optimumcode.json.schema.OutputCollector
-import kotlinx.serialization.json.JsonElement
+import io.github.optimumcode.json.schema.model.AbstractElement
 
 internal class JsonSchemaRoot(
   private val scopeId: Uri,
@@ -12,7 +12,7 @@ internal class JsonSchemaRoot(
   private val canBeReferencedRecursively: Boolean,
 ) : JsonSchemaAssertion {
   override fun validate(
-    element: JsonElement,
+    element: AbstractElement,
     context: AssertionContext,
     errorCollector: OutputCollector<*>,
   ): Boolean {

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/internal/RecursiveRefSchemaAssertion.kt

@@ -5,14 +5,14 @@ import io.github.optimumcode.json.pointer.plus
 import io.github.optimumcode.json.pointer.relative
 import io.github.optimumcode.json.schema.AbsoluteLocation
 import io.github.optimumcode.json.schema.OutputCollector
-import kotlinx.serialization.json.JsonElement
+import io.github.optimumcode.json.schema.model.AbstractElement
 
 internal class RecursiveRefSchemaAssertion(
   private val basePath: JsonPointer,
   private val refId: RefId,
 ) : JsonSchemaAssertion {
   override fun validate(
-    element: JsonElement,
+    element: AbstractElement,
     context: AssertionContext,
     errorCollector: OutputCollector<*>,
   ): Boolean {

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/internal/RefSchemaAssertion.kt

@@ -6,7 +6,7 @@ import io.github.optimumcode.json.pointer.plus
 import io.github.optimumcode.json.pointer.relative
 import io.github.optimumcode.json.schema.AbsoluteLocation
 import io.github.optimumcode.json.schema.OutputCollector
-import kotlinx.serialization.json.JsonElement
+import io.github.optimumcode.json.schema.model.AbstractElement
 
 internal class RefSchemaAssertion(
   private val basePath: JsonPointer,
@@ -17,7 +17,7 @@ internal class RefSchemaAssertion(
   private lateinit var refAbsolutePath: Uri
 
   override fun validate(
-    element: JsonElement,
+    element: AbstractElement,
     context: AssertionContext,
     errorCollector: OutputCollector<*>,
   ): Boolean {

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/internal/factories/ExternalAssertionFactoryAdapter.kt

@@ -7,6 +7,7 @@ import io.github.optimumcode.json.schema.extension.ExternalAssertionFactory
 import io.github.optimumcode.json.schema.internal.AssertionContext
 import io.github.optimumcode.json.schema.internal.JsonSchemaAssertion
 import io.github.optimumcode.json.schema.internal.LoadingContext
+import io.github.optimumcode.json.schema.model.AbstractElement
 import kotlinx.serialization.json.JsonElement
 
 internal class ExternalAssertionFactoryAdapter(
@@ -25,7 +26,7 @@ private class ExternalAssertionAdapter(
   private val externalAssertion: ExternalAssertion,
 ) : JsonSchemaAssertion {
   override fun validate(
-    element: JsonElement,
+    element: AbstractElement,
     context: AssertionContext,
     errorCollector: OutputCollector<*>,
   ): Boolean =

json-schema-validator/src/commonMain/kotlin/io/github/optimumcode/json/schema/internal/factories/array/AdditionalItemsAssertion.kt

@@ -5,8 +5,9 @@ import io.github.optimumcode.json.schema.AnnotationKey
 import io.github.optimumcode.json.schema.OutputCollector
 import io.github.optimumcode.json.schema.internal.AssertionContext
 import io.github.optimumcode.json.schema.internal.JsonSchemaAssertion
-import kotlinx.serialization.json.JsonArray
-import kotlinx.serialization.json.JsonElement
+import io.github.optimumcode.json.schema.model.AbstractElement
+import io.github.optimumcode.json.schema.model.ArrayElement
+import io.github.optimumcode.json.schema.model.lastIndex
 
 internal class AdditionalItemsAssertion(
   private val location: JsonPointer,
@@ -16,12 +17,12 @@ internal class AdditionalItemsAssertion(
   private val returnIfNoIndex: Boolean,
 ) : JsonSchemaAssertion {
   override fun validate(
-    element: JsonElement,
+    element: AbstractElement,
     context: AssertionContext,
     errorCollector: OutputCollector<*>,
   ): Boolean {
     return errorCollector.updateKeywordLocation(location).use {
-      if (element !is JsonArray) {
+      if (element !is ArrayElement) {
         return@use true
       }
       val lastProcessedIndex: Int =