@schemair/core

Core serializable type graph model for SchemaIR.

@schemair/core defines the minimal declaration model used by SchemaIR. It answers one question:

What does a SchemaNode look like?

Install

npm install @schemair/core

Status

Experimental. The package is published early to establish the public package name and API surface. Expect changes before a stable 1.0.0 release.

What It Defines

@schemair/core provides TypeScript types for the smallest serializable schema model:

• SchemaNode
• SchemaConstraint
• primitive
• literal
• record
• array
• union
• ref
• selfRef

The primitive set is intentionally small:

• string
• number
• boolean
• null

Domain-level meanings such as integer, date, datetime, uuid, base64, or secret belong in the value layer through semanticPath and constraints, not in the primitive set.

Example

import type { SchemaNode } from '@schemair/core';

const customerSchema: SchemaNode = {
  kind: 'record',
  fields: [
    {
      key: 'name',
      required: true,
      schema: {
        kind: 'primitive',
        name: 'string',
      },
    },
    {
      key: 'email',
      schema: {
        kind: 'primitive',
        name: 'string',
        semanticPath: ['schemair', 'standard', 'email'],
      },
    },
  ],
};

Boundaries

@schemair/core is declaration-only. It does not perform:

• payload validation
• schema definition validation
• constraint execution
• refPath resolution
• JSON Schema or OpenAPI export
• form or view projection
• registry, snapshot, publication, or permission lifecycle management

Those responsibilities belong to other SchemaIR packages or to host systems built on top of SchemaIR.

References

A ref node stores only:

{
  kind: 'ref',
  refPath: string[]
}

The meaning of that path is host-defined. SchemaIR core does not decide whether it points to a schema id, a URL, a registry key, or any other lookup mechanism.

Self References

A selfRef node represents recursion back to the current root schema.

It does not carry refPath, semanticPath, or constraints, and it is not intended to be used as the top-level schema node.

Utilities

The package also exports small deterministic helpers:

• normalizeSchemaNode
• schemaFingerprint
• compareSchemaNode
• getSchemaRegistryKey

These helpers are intentionally simple and do not replace validation or graph analysis packages.

License

Apache-2.0