@sonata-innovations/fiber-types

TypeScript types and JSON Schema for Fiber — a system for building and rendering data-collection forms.

This package defines the two contracts every other Fiber package speaks:

• Flow — the JSON document a builder produces and the render engine consumes
• FlowData — the collected responses the render engine hands back

It has no runtime dependencies and is the foundation of the Fiber dependency graph, which makes it the canonical home for the schema documentation.

Install

npm install @sonata-innovations/fiber-types

Most consumers get this package transitively — it is a dependency of fiber-fbre, fiber-fbt, fiber-fbtl, and fiber-shared. Install it directly when you generate or inspect Flow JSON without rendering it.

Documentation

Full docs ship inside this package under docs/, so they always match the version you installed. Start with AGENTS.md at the package root, or read them online at github.com/sonata-innovations/fiber-docs.

| Document | What it covers | |---|---| | docs/fiber-concepts.md | The Flow/Screen/Component model, Flow vs FlowData | | docs/schema/flow-quick-reference.md | Compact reference: 30 component types and their value shapes, conditions, validation, widths, markup | | docs/schema/flow-schema.md | Exhaustive per-property reference | | docs/schema/flow-schema.json | Machine-validatable JSON Schema (draft 2020-12) for a Flow | | docs/schema/flow-data-schema.md | The shape of the data the render engine returns | | docs/schema/flow-data-schema.json | Machine-validatable JSON Schema for FlowData |

Validate a Flow

The JSON Schema is the enforceable contract. Validate anything you generate rather than trusting it by inspection:

npx ajv-cli validate --spec=draft2020 \
  -s node_modules/@sonata-innovations/fiber-types/docs/schema/flow-schema.json \
  -d my-flow.json

What's exported

import type {
  Flow, FlowScreen, Component, ComponentProperties,
  FlowMetadata, FlowConfiguration, ThemeConfig, NavigationConfig,
  ControlsConfig, ConfirmationConfig,
  FlowData, ScreenData, ComponentData, CalculationData,
  FileUploadData, RangeValue,
  FlowConditionConfig, ConditionRule, ConditionOperator,
  FlowValidationConfig, ValidationRule,
  PresetData, TemplateData,
  ComponentType, ComponentOfType, ComponentPropertiesByType,
} from "@sonata-innovations/fiber-types";

import {
  generateUUID,
  regenerateComponentUUIDs,
  regenerateFlowUUIDs,
  normalizeConditionalOrder,
  getValidationConfig,
  getComponentDisplayLabel,
  COMPONENT_VARIANT_TYPES,
} from "@sonata-innovations/fiber-types";

Component is a discriminated union keyed on type — narrow on component.type and component.properties narrows with it:

if (component.type === "inputText") {
  component.properties.placeholder; // typed, no cast
}

Gotchas

• 30 component types. Display types (header, text, divider, callout, table) never appear in FlowData; computed does.
• pattern validation rules take params.regex, not params.pattern. A pattern key is silently ignored and the rule always passes.
• Options must be { label, value } objects, not bare strings. value may be a string or a number.
• Option-bearing components do not default to their first option. The initial value is null unless properties.defaultValue matches an option's value.
• Never set runtime-only fields (value, valid, addedComponents) in Flow JSON.
• AI-generated flows should be passed through normalizeConditionalOrder(flow) before being loaded into FBTL. It reorders conditionals to follow their triggers — a pure structural reorder, idempotent, and it never rewrites a condition, property, uuid, or label.

Companion packages

| Package | What it is | |---|---| | @sonata-innovations/fiber-fbre | Render engine — renders a Flow, returns FlowData | | @sonata-innovations/fiber-fbt | Full drag-and-drop builder | | @sonata-innovations/fiber-fbtl | Lite builder for non-technical end users | | @sonata-innovations/fiber-shared | Condition, validation, markup, and formula engines | | @sonata-innovations/fiber-theme-editor | Visual theme editor widget |

License

MIT