Add notes about thread-safety to the documentation (#229)

Author: OptimumCode

README.md

@@ -351,6 +351,11 @@ val valid = schema.validate(elementToValidate, errors::add)
   |               | not                   | Supported                                                                                                                                       |
   </details>
 
+## Thread safety
+
+All public API is thread-safe unless stated otherwise.
+Please, read the documentation for each class/interface carefully before using an instance from different threads.
+
 ## Format assertion
 
 The library supports `format` assertion.

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

@@ -14,7 +14,7 @@ import kotlin.reflect.KClass
  *}
  * ```
  */
-public sealed class AnnotationKey<T : Any> private constructor(
+public sealed class AnnotationKey<T : Any>(
   private val name: String,
   internal val type: KClass<T>,
 ) {

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

@@ -7,7 +7,10 @@ import kotlin.jvm.JvmStatic
  * 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
+ * the validator **MUST** return [FormatValidator.Valid] result.
+ *
+ * If you create an implementation of [FormatValidator] that will be shared with others
+ * please make sure that it will be state-less since it might be invoked from different threads.
  */
 @ExperimentalApi
 public interface FormatValidator {

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

@@ -16,6 +16,9 @@ import io.github.optimumcode.json.schema.internal.wellknown.Draft7
 import kotlinx.serialization.json.JsonElement
 import kotlin.jvm.JvmStatic
 
+/**
+ * By default, implementations of [JsonSchemaLoader] are NOT thread-safe
+ */
 @Suppress("detekt:TooManyFunctions")
 public interface JsonSchemaLoader {
   public fun registerWellKnown(draft: SchemaType): JsonSchemaLoader =
@@ -119,6 +122,11 @@ public interface JsonSchemaLoader {
   ): JsonSchema
 
   public companion object {
+    /**
+     * Creates an instance of [JsonSchemaLoader].
+     *
+     * @return implementation of [JsonSchemaLoader]. The implementation is **NOT thread-safe**.
+     */
     @JvmStatic
     public fun create(): JsonSchemaLoader = SchemaLoader()
   }

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

@@ -13,8 +13,10 @@ private val NO_TRANSFORMATION: OutputErrorTransformer<*> = { it }
 /**
  * Provides collectors' implementations for outputs
  * defined in [draft 2020-12](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-01#section-12.4)
+ *
+ * **The implementations of [OutputCollector] are NOT thread-safe**.
  */
-public sealed class OutputCollector<T> private constructor(
+public sealed class OutputCollector<T>(
   parent: OutputCollector<T>? = null,
   transformer: OutputErrorTransformer<T> = NO_TRANSFORMATION,
 ) {

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

@@ -5,7 +5,7 @@ import kotlinx.serialization.Serializable
 import kotlinx.serialization.Transient
 import kotlin.jvm.JvmField
 
-public sealed class ValidationOutput private constructor() {
+public sealed class ValidationOutput {
   public abstract val valid: Boolean
 
   @Serializable

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

@@ -10,6 +10,9 @@ 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.
+ *
+ * If you create an implementation of [ExternalAssertion] that will be shared with others
+ * please make sure that it will be state-less since it might be invoked from different threads.
  */
 @Suppress("detekt:ForbiddenComment")
 @ExperimentalApi

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

@@ -10,10 +10,6 @@ public interface ExternalAssertionFactory {
    * This keyword **must not** overlap with any existing keywords for existing drafts.
    * If keyword overlaps with any keyword for any existing draft and [IllegalStateException] will be thrown
    * when this factory is registered in [io.github.optimumcode.json.schema.JsonSchemaLoader].
-   *
-   * NOTE: currently the library does not have **format** assertion implemented. But it will have.
-   * If you decide to implement it as an [ExternalAssertion] please be aware
-   * that one day this will cause an [IllegalStateException] as it was added to the library itself
    */
   public val keywordName: String
 

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

@@ -7,6 +7,8 @@ import io.github.optimumcode.json.schema.ExperimentalApi
  * * [ObjectElement] - corresponds to a JSON/YAML object or [Map]
  * * [ArrayElement] - corresponds to a collection of [AbstractElement]s
  * * [PrimitiveElement] - corresponds to a scalar value (string, number, boolean)
+ *
+ * The implementations are NOT required to be thread-safe.
  */
 @ExperimentalApi
 public sealed interface AbstractElement {