zayra-format

The official format engine for ZAYRA's custom file formats. zayra-format parses, validates, and (soon) converts ZAYRA's own file types — the .zs, .zcfg, .zproj, .zpkg, .zmod, .zplug, .zflow, .zagent, and .zmodel files the rest of the ecosystem reads and writes.

This is version 0.0.1. It contains no database logic, no AI logic, no API keys, and no frontend code — this package only handles ZAYRA file formats.

Installation

npm install zayra-format

Usage

import { createDefaultRegistry, FormatParser } from "zayra-format";

const registry = createDefaultRegistry(); // every built-in ZAYRA format, pre-registered
const parser = new FormatParser(registry);

// Read + validate a config file in one call:
const config = await parser.load("./app.zcfg");

// Or step by step:
const raw = await parser.read("./app.zcfg");
parser.validate(raw, ".zcfg");

// Write one back out:
await parser.write("./app.zcfg", { name: "app-settings", version: "1.0", settings: { theme: "dark" } });

Supported formats

| Extension | Name | Purpose | Required fields | | --- | --- | --- | --- | | .zs | ZAYRA Source | Internal scripts, logic definitions, automation instructions | name, version, instructions | | .zcfg | ZAYRA Config | Settings, preferences, system configuration | name, version, settings | | .zproj | ZAYRA Project | Project metadata, project structure, workspace information | name, version, structure | | .zpkg | ZAYRA Package | Package information, dependencies, version metadata | name, version, dependencies | | .zmod | ZAYRA Module | Module definitions, module information | name, version, definition | | .zplug | ZAYRA Plugin | Plugin metadata, plugin configuration | name, version, configuration | | .zflow | ZAYRA Workflow | Automation flows, task sequences | name, version, steps | | .zagent | ZAYRA Agent | AI agent configuration, agent behavior settings | name, version, behavior | | .zmodel | ZAYRA Model | Model information, capability metadata | name, version, capabilities |

Every ZAYRA format file is UTF-8 JSON — the extension identifies which ZAYRA format a file is; the required fields above are that format's schema.

// app.zflow
{
  "name": "Research topic",
  "version": "1.0",
  "steps": ["Search information", "Analyze results", "Generate summary"]
}

Parser System

parser.parse(text, extension?); // string -> object, no filesystem access
parser.stringify(content);       // object -> string
await parser.read(filePath);      // read + parse
await parser.write(filePath, content); // stringify + write
parser.validate(content, extension);    // check structure/required fields/version
await parser.load(filePath);             // read + validate in one call

read()/write()/validate()/load() all throw FormatError (code "UNKNOWN_FORMAT") if the file's extension isn't registered — register it first with registerFormat().

Format Registry

New formats — ZAYRA's own future ones, or an application's private extensions — are added the exact same way the 9 built-in formats are, with no changes to this package's code:

import { FormatRegistry } from "zayra-format";

const registry = new FormatRegistry();
registry.registerFormat({
  extension: ".zwidget",
  name: "ZAYRA Widget",
  description: "Custom UI widget definitions for an app built on ZAYRA.",
  requiredFields: ["name", "version", "widget"],
  latestVersion: "1.0",
});

registry.getFormat(".zwidget");    // the definition above
registry.hasFormat(".zwidget");     // true
registry.listFormats();              // every registered format, built-in + custom
registry.unregisterFormat(".zwidget");

createDefaultRegistry() (from the package root) returns a FormatRegistry with all 9 built-in formats already registered — the fast path for most consumers.

Validation System

import { validate, validateStructure, validateRequiredFields, validateVersion, ZCFG_FORMAT } from "zayra-format";

validate(content, ZCFG_FORMAT); // runs all three checks below, in order, returns { valid: true } or throws

validateStructure(content);              // must be a plain JSON object at the top level
validateRequiredFields(content, format); // every format.requiredFields key must be present
validateVersion(content, format);        // "version", if present, must be a non-empty string

Both FormatParser.validate() and the standalone validate() run the same pipeline — the parser version just also resolves the format definition from a registry by extension first.

Conversion Support

Prepared, minimal support for format conversion, migration, and version upgrades — a pluggable converter registry with no built-in converters yet:

import { ConversionRegistry } from "zayra-format";

const conversions = new ConversionRegistry();
conversions.registerConverter("[email protected]", "[email protected]", (content) => ({
  ...content,
  version: "2.0",
}));

conversions.hasConverter("[email protected]", "[email protected]"); // true
conversions.convert("[email protected]", "[email protected]", oldConfig); // runs the registered converter
conversions.listConverters(); // ["[email protected]>[email protected]"]

Errors

• FormatError — base class; also thrown directly for an unregistered extension (code: "UNKNOWN_FORMAT"), a bad format/converter definition, or a missing converter
• FormatParseError — content wasn't valid JSON (code: "PARSE_ERROR")
• FormatValidationError — failed structure/required-fields/version checks (code: "INVALID_STRUCTURE" | "MISSING_FIELDS" | "INVALID_VERSION"); carries err.missing for the fields check

import { FormatValidationError } from "zayra-format";

try {
  await parser.load("./broken.zpkg");
} catch (err) {
  if (err instanceof FormatValidationError && err.code === "MISSING_FIELDS") {
    console.error(`Missing: ${err.missing.join(", ")}`);
  }
}

What this package deliberately does NOT do

Per its design rules:

• No database logic — reads/writes go straight to the filesystem, nothing is persisted elsewhere
• No AI logic — .zagent/.zmodel files are just structured metadata this package parses and validates, it doesn't interpret or run them
• No API keys — nothing here calls a network service
• No frontend code
• This package only handles ZAYRA file formats

Project structure

zayra-format/
  src/
    index.js         # public entry point + createDefaultRegistry()
    parser.js           # FormatParser — parse/read/write/validate/load
    validator.js           # Validation System — structure/required-fields/version
    registry.js               # FormatRegistry — registerFormat/getFormat/listFormats
    conversion.js                # ConversionRegistry — prepared conversion/migration support
    errors.js                       # FormatError, FormatParseError, FormatValidationError
    formats/                           # one file per built-in ZAYRA format
      zs.js
      zcfg.js
      zproj.js
      zpkg.js
      zmod.js
      zplug.js
      zflow.js
      zagent.js
      zmodel.js
      index.js                            # aggregates the 9 above + registerBuiltInFormats()
  package.json
  README.md

API reference

class FormatParser

| Method | Description | | --- | --- | | new FormatParser(registry) | registry — a FormatRegistry instance. | | parse(text, extension?) | JSON string -> object. | | stringify(content) | Object -> pretty-printed JSON string. | | read(filePath) | Read + parse from disk. | | write(filePath, content) | Stringify + write to disk. | | validate(content, extension) | Run the Validation System pipeline. | | load(filePath) | read() + validate() in one call. |

class FormatRegistry

| Method | Description | | --- | --- | | registerFormat(definition) | { extension, name, description?, requiredFields?, latestVersion? }. | | getFormat(extension) / hasFormat(extension) | Look up a registered format (case-insensitive). | | unregisterFormat(extension) | Remove a format. | | listFormats() | Every registered format. |

class ConversionRegistry

| Method | Description | | --- | --- | | registerConverter(from, to, convert) | convert: (content) => content. | | hasConverter(from, to) / convert(from, to, content) | Check for / run a registered converter. | | listConverters() | Every registered "from->to" pair. |

Other exports

createDefaultRegistry(), validate(), validateStructure(), validateRequiredFields(), validateVersion(), BUILT_IN_FORMATS, registerBuiltInFormats(), ZS_FORMAT, ZCFG_FORMAT, ZPROJ_FORMAT, ZPKG_FORMAT, ZMOD_FORMAT, ZPLUG_FORMAT, ZFLOW_FORMAT, ZAGENT_FORMAT, ZMODEL_FORMAT, FormatError, FormatParseError, FormatValidationError

License

MIT