Package dev.omnist.codec

Class JsonCodec

java.lang.Object
dev.omnist.codec.JsonCodec
public final class JsonCodec extends Object
Codec for reading and writing the Omnist Document model as JSON (omnist-spec ยง7.3).

Reading: JSON objects map to Node values; JSON arrays appearing as object-field values map to repeated edges with the same label; bare top-level arrays and nested arrays are rejected because they have no labeled-edge representation. Temporal scalars (Scalar.DateScalar, Scalar.TimeScalar, Scalar.DateTimeScalar) are written as ISO-8601 strings with an accompanying format.temporal-stringified adjustment.

Writing: Double.NaN and infinite values are replaced with null and reported as format.float-special errors.

This class is stateless; all methods are static.

  • Method Details

    • read

      public static Document read(String text)
      Parses JSON text into a Document without schema guidance. Equivalent to read(text, null).
      Parameters:
      text - the JSON text; must not be null
      Returns:
      the parsed document
      Throws:
      RuntimeException - if the JSON is syntactically invalid or structurally unsupported

    • read

      public static Document read(String text, Schema schema)
      Parses JSON text into a Document.

      The schema parameter is intentionally unused here: JSON's own grammar already distinguishes strings/numbers/booleans natively, so there is no scalar-kind ambiguity for a schema to resolve at parse time (unlike XmlCodec.read(String, dev.omnist.schema.Schema), where every value is a string until schema-guided pre-typing runs). Schema-driven coercion of an already-typed value (e.g. a JSON string into a schema's date field) is a separate concern handled by a later Materializer call, not by this method.

      Parameters:
      text - the JSON text; must not be null
      schema - accepted for call-site symmetry with the other format codecs; has no effect
      Returns:
      the parsed document
      Throws:
      RuntimeException - if the JSON is syntactically invalid, or if the root value is an array, or if nesting depth exceeds 200, or if node count exceeds 1,000,000

    • write

      public static String write(Document node)
      Serializes a Document to compact JSON with no indentation. Equivalent to write(node, null, false, null).
      Parameters:
      node - the document to serialize
      Returns:
      the JSON text
      Throws:
      WriteException - if the document has structural issues (e.g. non-representable values)

    • write

      public static String write(Document node, Integer indent, boolean strict, WriteReport report)
      Serializes a Document to JSON, optionally indented and in strict mode.

      Temporal scalars are written as ISO-8601 strings; Double.NaN and infinite values are replaced with null and reported as format.float-special. Repeated edges with the same label are grouped into a JSON array under that key.

      Parameters:
      node - the document to serialize
      indent - if positive, pretty-print with that many spaces; null or 0 for compact
      strict - if true, throws a WriteException instead of accumulating adjustments
      report - if non-null, receives all format adjustment records; may be null
      Returns:
      the JSON text
      Throws:
      WriteException - if strict is true and any adjustment is required

    • check

      public static WriteReport check(Document node)
      Checks a Document for JSON-representability issues without serializing it. Returns a WriteReport that callers can inspect before deciding whether to proceed.
      Parameters:
      node - the document to check
      Returns:
      a report of any format adjustments that would be applied during write(dev.omnist.document.Document)