Serialization & validation

The library reads and writes its native JSON format, and validates untrusted input at the boundary with zod schemas.

Export

import { exportGrammar, exportGraph } from 'graph-grammar'

const json = exportGrammar(grammar) // pretty-printed JSON string
const graphJson = exportGraph(engine.graph)

Import (validated)

importGrammar parses JSON, back-fills the optional top-level fields, and validates the result against the schema. It throws a path-qualified error if the input can’t be made valid:

import { importGrammar } from 'graph-grammar'

try {
  const grammar = importGrammar(jsonString)
} catch (err) {
  console.error(err.message) // e.g. "Invalid grammar: rules.0.enabled: expected boolean"
}

For UI flows, prefer the non-throwing variant:

import { safeImportGrammar } from 'graph-grammar'

const res = safeImportGrammar(jsonString)
if (res.ok) {
  use(res.grammar)
} else {
  showError(res.error) // precise, path-qualified message
}

Parse a graph from text

parseGraph auto-detects several convenient formats , handy for pasting a quick host graph:

import { parseGraph } from 'graph-grammar'

parseGraph(`{ "nodes": [...], "edges": [...] }`) // JSON
parseGraph('A -> B -> C') // edge list
parseGraph('digraph { A -> B [label=x]; B -> C }') // DOT-lite

A well-formed JSON graph is taken verbatim; loosely-shaped input (numeric ids, missing props) is normalized.

Validate without importing

The zod schemas are exported directly, so you can validate or narrow data in your own code:

import { GrammarSchema, GraphSchema } from 'graph-grammar'

const result = GraphSchema.safeParse(unknownValue)
if (result.success) {
  // result.data is a fully-typed Graph
}

Every schema corresponds to a type in the API reference , GraphSchema ↔ Graph, RuleSchema ↔ Rule, and so on. They’re kept in lockstep with the TypeScript types at compile time.

Generators

For testing and demos:

import { randomGraph, gridGraph } from 'graph-grammar'

const r = randomGraph(50, 1.5, ['A', 'B']) // 50 nodes, ~75 edges, two labels
const g = gridGraph(10, 10) // a 10×10 grid