json_repair

    Repair streamed tool arguments with exact source audits, incremental JSON Patch, an SSE gateway, and MCP tool-call validation.

    json
    repair
    llm
    agent
    schema
    Download zip
    Author
    Version
    0.4.0
    License
    Apache-2.0
    Last updated
    11 hours ago
    Downloads
    2

    No dependencies

    #Moon JSON Repair

    Repair a single JSON reply, extract independent documents, or feed a RepairStream to inspect an incomplete argument payload. Repairs retain decimal spellings and original UTF-16 audit coordinates. Tool-call validation uses a bounded JSON Schema subset. Native command modes consume NDJSON, SSE, or MCP JSON-RPC frames. The core has no external MoonBit packages or FFI.

    TaskAPI
    Repair one documentrepair or repair_with_policy
    Apply live changesRepairStream::next_patches and apply_json_patches
    Route and validate MCP argumentsToolSchemaRegistry and guard_mcp_tool_call
    Gate executionvalidate, coerce_with_schema, and format_retry_prompt

    ///|
    test "five-line tool call repair" {
    let report = @json_repair.repair("{amount:42").unwrap()
    let schema : Json = { "required": ["amount"] }
    assert_true(@json_repair.validate(report.value, schema).is_empty())
    }

    ///|
    test "repair and validate a tool call" {
    let input =
    #|{tool:'quote', args:{amount:125.50,currency:'SGD'
    guard @json_repair.repair(input) is Ok(report) else {
    fail("expected a repairable tool call")
    }
    let schema : Json = {
    "type": "object",
    "required": ["tool", "args"],
    "properties": {
    "tool": { "enum": ["quote"] },
    "args": {
    "type": "object",
    "required": ["amount", "currency"],
    "properties": {
    "amount": { "type": "number", "minimum": 0 },
    "currency": { "enum": ["SGD", "USD"] },
    },
    },
    },
    }
    assert_eq(
    report.json,
    (
    #|{"tool":"quote","args":{"amount":125.50,"currency":"SGD"}}
    ),
    )
    assert_true(!report.edits.is_empty())
    assert_true(@json_repair.validate(report.value, schema).is_empty())
    }

    ///|
    test "preview while the model is streaming" {
    let stream = @json_repair.RepairStream::new()
    guard stream.push(
    (
    #|{"args":{"city":"Sing
    ),
    )
    is Ok(_) else {
    fail("chunk was rejected")
    }
    guard stream.preview() is Ok(preview) else { fail("preview was rejected") }
    assert_eq(
    preview.json,
    (
    #|{"args":{"city":"Sing"}}
    ),
    )
    guard stream.push(
    (
    #|apore"}}
    ),
    )
    is Ok(_) else {
    fail("chunk was rejected")
    }
    guard stream.preview() is Ok(completed) else { fail("result was rejected") }
    assert_eq(
    completed.json,
    (
    #|{"args":{"city":"Singapore"}}
    ),
    )
    assert_true(completed.edits.is_empty())
    }

    ///|
    test "extract two payloads and preserve a JSON5 integer" {
    let options : @json_repair.RepairOptions = {
    ..@json_repair.RepairOptions::default(),
    json5: true,
    }
    let reply = "First {id:0x20000000000001}\nThen [.5]"
    let blocks = @json_repair.extract_all(reply, options).unwrap()
    assert_eq(blocks.length(), 2)
    assert_eq(blocks[0].report.json, "{\"id\":9007199254740993}")
    assert_eq(blocks[1].report.json, "[0.5]")
    }

    ///|
    test "coerce a numeric argument and request a precise retry" {
    let input : Json = { "amount": "42.5", "currency": "BTC" }
    let schema : Json = {
    "properties": {
    "amount": { "type": "number", "minimum": 0 },
    "currency": { "enum": ["USD", "SGD"] },
    },
    }
    let healed = @json_repair.coerce_with_schema(input, schema)
    assert_eq(healed.edits.length(), 1)
    assert_eq(healed.errors[0].path, "$.currency")
    let prompt = @json_repair.format_retry_prompt(healed.value, schema)
    assert_true(prompt.contains("$.currency"))
    }

    ///|
    test "ignore reasoning drafts before extracting a tool call" {
    let policy = @json_repair.RepairOptions::default().with_ignore_think_blocks(
    true,
    )
    let reply = "<THINK>{amount:99</THINK>\n{amount:2"
    let blocks = @json_repair.extract_all_with_policy(reply, policy).unwrap()
    assert_eq(blocks.length(), 1)
    assert_eq(blocks[0].report.json, "{\"amount\":2}")
    assert_eq(blocks[0].report.edits[0].action, "ignore think block")
    }

    ///|
    test "apply patches as a tool field seals" {
    let stream = @json_repair.RepairStream::new()
    stream.push("{\"args\":{\"order/id\":\"SG").unwrap()
    let first = stream.next_patches().unwrap()
    assert_true(
    first.fields.any(field => {
    field.pointer == "/args/order~1id" && !field.is_sealed
    }),
    )
    stream.push("D\"}}").unwrap()
    let next = stream.next_patches().unwrap()
    assert_eq(next.patches[0].path, "/args/order~1id")
    let updated = @json_repair.apply_json_patches(
    first.report.value,
    next.patches[:],
    ).unwrap()
    assert_eq(updated.stringify(), next.report.json)
    assert_true(
    next.fields.any(field => {
    field.pointer == "/args/order~1id" && field.is_sealed
    }),
    )
    }

    ///|
    test "guard a tool call and preserve exact decimal text" {
    let schemas : Json = {
    "sum": {
    "type": "object",
    "required": ["x"],
    "properties": { "x": { "type": "integer" } },
    },
    }
    let routes = @json_repair.ToolSchemaRegistry::from_json(schemas).unwrap()
    let source =
    #|{"jsonrpc":"2.0","id":9007199254740993,"method":"tools/call","params":{"name":"sum","arguments":{"x":"9007199254740993"}}}
    let result = @json_repair.guard_mcp_tool_call(source, routes, coerce=true)
    assert_true(result.forward)
    let frame = result.frame.unwrap()
    assert_true(frame.contains("\"id\":9007199254740993"))
    assert_true(frame.contains("\"x\":9007199254740993"))
    }

    JsonValue

    using @moonbitlang/core/json { type Json as JsonValue }

    The standard-library JSON AST. Numbers retain their original decimal spelling in the Number constructor's repr field.

    CoercionEdit

    pub struct CoercionEdit {
    path : String
    kind : String
    before :
    Json

    after :
    Json

    } derive(Eq,
    Debug
    )

    One type change at an instance path. Array wrapping is logged before any subsequent conversion of its element.

    CoercionOptions

    pub(all) struct CoercionOptions {
    number_strings : Bool
    boolean_strings : Bool
    wrap_scalar_arrays : Bool
    } derive(Eq,
    Debug
    )

    The schema-directed type conversions a caller permits. Numeric strings must already be valid JSON numbers. Boolean strings must be exactly true or false. Array wrapping is independently opt-in.

    CoercionOptions::default

    Allow numeric and boolean strings to satisfy an explicit schema type. Leave scalar-to-array wrapping disabled.

    CoercionReport

    pub struct CoercionReport {
    json : String
    value :
    Json

    edits : Array[CoercionEdit]
    errors : Array[ValidationError]
    } derive(Eq,
    Debug
    )

    The coerced value, its compact JSON text, the ordered type changes, and the remaining validation errors. Inspect errors before executing a tool.

    ExtractedBlock

    pub(all) struct ExtractedBlock {
    start : SourcePosition
    end : SourcePosition
    confidence : Int
    report : RepairReport
    } derive(Eq,
    Debug
    ,
    ToJson
    )

    One non-overlapping JSON payload. Source coordinates and audit positions refer to the full reply. The end is exclusive. Confidence is a structural heuristic from 0 to 100, never a probability of user intent.

    FieldSeal

    pub(all) struct FieldSeal {
    pointer : String
    is_sealed : Bool
    } derive(Eq,
    Debug
    )

    Snapshot of a JSON Pointer's source closure. Synthetic quotes and container delimiters keep a value streaming, even after the transport has finished.
    impl ToJson for FieldSeal

    JsonPatch

    pub(all) struct JsonPatch {
    op : String
    path : String
    value :
    Json
    ?
    } derive(Eq,
    Debug
    )

    An RFC 6902 add, replace, or remove operation. The empty path points to the entire document. An explicit JSON null is distinct from an absent value.
    impl ToJson for JsonPatch

    McpGuardAudit

    pub struct McpGuardAudit {
    envelope_edits : Int
    argument_edits : Int
    coercions : Int
    } derive(Eq,
    Debug
    ,
    ToJson
    )

    Counts of edits to the incoming frame, repairs inside stringified arguments, and optional schema-directed coercions, respectively.

    McpGuardResult

    pub struct McpGuardResult {
    forward : Bool
    frame : String?
    tool : String?
    audit : McpGuardAudit
    error_code : Int?
    } derive(Eq,
    Debug
    ,
    ToJson
    )

    Routing decision for one JSON-RPC frame. With [forward] true, send [frame] to the server. Otherwise, route any [frame] back to the requesting client. A rejected notification has an [error_code] but no wire reply. [tool] is set when the frame identifies a tool by name.

    PatchFrame

    pub(all) struct PatchFrame {
    patches : Array[JsonPatch]
    fields : Array[FieldSeal]
    report : RepairReport
    } derive(Eq,
    Debug
    ,
    ToJson
    )

    Operations and closure state for a successfully repaired stream prefix. Apply the first frame to JSON null and subsequent frames in delivery order.

    RepairEdit

    pub(all) struct RepairEdit {
    kind : RepairKind
    action : String
    position : SourcePosition
    end_offset : Int
    replacement : String
    } derive(Eq,
    Debug
    )

    An edit in discovery order. The exclusive end offset equals the start offset for insertions. Formatting whitespace is outside the audit.

    RepairEdit::code

    fn RepairEdit::code(self : RepairEdit) -> String

    More specific serialized identity for optional repairs. The original RepairKind remains exhaustive for source-compatible consumers.

    RepairError

    pub(all) struct RepairError {
    kind : RepairFailureKind
    message : String
    position : SourcePosition
    } derive(Eq,
    Debug
    )

    A rejected repair with a machine-readable category, a human-readable message, and the original source position associated with the failure.

    RepairFailureKind

    pub(all) enum RepairFailureKind {
    EmptyInput
    UnexpectedToken
    InvalidUnicode
    InvalidNumber
    DuplicateKey
    TrailingContent
    DepthLimit
    InputLimit
    EditLimit
    } derive(Eq,
    Debug
    )

    Why one document was rejected. A limit error indicates the corresponding input, nesting, or edit budget was exhausted.

    RepairFailureKind::code

    fn RepairFailureKind::code(self : RepairFailureKind) -> String

    Return the stable snake-case code for programmatic failure handling.

    RepairKind

    pub(all) enum RepairKind {
    StripProse
    StripFence
    StripBom
    RemoveComment
    RemoveTrailingComma
    InsertComma
    QuoteKey
    NormalizeQuote
    EscapeControl
    EscapeBackslash
    NormalizeLiteral
    CompleteLiteral
    CloseString
    CloseArray
    CloseObject
    DropIncompleteMember
    } derive(Eq,
    Debug
    )

    Classification of an edit applied to the source. Use RepairEdit::code for the most specific serialized code.

    RepairKind::code

    fn RepairKind::code(self : RepairKind) -> String

    Return the stable snake-case code for this edit category.

    RepairLimits

    pub(all) struct RepairLimits {
    max_input : Int
    max_depth : Int
    max_edits : Int
    } derive(Eq,
    Debug
    )

    Nesting is clamped to 1–256. The other limits are clamped at zero. Input size is measured in UTF-16 code units.

    RepairLimits::default

    fn RepairLimits::default() -> RepairLimits

    Allow 1,048,576 UTF-16 units, 128 container levels, and 16,384 edits.

    RepairOptions

    pub(all) struct RepairOptions {
    limits : RepairLimits
    json5 : Bool
    max_blocks : Int
    } derive(Eq,
    Debug
    )

    Single-document repair and extraction options. Set json5 to accept exact hexadecimal integers and extended decimal spellings. max_blocks limits successful extraction results and is clamped to 0–4,096.

    RepairOptions::default

    fn RepairOptions::default() -> RepairOptions

    Use the default repair limits, disable JSON5 numbers, and allow extraction to return up to 128 independent documents.

    RepairOptions::with_ignore_think_blocks

    fn RepairOptions::with_ignore_think_blocks(self : RepairOptions, ignore_think_blocks : Bool) -> RepairPolicy

    Set reasoning isolation while preserving the current repair limits, numeric options, and extraction budget.

    RepairPolicy

    pub(all) struct RepairPolicy {
    options : RepairOptions
    ignore_think_blocks : Bool
    } derive(Eq,
    Debug
    )

    Repair options plus optional isolation of case-insensitive think tags. Batch repair, extraction, and streams share the policy.

    RepairPolicy::default

    fn RepairPolicy::default() -> RepairPolicy

    Use default RepairOptions and treat reasoning tags as ordinary input.

    RepairReport

    pub(all) struct RepairReport {
    json : String
    value :
    Json

    edits : Array[RepairEdit]
    } derive(Eq,
    Debug
    )

    A successful repair with compact JSON text, its parsed value, and edits. Use json as the wire representation when an ordinary host JSON parser would lose large integers or decimal spellings.

    RepairStream

    pub struct RepairStream {
    // private fields
    }

    Append-only repair session with lexical and syntax checkpoints. Strict JSON continuations reuse committed tokens. Ambiguous syntax uses the batch parser.

    RepairStream::finalize

    Seal the source and produce the same result as a batch repair of all chunks. Subsequent pushes fail until reset; the lexical source state stays visible.

    RepairStream::new

    fn RepairStream::new(limits? : RepairLimits) -> RepairStream

    Create a stream with standard JSON syntax and optional resource limits.

    RepairStream::next_patches

    fn RepairStream::next_patches(self : RepairStream) -> Result[PatchFrame, RepairError]

    Compute changes since the last successful patch frame. Errors leave the prior baseline in place. Fields describe physical source delimiters, not the synthetic delimiters used to build the preview.

    RepairStream::preview

    Materialize the repaired document and audit for the accepted prefix. Committed syntax can be reused, while emitting full output still costs space proportional to the report.

    RepairStream::push

    fn RepairStream::push(self : RepairStream, chunk : String) -> Result[Unit, RepairError]

    Append a chunk atomically. On overflow the previously accepted prefix remains available to preview, extend, or reset.

    RepairStream::reset

    fn RepairStream::reset(self : RepairStream) -> Unit

    Discard accepted input, current framing and previous patch history.

    RepairStream::scanned_units

    fn RepairStream::scanned_units(self : RepairStream) -> Int

    Number of UTF-16 units consumed by the incremental checkpoint. Polling status does not add to it. Explicit JSON previews are tracked separately.

    RepairStream::status

    fn RepairStream::status(self : RepairStream) -> StreamStatus

    Return the lexical checkpoint without scanning the accumulated source.

    RepairStream::with_options

    fn RepairStream::with_options(options : RepairOptions) -> RepairStream

    Create a stream with the requested JSON extensions and resource limits.

    RepairStream::with_policy

    fn RepairStream::with_policy(policy : RepairPolicy) -> RepairStream

    Create a stream with the requested syntax and reasoning isolation policy.

    RepairStream::with_uncached_policy

    fn RepairStream::with_uncached_policy(policy : RepairPolicy) -> RepairStream

    Create a reference stream that reparses each source prefix. Use it to compare checkpoint results or measure the cost of full-prefix repair.

    SourcePosition

    pub(all) struct SourcePosition {
    offset : Int
    line : Int
    column : Int
    } derive(Eq,
    Debug
    ,
    ToJson
    )

    Offsets are zero-based. Lines and columns start at one. Offsets and columns count UTF-16 code units in the original input.

    StreamStatus

    pub(all) struct StreamStatus {
    position : SourcePosition
    depth : Int
    stack : Array[String]
    quote : String?
    in_comment : Bool
    stable : Bool
    stable_offset : Int
    finalized : Bool
    } derive(Eq,
    Debug
    ,
    ToJson
    )

    The source boundary observed so far. Stack entries are expected closing delimiters from outermost to innermost, capped by max_depth. A stable boundary describes balanced framing, not successful JSON or schema parsing.

    ToolSchemaRegistry

    pub struct ToolSchemaRegistry {
    // private fields
    }

    Case-sensitive, fail-closed routing from MCP tool names to input schemas. Registration validates the same schema subset as [validate] and copies each definition, so changing the input JSON later does not change the guard.

    ToolSchemaRegistry::from_json

    Build a registry from a JSON object keyed by tool name. For example, {"write_file":{"type":"object","required":["path"]}} registers one tool. An invalid definition rejects the entire map.

    ToolSchemaRegistry::new

    Start with an empty registry. Tools are denied until explicitly registered.

    ToolSchemaRegistry::register

    fn ToolSchemaRegistry::register(self : ToolSchemaRegistry, name : String, schema :
    Json
    ) -> Result[Unit, ValidationError]

    Register one nonempty tool name and a valid input schema. A duplicate name returns an error and keeps the existing route.

    ValidationError

    pub struct ValidationError {
    path : String
    keyword : String
    message : String
    } derive(Eq,
    Debug
    )

    A failed constraint. Instance paths start at $ and definition paths at $schema. Array indices are zero-based and unusual keys are JSON-quoted.

    ValidationError::to_json

    Expose ValidationError serialization through the direct to_json method.

    apply_json_patches

    fn apply_json_patches(input :
    Json
    , patches : ArrayView[JsonPatch]) -> Result[
    Json
    , String]

    Apply add, replace, and remove transactionally, without mutating the input. Root remove is rejected because the result type requires a JSON document.

    coerce_with_schema

    Convert strings only to explicitly requested types and keep the exact spelling of valid JSON number literals. Missing properties and business constraints stay visible as validation errors. The input is never mutated.

    diff_json_patches

    Generate deterministic structural changes, keeping unchanged branches and common array edges intact. Short changed array runs use edit-distance alignment. Large runs use bounded-memory positional edits. Numbers compare their lossless decimal spelling.

    test {
    let previous : Json = { "queue": [1] }
    let current : Json = { "queue": [1, 2] }
    let patches = @json_repair.diff_json_patches(previous, current)
    assert_eq(patches[0].path, "/queue/1")
    assert_eq(
    @json_repair.apply_json_patches(previous, patches[:]).unwrap(),
    current,
    )
    }

    extract_all

    fn extract_all(input : String, options : RepairOptions) -> Result[Array[ExtractedBlock], RepairError]

    Extract successfully repaired candidates in source order. A failed local candidate is skipped. Resource limits return an error rather than hiding successful blocks. Naked scalar text is ignored; language fences can frame it.

    The scanner visits source code units in order. Each emitted candidate's repair consumes a disjoint slice, and framing memory is bounded by max_depth.

    extract_all_with_policy

    fn extract_all_with_policy(input : String, policy : RepairPolicy) -> Result[Array[ExtractedBlock], RepairError]

    Extract a model reply using the requested protocol policy. Each ignored region is audited once, on the next extracted block or the last block for trailing regions. A reply without a candidate still returns an empty array.

    format_retry_prompt

    fn format_retry_prompt(value :
    Json
    , schema :
    Json
    ) -> String

    A compact retry instruction with structured paths, expectations, current values, and validated examples when available. Large values are summarized. Valid arguments produce an empty string.

    guard_mcp_tool_call

    fn guard_mcp_tool_call(source : String, registry : ToolSchemaRegistry, policy? : RepairPolicy, coerce? : Bool) -> McpGuardResult

    Repair and route a single inbound MCP JSON-RPC 2.0 frame. Known tools must pass their registered input schema. Stringified arguments are repaired and unwrapped once. Enable [coerce] to apply explicit schema-directed type conversions. Successful unchanged one-line frames retain their wire bytes.

    Irreparable JSON returns -32700, invalid envelopes return -32600, and rejected tool parameters return -32602. Notifications cannot receive replies. The guard never spawns a transport or authorizes tool execution.

    repair

    fn repair(input : String, limits? : RepairLimits) -> Result[RepairReport, RepairError]

    Repair one JSON document and record the edits against the original input. Ambiguous values such as duplicate keys and malformed numbers return Err.

    test {
    let report = @json_repair.repair("{amount:42").unwrap()
    assert_eq(report.json, "{\"amount\":42}")
    assert_true(!report.edits.is_empty())
    }

    repair_with_options

    fn repair_with_options(input : String, options : RepairOptions) -> Result[RepairReport, RepairError]

    Repair one document with explicit numeric extensions and repair limits. Use extract_all for a reply with multiple independent documents.

    repair_with_policy

    fn repair_with_policy(input : String, policy : RepairPolicy) -> Result[RepairReport, RepairError]

    Repair a model reply using the requested protocol policy. When reasoning isolation is enabled, case-insensitive think tags delimit discarded text. Valid JSON strings protect their literal tags. Unterminated reasoning runs to EOF unless a standalone close can recover an invalid quote boundary.

    validate

    Validate a JSON value against the tool-call schema subset. Definitions support type, required, properties, enum, minimum, maximum, minLength, maxLength, and items, plus boolean schemas. Definition errors take precedence even when the instance would skip a rule.