Internal Architecture

This guide targets library authors and advanced users who want to understand how Valibot works under the hood. It covers the internal object model — schemas, actions, datasets, issues, and config — and how they fit together in the pipeline execution engine.

Valibot is built around a simple modularity principle: every schema and action is an independent, interchangeable building block. Like Lego bricks, they each expose a standard connector — a shared interface contract — and can be freely combined, nested, and replaced without any central registry or shared state. Valibot's built-in schemas and actions follow the exact same rules as any custom ones you write yourself, which means the library can be extended or partially replaced without special privileges.

This design is backed by a concrete technical choice: Every schema and action is a plain object literal returned by a pure factory function. There are no classes, no prototypes beyond Object, and no shared mutable state. Because each factory is a pure function with no side effects, it is annotated with // @__NO_SIDE_EFFECTS__, which allows bundlers to eliminate every unused schema and action from the final bundle.

Schemas

Schemas are the starting point for using Valibot. They validate a specific data type, like a string, object, or date, and can be reused or nested to reflect more complex data structures. Every schema is a plain object that satisfies BaseSchema:

Validation logic beyond the base type check lives in a pipe array added by the pipe method and some schemas expose additional schema-specific properties. See Runtime properties for a full breakdown.

Any object that satisfies the BaseSchema interface is a valid schema — whether it comes from Valibot's built-ins, a third-party package, or your own code. The guide Extend Valibot walks through building one from scratch.

Actions

Actions come in three kinds. The first and probably most important one are validation actions. They check an already-typed value and may add issues. Every validation action is a plain object that satisfies BaseValidation:

The second one are transformation actions. They convert the value to a new type and/or value. Every transformation action is a plain object that satisfies BaseTransformation:

The third one are metadata actions. They carry static annotations and are always skipped during pipeline execution. Every metadata action is a plain object that satisfies BaseMetadata:

Just like schemas, any object that satisfies one of these action interfaces is a valid action that can be dropped into any pipeline.

Datasets

A dataset is the container that carries a value through the validation pipeline. It is passed to each '~run' method in sequence, and as the pipeline executes, the dataset's typed flag and issues array are updated to reflect the current state of validation.

Datasets are mutable by design for performance reasons. '~run' implementations modify dataset.value and dataset.typed in place rather than returning new objects.

Issues

When a schema or validation action finds a problem with the input, it adds an issue to the dataset. Every issue is a plain object that satisfies BaseIssue:

BaseIssue also extends Config, so the lang, message, abortEarly, and abortPipeEarly fields from the parse config are carried into the issue object as well.

Config

Every '~run' call receives a config object alongside the dataset. It controls language selection, custom error messages, and early-abort behavior. The Config interface has four fields:

Pipe execution

The pipe method is the universal connector between all building blocks. It returns a new schema object that spreads all properties of the root schema and adds a pipe property — a tuple with the root schema at index 0 and additional pipe items at index 1+.

Pipe items can be validation actions, transformation actions, metadata actions, or even other schemas. The '~run' method is replaced with a new implementation that iterates all items in the tuple.

pipe itself has no knowledge of any specific schema or action. It only depends on the shared interface contracts (kind and '~run'), which is what makes the entire system composable:

function pipe(...pipe) {
  return {
    // Spread all properties of the root schema
    ...pipe[0],
    // Add the pipe tuple (root schema at index 0, other pipe items at index 1+)
    pipe,
    // Replace '~standard' with a lazy getter so that `this` refers to the new schema object
    get '~standard'() {
      return _getStandardProps(this);
    },
    // Replace '~run' with a new implementation that executes the pipeline
    '~run'(dataset, config) {
      for (const item of pipe) {
        // Metadata actions are never executed
        if (item.kind !== 'metadata') {
          // Schemas and transformations abort if the dataset already has issues
          if (
            dataset.issues &&
            (item.kind === 'schema' || item.kind === 'transformation')
          ) {
            dataset.typed = false;
            break;
          }

          // Run pipe item unless an early abort is configured
          if (
            !dataset.issues ||
            (!config.abortEarly && !config.abortPipeEarly)
          ) {
            dataset = item['~run'](dataset, config);
          }
        }
      }
      return dataset;
    },
  };
}

The following rules apply during pipe execution:

• Metadata items are always skipped.
• Schemas and transformations abort if the dataset already has issues.
• Validations continue across existing issues unless abortEarly or abortPipeEarly is configured.

Because the result of pipe is itself a BaseSchema, it can be nested inside other schemas or passed to pipe again just like any other schema.

Immutability

We treat all schema and action objects as immutable. Mutating them directly after creation leads to unpredictable behavior, especially when schemas are shared across multiple pipelines or modules.

When we need a modified copy of a schema, we spread it into a new object and replace only the properties we want to change. Here is a simplified version of our fallback method to demonstrate this pattern:

function fallback(schema, fallbackValue) {
  return {
    // Copy all properties from the original schema
    ...schema,
    // Add the new fallback property as metadata
    fallback: fallbackValue,
    // Re-bind '~standard' so `this` refers to the new object
    get '~standard'() {
      return _getStandardProps(this);
    },
    // Override '~run' to return the fallback value on failure
    '~run'(dataset, config) {
      const outputDataset = schema['~run'](dataset, config);
      return outputDataset.issues
        ? { typed: true, value: fallbackValue }
        : outputDataset;
    },
  };
}

Two things are important when creating a modified copy. First, always re-bind the '~standard' getter so that this inside it refers to the new object instead of the original. Second, capture the original schema in a closure rather than reading this in '~run', so the original '~run' logic is called correctly.

If you want to create an entirely new schema or action from scratch rather than wrapping an existing one, see the Extend Valibot guide.