@x12i/io-matrix-schema

Types, Zod validation, and pure utilities for the Object–Property I/O Matrix JSON format.

Install

pnpm add @x12i/io-matrix-schema

Document format (I/O contract)

The only persistence unit is a versioned document. Never persist steps alone — object types, properties, abstracts, transforms and examples travel together.

{
  "formatVersion": "1.2.0",
  "matrix": {
    "abstractCatalog": ["asset_id", "cwe_ids"],
    "objectTypes": [
      {
        "key": "Finding",
        "label": "Finding",
        "abstracts": ["finding"],
        "properties": [
          { "key": "summary", "label": "summary", "abstracts": ["summary_text"] }
        ]
      }
    ],
    "steps": [
      {
        "id": "draft",
        "order": 1,
        "name": "Draft summary",
        "kind": "ai-service",
        "process": "Draft a finding summary.",
        "inputs": {},
        "outputs": { "Finding.summary": "R" },
        "abstractOutputs": { "summary_text": "R" },
        "transforms": [
          {
            "to": "Finding.summary",
            "from": [],
            "op": { "kind": "derived", "note": "Model-drafted summary" }
          }
        ],
        "examples": [
          {
            "id": "ex1",
            "input": {},
            "expectedOutput": { "Finding.summary": "Example summary" }
          }
        ]
      }
    ]
  }
}

| Field | Role | |-------|------| | formatVersion | 1.x documents parse; current write version is 1.2.0 | | matrix.objectTypes | Raw object model (keys, labels, optional abstracts[]) | | matrix.objectTypes[].properties | Property keys + optional abstracts[] | | matrix.abstractCatalog | Canonical abstract names | | matrix.steps[].inputs/outputs | Raw column I/O (Object.property → R/S/O/-) | | matrix.steps[].abstractInputs/Outputs/Adds | Abstract-name I/O | | matrix.steps[].transforms | Declarative field transforms (copy, rename, template, …) | | matrix.steps[].examples | Try-playground fixtures (travel with the document) |

parseDocument / serializeDocument round-trip the full document. Markdown export is view-aware (respects filters and naming lens) and appends abstract-mapping and transforms sections when present — it is not a lossless persistence format. Prefer JSON for load/save.

Cell values

| Symbol | Meaning | |--------|---------| | R | Required | | S | Supporting / recommended | | O | Optional | | - | Not used |

Step kinds

connector | data-service | ai-service | target-connector | ui

A step may optionally include a nested subMatrix with the same shape.

API

import {
  parseDocument,
  serializeDocument,
  documentToJson,
  computeIssues,
  computeCollapsedFlow,
  computeAbstractCoverage,
  deriveTransforms,
  evaluateStep,
  evaluatePipeline,
  projectToAbstracts,
  sampleInputFor,
  groupStepsIntoSubMatrix,
  flattenSubMatrixStep,
  matrixToMarkdown,
  EMPTY_MATRIX,
} from '@x12i/io-matrix-schema';

• parseDocument / serializeDocument — versioned import/export envelope
• computeIssues / computeCollapsedFlow — derived pipeline analysis (includes abstract I/O issues)
• computeAbstractCoverage / deriveTransforms — mapping helpers
• evaluateStep / evaluatePipeline / projectToAbstracts — Try playground evaluator
• groupStepsIntoSubMatrix / flattenSubMatrixStep — promote steps ↔ sub-matrix (preserves abstracts)
• matrixToMarkdown — view-aware Markdown export

This package contains no sample business data. Demo fixtures live in the monorepo data/ folder.