zio.blocks.schema.json

package zio.blocks.schema.json

Members list

Type members

Classlikes

object Anchor

Attributes

Companion
class
Source
JsonSchema.scala
Supertypes
class Object
trait Matchable
class Any
Self type
Anchor.type
final case class Anchor extends AnyVal

Anchor name (plain name fragment without #).

Anchor name (plain name fragment without #).

Attributes

Companion
object
Source
JsonSchema.scala
Supertypes
trait Serializable
trait Product
trait Equals
class AnyVal
trait Matchable
class Any
Show all
object DiscriminatorKind

Attributes

Companion
trait
Source
DiscriminatorKind.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
sealed trait DiscriminatorKind

Represents the strategy for specifying the discriminator used in a JSON schema for distinguishing between different subtypes of a sealed hierarchy.

Represents the strategy for specifying the discriminator used in a JSON schema for distinguishing between different subtypes of a sealed hierarchy.

Implementations of this trait define how the discriminator is represented in the serialized JSON, if any.

The possible discriminator kinds include:

  • Field with adding a custom field named as specified in the name parameter that contains a value of the subtype discriminator, e.g. {"type": "Person", ...} for case class Person(...) extends SealedTrait
  • Key, where the discriminator is represented as a JSON object key with wrapping of the encoded value in a JSON object, e.g. {"Person":{...}} for case class Person(...) extends SealedTrait.
  • None, where no discriminator is used, meaning subtype differentiation is handled by sequential attempts to parse all possible subtypes, starting from the first subtype, until a successful parse is found, or an error is thrown if none of the subtypes can be parsed from the input.

Attributes

Companion
object
Source
DiscriminatorKind.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Field
object Key
object None
final case class EvaluationResult(errors: List[Single], evaluatedProperties: Set[String], evaluatedItems: Set[Int])

Result of schema validation that tracks evaluated properties and items.

Result of schema validation that tracks evaluated properties and items.

Per JSON Schema 2020-12, unevaluatedProperties and unevaluatedItems need to know which properties/items were evaluated by any applicator keyword in the schema tree.

Value parameters

errors

Accumulated validation errors

evaluatedItems

Set of array indices that were evaluated by applicator keywords

evaluatedProperties

Set of property names that were evaluated by applicator keywords

Attributes

Companion
object
Source
JsonSchema.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object EvaluationResult

Attributes

Companion
class
Source
JsonSchema.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object Json

Attributes

Companion
trait
Source
Json.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
Json.type
sealed trait Json

A sealed trait representing a JSON value.

A sealed trait representing a JSON value.

The Json type provides a complete representation of JSON data with six possible cases: Object, Array, String, Number, Boolean, and Null.

Key design decisions:

  • Objects use Chunk[(String, Json)] to preserve insertion order
  • Object equality is order-independent (keys are compared as sets)
  • Numbers use String to preserve exact representation
  • All navigation methods return JsonSelection for fluent chaining

Attributes

Companion
object
Source
Json.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Array
class Boolean
object Null
class Number
class Object
class String
Show all
abstract class JsonCodec[A] extends BinaryCodec[A]

Abstract class for encoding and decoding values of type A to and from JSON formats. Encapsulates logic to map JSON representations into native type structures and vice versa, handling serialization and deserialization as per JSON encoding standards using UTF-8 character set.

Abstract class for encoding and decoding values of type A to and from JSON formats. Encapsulates logic to map JSON representations into native type structures and vice versa, handling serialization and deserialization as per JSON encoding standards using UTF-8 character set.

This class requires an implementation for two core operations: decoding a value of type A from a JSON representation and encoding a value of type A into a JSON representation.

Attributes

Companion
object
Source
JsonCodec.scala
Supertypes
class BinaryCodec[A]
class Object
trait Matchable
class Any
object JsonCodec

A utility object that provides constants and thread-local pools for encoding and decoding JSON structures. The object defines various type constants that represent different data types and maintains ThreadLocal pools for JsonReader and JsonWriter instances to ensure their efficient reuse.

A utility object that provides constants and thread-local pools for encoding and decoding JSON structures. The object defines various type constants that represent different data types and maintains ThreadLocal pools for JsonReader and JsonWriter instances to ensure their efficient reuse.

The JsonCodec is designed for use with methods from its associated companion type, providing a lower-level abstraction to interact with JSON-encoded binary data. These utility pools help manage reading and writing operations in a thread-safe manner while also improving performance.

Attributes

Companion
class
Source
JsonCodec.scala
Supertypes
class Object
trait Matchable
class Any
Self type
JsonCodec.type
object JsonCodecDeriver extends JsonCodecDeriver

Provides a default implementation of JsonCodecDeriver with customizable settings for JSON and binary codec derivation. This object allows the derivation of codecs for various data types, including primitives, records, variants, sequences, maps, and dynamic values.

Provides a default implementation of JsonCodecDeriver with customizable settings for JSON and binary codec derivation. This object allows the derivation of codecs for various data types, including primitives, records, variants, sequences, maps, and dynamic values.

The derivation process can be customized through pre-configured parameters, including:

  • fieldNameMapper: Controls how field names are transformed during serialization and deserialization.
  • caseNameMapper: Controls how case names in variants are transformed.
  • discriminatorKind: Determines the strategy for handling type discriminators in variants.
  • rejectExtraFields: Specifies if unrecognized fields should cause validation errors.
  • enumValuesAsStrings: Specifies whether enumeration values are represented as strings.
  • transientNone: Excludes fields with a value of None (for Option) or absent (for Maybe) during serialization.
  • requireOptionFields: Enforces the inclusion of optional fields (Option and Maybe) in deserialization.
  • transientEmptyCollection: Excludes empty collections during serialization.
  • requireCollectionFields: Enforces the inclusion of collection fields in deserialization.
  • transientDefaultValue: Excludes fields with default values during serialization.
  • requireDefaultValueFields: Enforces the inclusion of fields with default values in deserialization.

This predefined object uses the NameMapper.Identity strategy, which applies no transformation to field or case names, and DiscriminatorKind.Key, which embeds type information as a key in serialized data.

Attributes

Companion
class
Source
JsonCodecDeriver.scala
Supertypes
class Object
trait Matchable
class Any
Self type
class JsonCodecDeriver extends Deriver[JsonCodec]

Attributes

Companion
object
Source
JsonCodecDeriver.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class JsonCodecError(var spans: List[Node], message: String) extends Throwable

A custom exception class without the stack trace representing errors that occur during JSON encoding/decoding operations.

A custom exception class without the stack trace representing errors that occur during JSON encoding/decoding operations.

The JsonCodecError class extends Throwable to provide enhanced error reporting for scenarios involving JSON encoding or decoding errors where dynamic data paths (spans) are involved. These spans represent the stack of nodes traversed within the data structure when the error occurred. So that top-level spans are at the end of the list.

Value parameters

message

A descriptive message providing additional context or details about the error.

spans

A list of DynamicOptic.Node objects representing the traversal path within the data structure where the error occurred. Each node encapsulates information about a specific element (field, index, etc.).

Attributes

Source
JsonCodecError.scala
Supertypes
class Throwable
trait Serializable
class Object
trait Matchable
class Any
object JsonDiffer

Computes differences between Json values, producing JsonPatch instances that can transform one JSON value into another.

Computes differences between Json values, producing JsonPatch instances that can transform one JSON value into another.

Attributes

Source
JsonDiffer.scala
Supertypes
class Object
trait Matchable
class Any
Self type
JsonDiffer.type
object JsonFormat extends BinaryFormat[JsonCodec]

An object that represents the JSON format used for serialization and deserialization.

An object that represents the JSON format used for serialization and deserialization.

It extends the BinaryFormat class, specifying "application/json" as the MIME type and utilizing the JsonCodecDeriver for deriving the necessary codecs.

Attributes

Source
JsonCodecDeriver.scala
Supertypes
trait Format
class Object
trait Matchable
class Any
Self type
JsonFormat.type
object JsonMatch

Provides matching logic for SchemaRepr patterns against Json instances.

Provides matching logic for SchemaRepr patterns against Json instances.

This object implements structural pattern matching between schema representations and JSON values, enabling the search optic to find JSON values that match a given schema pattern.

==Matching Rules==

  • '''Wildcard''': Matches any Json value
  • '''Primitive(name)''': Matches Json primitive types:
    • "string" matches Json.String
    • "boolean" matches Json.Boolean
    • "int", "long", "short", "byte", "float", "double", "number", "bigint", "bigdecimal" all match Json.Number
    • "null" matches Json.Null
  • '''Record(fields)''': Matches Json.Object using subset matching - all specified fields must exist with matching types, but extra fields are allowed
  • '''Variant(cases)''': Returns false (JSON doesn't have tagged variants)
  • '''Sequence(elem)''': Matches Json.Array if all elements match the element pattern (empty array always matches)
  • '''Map(k, v)''': Matches Json.Object if key pattern is "string" and all values match the value pattern (empty object always matches)
  • '''Optional(inner)''': Matches Json.Null always, otherwise checks inner pattern
  • '''Nominal(name)''': Returns false (requires schema context not available in JSON)

Attributes

Source
JsonMatch.scala
Supertypes
class Object
trait Matchable
class Any
Self type
JsonMatch.type
object JsonPatch

Attributes

Companion
class
Source
JsonPatch.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
JsonPatch.type
final case class JsonPatch(ops: Chunk[JsonPatchOp])

An untyped patch that operates on Json values. Patches are composable and can be applied with different failure handling modes.

An untyped patch that operates on Json values. Patches are composable and can be applied with different failure handling modes.

Value parameters

ops

The sequence of patch operations to apply

Attributes

Companion
object
Source
JsonPatch.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final class JsonReader

The reader to parse JSON input iteratively.

The reader to parse JSON input iteratively.

Value parameters

bbuf

the byte buffer with JSON input

buf

the internal buffer with JSON input

charBuf

the internal char buffer for parsed strings

config

the JSON reader configuration

head

the head position in the internal buffer

in

the input stream with JSON input

markNum

the number of mark positions in the stack

marks

the stack of mark positions

maxTop

a maximum offset of the stack top

stack

a pre-allocated stack of registers

tail

the tail position in the internal buffer

top

an offset of the stack top

totalRead

the total number of read bytes

Attributes

Companion
object
Source
JsonReader.scala
Supertypes
class Object
trait Matchable
class Any
object JsonReader

Attributes

Companion
class
Source
JsonReader.scala
Supertypes
class Object
trait Matchable
class Any
Self type
JsonReader.type
object JsonSchema

Attributes

Companion
trait
Source
JsonSchema.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
JsonSchema.type
sealed trait JsonSchema extends Product, Serializable

A JSON Schema 2020-12 representation.

A JSON Schema 2020-12 representation.

This sealed trait provides a complete model of JSON Schema with:

  • Boolean schemas (True accepts all, False rejects all)
  • Full schema objects with all standard vocabularies
  • Round-trip JSON serialization via toJson / fromJson
  • Validation via check method returning accumulated errors
  • Combinators (&& for allOf, || for anyOf, ! for not)

Attributes

Companion
object
Source
JsonSchema.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Known subtypes
object False
class Object
object True
sealed trait JsonSchemaType extends Product, Serializable

Represents the "type" keyword values in JSON Schema.

Represents the "type" keyword values in JSON Schema.

Note: This is distinct from JsonType which represents runtime JSON value types. JSON Schema's type keyword includes "integer" as a distinct type, while runtime JSON only has "number" for all numeric values.

Attributes

Companion
object
Source
JsonSchemaType.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Known subtypes
object Array
object Boolean
object Integer
object Null
object Number
object Object
object String
Show all
object JsonSchemaType

Attributes

Companion
trait
Source
JsonSchemaType.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class JsonSelection(either: Either[SchemaError, Chunk[Json]]) extends AnyVal

A wrapper around Either[SchemaError, Chunk[Json]] that provides fluent chaining for JSON navigation and querying operations.

A wrapper around Either[SchemaError, Chunk[Json]] that provides fluent chaining for JSON navigation and querying operations.

JsonSelection enables a fluent API style for navigating through JSON structures:

import zio.blocks.schema.json._

val json = Json.Object(
 "users" -> Json.Array(
   Json.Object("name" -> Json.String("Alice"))
 )
)

val names: JsonSelection =
 json.get("users").arrays.apply(0).get("name").strings

The selection can contain zero, one, or multiple JSON values, supporting both single-value navigation and multi-value queries.

Attributes

Companion
object
Source
JsonSelection.scala
Supertypes
trait Serializable
trait Product
trait Equals
class AnyVal
trait Matchable
class Any
Show all
object JsonSelection

Attributes

Companion
class
Source
JsonSelection.scala
Supertypes
class Object
trait Matchable
class Any
Self type
sealed trait JsonType extends Json => Boolean

A sealed trait representing the type of a JSON value.

A sealed trait representing the type of a JSON value.

This is used by MergeStrategy to make decisions about recursion without needing access to the actual JSON values.

Each case provides two type members:

  • Type: The corresponding Json subtype (e.g., Json.Object)
  • Unwrap: The underlying Scala type of the value (e.g., Chunk[(String, Json)])

Attributes

Companion
object
Source
JsonType.scala
Supertypes
trait Json => Boolean
class Object
trait Matchable
class Any
Known subtypes
object Array
object Boolean
object Null
object Number
object Object
object String
Show all
object JsonType

Attributes

Companion
trait
Source
JsonType.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
JsonType.type
object JsonWriter

Attributes

Companion
class
Source
JsonWriter.scala
Supertypes
class Object
trait Matchable
class Any
Self type
JsonWriter.type
final class JsonWriter

A writer for iterative serialization of JSON keys and values.

A writer for iterative serialization of JSON keys and values.

Value parameters

bbuf

a byte buffer for writing JSON data

buf

an internal buffer for writing JSON data

comma

a flag indicating if comma should precede the next element

config

a writer configuration

count

the current position in the internal buffer

disableBufGrowing

a flag indicating if growing of the internal buffer is disabled

indention

the current indention level

limit

the last position in the internal buffer

maxTop

a maximum offset of the stack top

out

the output stream for writing JSON data

stack

a pre-allocated stack of registers

top

an offset of the stack top

Attributes

Companion
object
Source
JsonWriter.scala
Supertypes
class Object
trait Matchable
class Any
sealed trait MergeStrategy extends (DynamicOptic, Json, Json) => Json

Strategy for merging two JSON values.

Strategy for merging two JSON values.

A MergeStrategy is a function (DynamicOptic, Json, Json) => Json that determines how to merge two JSON values at a given path. The recurse method controls whether the merge driver should descend into containers (objects/arrays) or call apply directly.

When recurse returns true for a container type:

  • Objects are merged by key (union of keys, recursive merge on shared keys)
  • Arrays are merged by index (union of indices, recursive merge on shared indices)

When recurse returns false, apply is called with the container values directly.

Attributes

Companion
object
Source
MergeStrategy.scala
Supertypes
trait (DynamicOptic, Json, Json) => Json
class Object
trait Matchable
class Any
Known subtypes
object Auto
object Concat
class Custom
object Replace
object Shallow
object MergeStrategy

Attributes

Companion
trait
Source
MergeStrategy.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
object NonNegativeInt extends NonNegativeIntCompanionVersionSpecific

Attributes

Companion
class
Source
JsonSchema.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final case class NonNegativeInt extends AnyVal

Non-negative integer (>= 0). Used for minLength, maxLength, minItems, etc.

Non-negative integer (>= 0). Used for minLength, maxLength, minItems, etc.

Attributes

Companion
object
Source
JsonSchema.scala
Supertypes
trait Serializable
trait Product
trait Equals
class AnyVal
trait Matchable
class Any
Show all
trait NonNegativeIntCompanionVersionSpecific

Attributes

Source
NonNegativeIntCompanionVersionSpecific.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
final case class PositiveNumber extends AnyVal

Strictly positive number (> 0). Used for multipleOf.

Strictly positive number (> 0). Used for multipleOf.

Attributes

Companion
object
Source
JsonSchema.scala
Supertypes
trait Serializable
trait Product
trait Equals
class AnyVal
trait Matchable
class Any
Show all
object PositiveNumber extends PositiveNumberCompanionVersionSpecific

Attributes

Companion
class
Source
JsonSchema.scala
Supertypes
class Object
trait Matchable
class Any
Self type
trait PositiveNumberCompanionVersionSpecific

Attributes

Source
PositiveNumberCompanionVersionSpecific.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object ReaderConfig extends ReaderConfig

Attributes

Companion
class
Source
ReaderConfig.scala
Supertypes
class ReaderConfig
trait Serializable
class Object
trait Matchable
class Any
Self type
class ReaderConfig extends Serializable

Configuration for zio.blocks.schema.json.JsonReader that contains flags for tuning of preferred sizes for internal buffers that are created on the reader instantiation and reused in runtime for parsing of messages. All configuration params already initialized by recommended default values, but in some cases they should be altered for performance reasons:

Configuration for zio.blocks.schema.json.JsonReader that contains flags for tuning of preferred sizes for internal buffers that are created on the reader instantiation and reused in runtime for parsing of messages. All configuration params already initialized by recommended default values, but in some cases they should be altered for performance reasons:

  • increase preferred size of an internal byte buffer for parsing from java.io.InputStream or java.nio.ByteBuffer to reduce allocation rate of grown and then reduced buffers during parsing of large (>32Kb) numbers (including stringified), raw values, or ADT instances with the discriminator field doesn't appear at the beginning of the JSON object
  • increase the preferred size of an internal char buffer to reduce the allocation rate of grown and then reduced buffers when large (>4Kb) string instances

Value parameters

checkForEndOfInput

a flag to check and raise an error if some non-whitespace bytes are detected after successful parsing of the value

maxBufSize

a max size (in bytes) of an internal byte buffer when parsing from java.io.InputStream or java.nio.ByteBuffer

maxCharBufSize

a max size (in chars) of an internal char buffer for parsing of string values

preferredBufSize

a preferred size (in bytes) of an internal byte buffer when parsing from java.io.InputStream or java.nio.ByteBuffer

preferredCharBufSize

a preferred size (in chars) of an internal char buffer for parsing of string values

Attributes

Companion
object
Source
ReaderConfig.scala
Supertypes
trait Serializable
class Object
trait Matchable
class Any
Known subtypes
object ReaderConfig
object RegexPattern

Attributes

Companion
class
Source
JsonSchema.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class RegexPattern(value: String)

ECMA-262 regular expression pattern.

ECMA-262 regular expression pattern.

Attributes

Companion
object
Source
JsonSchema.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
sealed trait SchemaType extends Product, Serializable

Attributes

Companion
object
Source
JsonSchemaType.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Known subtypes
class Single
class Union
object SchemaType

Attributes

Companion
trait
Source
JsonSchemaType.scala
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
SchemaType.type
final case class UriReference extends AnyVal

URI-Reference per RFC 3986 (may be relative).

URI-Reference per RFC 3986 (may be relative).

Attributes

Companion
object
Source
JsonSchema.scala
Supertypes
trait Serializable
trait Product
trait Equals
class AnyVal
trait Matchable
class Any
Show all
object UriReference

Attributes

Companion
class
Source
JsonSchema.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final case class ValidationOptions(validateFormats: Boolean = ...)

Options for JSON Schema validation behavior.

Options for JSON Schema validation behavior.

Value parameters

validateFormats

When true, the format keyword is validated (format assertion vocabulary). When false, format is treated as an annotation only (default per JSON Schema 2020-12).

Attributes

Companion
object
Source
JsonSchema.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ValidationOptions

Attributes

Companion
class
Source
JsonSchema.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object WriterConfig extends WriterConfig

Attributes

Companion
class
Source
WriterConfig.scala
Supertypes
class WriterConfig
trait Serializable
class Object
trait Matchable
class Any
Self type
class WriterConfig extends Serializable

Configuration for zio.blocks.schema.json.JsonWriter that contains params for formatting of output JSON and for tuning of preferred size for internal byte buffer that is created on the writer instantiation and reused in runtime for serialization of messages using any type of output except heap byte buffers supplied as arguments. All configuration params already initialized to default values, but in some cases they should be altered:

Configuration for zio.blocks.schema.json.JsonWriter that contains params for formatting of output JSON and for tuning of preferred size for internal byte buffer that is created on the writer instantiation and reused in runtime for serialization of messages using any type of output except heap byte buffers supplied as arguments. All configuration params already initialized to default values, but in some cases they should be altered:

  • turn on pretty printing by specifying of an indention step that is greater than 0
  • turn on escaping of Unicode characters to serialize with only ASCII characters
  • increase the preferred size of an internal byte buffer to reduce the allocation rate of grown and then reduced internal buffers when the serialized output size is greater than 32Kb

Value parameters

escapeUnicode

a flag to turn on hexadecimal escaping of all non-ASCII chars

indentionStep

a size of indention for pretty-printed formatting or 0 for compact output

preferredBufSize

a preferred size (in bytes) of an internal byte buffer when writing to any type of output except pre-allocated byte arrays or heap byte buffers supplied as arguments

Attributes

Companion
object
Source
WriterConfig.scala
Supertypes
trait Serializable
class Object
trait Matchable
class Any
Known subtypes
object WriterConfig

Extensions

Extensions

extension (inline sc: StringContext)
inline def json(inline args: Any*): Json

Attributes

Source
package.scala