Resource grammar

Tapstate resources are YAML files named *.tap.yml. Each file contains one version: tapstate/v1 resource.

Use the Schema and connector catalog bundled with the same tapstate version as your CLI. This site does not yet publish a stable, versioned Schema URL.

Workspace layout

The canonical workspace layout groups files by resource kind:

tap-work/
├── source/
├── pipeline/
├── transform/
├── view/
└── serve/

tapstate new writes <workspace>/<kind>/<id>.tap.yml. tapstate validate accepts a workspace directory or one resource file.

Resource kinds

Kind	Declares
`source`	A connector connection. A read source includes `mode`; a target connection omits it.
`pipeline`	Source references, ordered transform steps, and optional view and serve surfaces. A declared view materializes to managed state; serve delivers externally.
`transform`	Reusable transform logic without input wiring.
`view`	Reusable materialization settings without input wiring.
`serve`	Reusable `sync`, `query`, and `push` declarations without input wiring.

A string reference resolves by resource ID. Top-level IDs must be unique in the workspace and cannot contain ..

Minimal runnable shape

The released preview path uses MySQL and PostgreSQL source connections and one pipeline:

source/orders.tap.yml

version: tapstate/v1
kind: source
id: orders
connector: mysql
mode: cdc
config:
  host: mysql
  port: "3306"
  database: appdb
  username: ${MYSQL_USER}
  password: ${MYSQL_PASSWORD}
tables: [orders]

source/shipments.tap.yml

version: tapstate/v1
kind: source
id: shipments
connector: postgres
mode: cdc
config:
  host: postgres
  port: "5432"
  database: appdb
  schema: public
  user: ${POSTGRES_USER}
  password: ${POSTGRES_PASSWORD}
tables: [shipments]

pipeline/orders-sync.tap.yml

version: tapstate/v1
kind: pipeline
id: orders-sync
source: [orders, shipments]
settings:
  read_mode: snapshot_and_cdc
transforms:
  - id: order-document
    type: nest
    from:
      order: orders
      shipment: shipments
    root:
      from: order
      key: [id]
      embed:
        - from: shipment
          on:
            order_id: id
          as: array
          path: shipments
          arrayKey: [id]
view:
  id: order_state
  from: order-document
  primary_key: id

Apply the source connections first, run discover-schema for each source, then apply the complete workspace and start the pipeline. Add expressions that read after.<field> or before.<field> only after discovery has supplied the field types used during server-side validation.

For the complete field shapes, see source, pipeline, transforms, and view and serve.

Declaration and execution are different checks

The v1 Schema describes what can be declared. The current preview runtime executes a smaller subset. A pipeline may declare a view, a serve surface, or both; a view-only pipeline still materializes records and does not need serve.

Surface	Schema/validator	Current preview runtime
Resource kinds	`source`, `pipeline`, `transform`, `view`, `serve`	The Quickstart declares `source` + `pipeline` with an inline `view`.
Transforms	`filter`, `map`, `js`, `union`, `nest`, `join`	`filter`, `map`, `js`, `union`, and `nest` are wired. The runtime refuses `join`.
Serve declarations	`sync`, `query`, `push`	`serve.sync` delivers to an external target; the Quickstart's managed view does not need a `serve` block. Do not infer an executable runtime surface from Schema acceptance alone.
Connector fields	Connector-specific keys are allowed structurally; known catalog fields can receive additional checks.	A catalog entry does not prove that a connector artifact is installed, registered, or available in the current release.

Validation model

Offline validation checks:

YAML and Schema structure;
cross-file ID and reference closure;
rules exposed by the bundled connector catalog.

Validation does not connect to an external system, verify credentials or network access, install a connector artifact, or prove that a Schema-declared feature is executable by the current runtime. Unknown connector-specific config keys can pass the current offline validator, so test the real connector path before relying on a configuration.

Quote regular-expression table selectors

Quote a table-selector regex when it contains YAML flow indicators such as ? or :. This includes negative lookahead expressions:

tables:
  - "/^(?!timezone_test$).*/"

The equivalent flow form is tables: ["/^(?!timezone_test$).*/"]. Keeping the regex quoted preserves it as one string and ensures that canonical YAML returned by tapstate remains parseable. Do not rely on an unquoted scalar for these patterns, even if a YAML parser happens to accept the input form.

Compatibility rules

Unknown top-level fields are rejected.
Connector-owned config, options, and experimental maps can accept extension fields.
experimental fields do not carry the v1 compatibility guarantee.
Use the Schema and catalog from the same release as the runtime you deploy.

To explore a running example, run the Quickstart. For connector metadata and external-system preparation, use the connector directory.