Skip to main content

softschema

JavaScript / TypeScript API reference for the module softschema.

Public API​

Class: Contracts​

Canonical path: softschema.Contracts

Declared in: packages/typescript/src/registry.ts

Signature​

class Contracts {}

Class: EnvelopeAmbiguityError​

Canonical path: softschema.EnvelopeAmbiguityError

Declared in: packages/typescript/src/validate.ts

Signature​

class EnvelopeAmbiguityError extends Error {}

Class: SchemaView​

Canonical path: softschema.SchemaView

Declared in: packages/typescript/src/schemaView.ts

Signature​

class SchemaView {}

Constructor: constructor​

Canonical path: softschema.EnvelopeAmbiguityError.constructor

Declared in: packages/typescript/src/validate.ts

Signature​

constructor(candidates: string[]) {}

Constructor: constructor​

Canonical path: softschema.SchemaView.constructor

Declared in: packages/typescript/src/schemaView.ts

Signature​

constructor(schema: SchemaNode) {}

Function: compileSchema​

Canonical path: softschema.compileSchema

Declared in: packages/typescript/src/compile.ts

Signature​

function compileSchema(
  zodSchema: z.ZodType,
  outPath: string,
  options: CompileOptions,
): CompileResult {}

Function: inferEnvelopeKey​

Canonical path: softschema.inferEnvelopeKey

Declared in: packages/typescript/src/validate.ts

Signature​

function inferEnvelopeKey(frontmatter: Record<string, unknown>): string | null {}

Function: parseSchemaMetadata​

Canonical path: softschema.parseSchemaMetadata

Declared in: packages/typescript/src/models.ts

Signature​

function parseSchemaMetadata(raw: unknown): SchemaMetadata | null {}

Function: regenerate​

Canonical path: softschema.regenerate

Declared in: packages/typescript/src/generate.ts

Signature​

function regenerate(
  path: string,
  options: { check?: boolean; schemaRoot?: string } = {},
): RegenerateResult {}

Function: softField​

Canonical path: softschema.softField

Declared in: packages/typescript/src/softField.ts

Signature​

function softField<T extends z.ZodType>(schema: T, options: SoftFieldOptions): T {}

Function: validateArtifact​

Canonical path: softschema.validateArtifact

Declared in: packages/typescript/src/validate.ts

Signature​

function validateArtifact(
  docPath: string,
  contract: Contract,
  options: {
    semanticModel?: z.ZodType;
    metadataMode?: MetadataMode;
    /**
     * An already-parsed frontmatter (from `readFrontmatter`); when supplied for a
     * frontmatter-md contract the document is not re-read. The CLI passes what it
     * parsed for binding inference so the file is read once.
     */
    preParsed?: RawFrontmatter;
  } = {},
): ArtifactValidationResult {}

Function: validateSemantic​

Canonical path: softschema.validateSemantic

Declared in: packages/typescript/src/validate.ts

Signature​

function validateSemantic(values: unknown, model: z.ZodType): SemanticResult {}

Function: validateStructural​

Canonical path: softschema.validateStructural

Declared in: packages/typescript/src/validate.ts

Signature​

function validateStructural(
  values: unknown,
  schemaObject: Record<string, unknown>,
  options: { strictExtras?: boolean; resources?: Record<string, Record<string, unknown>> } = {},
): StructuralResult {}

Function: validateValues​

Canonical path: softschema.validateValues

Declared in: packages/typescript/src/validate.ts

Signature​

function validateValues(
  values: unknown,
  options: { model?: z.ZodType; schema?: Record<string, unknown> } = {},
): ValidationResult {}

Interface: ArtifactValidationResult​

Canonical path: softschema.ArtifactValidationResult

Declared in: packages/typescript/src/validate.ts

Signature​

interface ArtifactValidationResult {
  readonly ok: boolean;
  contract: Record<string, unknown>;
  contract_id: string;
  document_metadata: Record<string, unknown> | null;
  outcome: "valid" | "invalid" | "input_error";
  path: string;
  profile: string;
  semantic: SemanticResult;
  status: string;
  structural: StructuralResult;
  values: Record<string, unknown> | null;
  warnings: SchemaWarning[];
}

Interface: CompileOptions​

Canonical path: softschema.CompileOptions

Declared in: packages/typescript/src/compile.ts

Signature​

interface CompileOptions {
  contractId: string;
  schemaId?: string;
  checkOnly?: boolean;
}

Interface: CompileResult​

Canonical path: softschema.CompileResult

Declared in: packages/typescript/src/compile.ts

Signature​

interface CompileResult {
  outPath: string;
  schemaYaml: string;
  drift: boolean;
  driftDiff: string | null;
  schemaSha256: string;
}

Interface: Contract​

Canonical path: softschema.Contract

Declared in: packages/typescript/src/models.ts

Signature​

interface Contract {
  id: string;
  /** A label for the semantic model (e.g. a Zod module spec), or null when schema-only. */
  model: string | null;
  envelopeKey: string | null;
  status: SchemaStatus;
  profile: SchemaProfile;
  schemaPath: string | null;
}

Interface: FieldInfo​

Canonical path: softschema.FieldInfo

Declared in: packages/typescript/src/schemaView.ts

Signature​

interface FieldInfo {
  /** JSON Pointer (RFC 6901) relative to the root schema document. */
  pointer: string;
  name: string;
  jsonType: string | null;
  enum: string[] | null;
  required: boolean;
  description: string | null;
  /** The field's per-property `x-softschema` block (empty when unannotated). */
  softmeta: Record<string, unknown>;
}

Interface: GeneratedSection​

Canonical path: softschema.GeneratedSection

Declared in: packages/typescript/src/generate.ts

Signature​

interface GeneratedSection {
  start: number;
  end: number;
  attrs: Record<string, string>;
  existingContent: string;
}

Interface: RegenerateResult​

Canonical path: softschema.RegenerateResult

Declared in: packages/typescript/src/generate.ts

Signature​

interface RegenerateResult {
  path: string;
  sections: number;
  drift: boolean;
  driftDetails: string[];
}

Interface: SchemaMetadata​

Canonical path: softschema.SchemaMetadata

Declared in: packages/typescript/src/models.ts

Signature​

interface SchemaMetadata {
  contractId: string;
  schema: string | null;
  envelope: string | null;
  status: SchemaStatus | null;
}

Interface: SchemaWarning​

Canonical path: softschema.SchemaWarning

Declared in: packages/typescript/src/models.ts

Signature​

interface SchemaWarning {
  code: WarningCode;
  message: string;
  severity: "info" | "warning";
}

Interface: SemanticResult​

Canonical path: softschema.SemanticResult

Declared in: packages/typescript/src/validate.ts

Signature​

interface SemanticResult {
  ok: boolean;
  errors: Record<string, unknown>[];
  skipped_reason: string | null;
}

Interface: SoftFieldOptions​

Canonical path: softschema.SoftFieldOptions

Declared in: packages/typescript/src/softField.ts

Signature​

interface SoftFieldOptions {
  description: string;
  group: string;
  owner?: SoftOwner;
  tier?: SoftTier;
  order?: number;
  instruction?: string;
  examples?: unknown[];
  aliases?: Record<string, string[]>;
  repair?: RepairKind;
}

Interface: StructuralResult​

Canonical path: softschema.StructuralResult

Declared in: packages/typescript/src/validate.ts

Signature​

interface StructuralResult {
  ok: boolean;
  errors: (StructuralErrorRecord | Record<string, unknown>)[];
  engine: string;
  skipped_reason: string | null;
}

Interface: ValidationResult​

Canonical path: softschema.ValidationResult

Declared in: packages/typescript/src/validate.ts

Signature​

interface ValidationResult {
  structural: StructuralResult;
  semantic: SemanticResult;
}

Method: all​

Canonical path: softschema.Contracts.all

Declared in: packages/typescript/src/registry.ts

Signature​

get all(): Record<string, Contract> {}

Method: register​

Canonical path: softschema.Contracts.register

Declared in: packages/typescript/src/registry.ts

Signature​

register(contract: Contract): void {}

Method: resolve​

Canonical path: softschema.Contracts.resolve

Declared in: packages/typescript/src/registry.ts

Signature​

resolve(contractId: string): Contract | null {}

Method: contractId​

Canonical path: softschema.SchemaView.contractId

Declared in: packages/typescript/src/schemaView.ts

Signature​

get contractId(): string | null {}

Method: enumValues​

Canonical path: softschema.SchemaView.enumValues

Declared in: packages/typescript/src/schemaView.ts

Signature​

enumValues(pointer: string): string[] | null {}

Method: field​

Canonical path: softschema.SchemaView.field

Declared in: packages/typescript/src/schemaView.ts

Signature​

field(pointer: string): FieldInfo {}

Method: fieldsByGroup​

Canonical path: softschema.SchemaView.fieldsByGroup

Declared in: packages/typescript/src/schemaView.ts

Signature​

fieldsByGroup(group: string): FieldInfo[] {}

Method: fieldsByOwner​

Canonical path: softschema.SchemaView.fieldsByOwner

Declared in: packages/typescript/src/schemaView.ts

Signature​

fieldsByOwner(owner: string): FieldInfo[] {}

Method: fieldsByTier​

Canonical path: softschema.SchemaView.fieldsByTier

Declared in: packages/typescript/src/schemaView.ts

Signature​

fieldsByTier(tier: string): FieldInfo[] {}

Method: iterFields​

Canonical path: softschema.SchemaView.iterFields

Declared in: packages/typescript/src/schemaView.ts

Signature​

iterFields(includeRefs = true): FieldInfo[] {}

Method: load​

Canonical path: softschema.SchemaView.load

Declared in: packages/typescript/src/schemaView.ts

Signature​

static load(schemaPath: string): SchemaView {}

Method: raw​

Canonical path: softschema.SchemaView.raw

Declared in: packages/typescript/src/schemaView.ts

Signature​

get raw(): SchemaNode {}

Method: rootSoftmeta​

Canonical path: softschema.SchemaView.rootSoftmeta

Declared in: packages/typescript/src/schemaView.ts

Signature​

get rootSoftmeta(): Record<string, unknown> {}

Method: schemaId​

Canonical path: softschema.SchemaView.schemaId

Declared in: packages/typescript/src/schemaView.ts

Signature​

get schemaId(): string | null {}

Method: schemaSha256​

Canonical path: softschema.SchemaView.schemaSha256

Declared in: packages/typescript/src/schemaView.ts

Signature​

get schemaSha256(): string | null {}

Method: softmeta​

Canonical path: softschema.SchemaView.softmeta

Declared in: packages/typescript/src/schemaView.ts

Signature​

softmeta(pointer: string): Record<string, unknown> {}

Type Alias: RepairKind​

Canonical path: softschema.RepairKind

Declared in: packages/typescript/src/softField.ts

Signature​

type RepairKind = "none" | "safe_coerce" | "suggest_alias";

Type Alias: SchemaProfile​

Canonical path: softschema.SchemaProfile

Declared in: packages/typescript/src/models.ts

Signature​

type SchemaProfile = "frontmatter-md" | "pure-yaml";

Type Alias: SchemaStatus​

Canonical path: softschema.SchemaStatus

Declared in: packages/typescript/src/models.ts

Signature​

type SchemaStatus = "soft" | "permissive" | "enforced";

Type Alias: SoftOwner​

Canonical path: softschema.SoftOwner

Declared in: packages/typescript/src/softField.ts

Signature​

type SoftOwner = "agent" | "postprocess" | "system" | "human";

Type Alias: SoftTier​

Canonical path: softschema.SoftTier

Declared in: packages/typescript/src/softField.ts

Signature​

type SoftTier = "hard_fact" | "constrained" | "narrative";

Type Alias: WarningCode​

Canonical path: softschema.WarningCode

Declared in: packages/typescript/src/models.ts

Signature​

type WarningCode = "document-contract-mismatch" | "document-status-mismatch";