Skip to content

Add provider-neutral Parse and SafeParse components #193

Description

@taras

Motivation

Executable Markdown workflows need deterministic JSON parsing and schema
validation before generated content can drive control flow or environmental
effects. Parsing must remain provider-neutral; model-assisted repair belongs in
explicit surrounding Markdown.

This story follows schema-validated component returns (#176).

Authoring contract

<Parse schema={schema} as="value">
  <Content />
</Parse>

<SafeParse schema={schema} as="result">
  <Content />
</SafeParse>
  • Both components are provider-neutral core components.
  • Both require schema and as, return structured JSON values, and render
    nothing.
  • Children expand to the text being parsed.
  • schema accepts either captured JSON text or an already structured JSON
    Schema value.
  • Both forms normalize the schema through the same draft-07 compiler.
  • The initial implementation supports only fragment references contained
    within the supplied schema.
  • The complete schema compiles before child content expands.
  • Invalid schema text, an invalid schema, or an asynchronous schema fails before
    child effects.
  • Child execution failures propagate unchanged; <SafeParse> handles only JSON
    syntax and schema-validation failures.

Parse results

<Parse>:

  • parses any JSON value, including scalar, array, object, and null;
  • binds the validated JSON value directly to as;
  • fails on malformed JSON or schema-invalid content.

<SafeParse> returns one of:

{ "ok": true, "value": "<validated JSON value>" }
{
  "ok": false,
  "input": "<original rendered text>",
  "errors": [
    {
      "instancePath": "",
      "schemaPath": "",
      "keyword": "parse",
      "params": {},
      "message": "..."
    }
  ]
}
  • Schema failures use the existing normalized validation issue shape:
    { instancePath, schemaPath, keyword, params, message }.
  • Malformed JSON produces one normalized issue with keyword: "parse".
  • The original rendered input is preserved exactly in a failed result.
  • Parsing and validation do not coerce types, apply defaults, remove
    properties, or otherwise transform the parsed value.

Repair

Neither component invokes an agent or repairs content. A document may inspect a
<SafeParse> failure, render its errors into a corrective prompt, and finish
with <Parse> after a bounded retry. That repair loop remains visible and
testable in Markdown.

External file and HTTP(S) $ref resolution is tracked separately in #192.

Testing

Add colocated Parse.test.md and SafeParse.test.md documents without agent
calls. Together they cover:

  • schemas supplied as captured JSON text and structured prop values;
  • object, array, scalar, boolean, and null results;
  • local fragment references;
  • successful direct binding from <Parse>;
  • successful and failed <SafeParse> result variants;
  • malformed JSON represented by a keyword: "parse" issue;
  • multiple normalized schema issues;
  • preservation of the original failed input;
  • defaults not being inserted;
  • types not being coerced; and
  • additional properties not being removed.

Add lower-level automated tests for:

  • required props and required capture name;
  • invalid schema JSON, invalid draft-07 schemas, and asynchronous schemas;
  • schema compilation occurring before child expansion;
  • child failures propagating unchanged;
  • <Parse> failure diagnostics with source and component context;
  • no rendered output;
  • deterministic capture and replay; and
  • parity across Deno, Node, and Bun.

Documentation

Acceptance criteria

  • <Parse> binds exactly the parsed, validated JSON value or fails.
  • <SafeParse> returns the documented stable union without throwing for JSON
    syntax or instance-validation failures.
  • Invalid schemas and child execution errors still fail normally.
  • Validation never transforms the parsed value.
  • Both schema input forms behave identically.
  • Markdown tests exercise all public success and safe-failure behavior.
  • Lower-level tests cover ordering, diagnostics, propagation, and replay.
  • Specification and website documentation ship in the same PR.

Not included

  • Agent-assisted or hidden repair.
  • External file or network $ref resolution.
  • Additional JSON Schema drafts.
  • Validation transformations.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions