Seed format reference

A seed is a JSON file containing a world's starting data and logical time. Reuse a seed to run the same test from the same starting point.

Create starting data from a template or import in the dashboard, or write a seed file directly. Validate a file before using it:

worlds seed validate my-seed.json

Choose the connector profile

Native Zendesk and the legacy desk cannot coexist in one seed. Stripe's implemented subset has real-API verification; native Zendesk has local conformance coverage, with live qualification pending. See connector scope.

Top level

This is a valid empty starting world:

{
  "name": "my-seed",
  "version": 1,
  "epoch": 1767225600,
  "clock_mode": "manual",
  "data": {}
}

With a manual clock, time moves through worlds clock advance or the admin API. Auto mode also advances by auto_tick_seconds on eligible API requests. Authentication, injected failures and preflight refusals do not tick; see logical clock behavior.

Loading a seed emits no events or webhooks. The world records the parsed seed's canonical-JSON SHA-256 as seed_hash; generated record IDs derive from that hash and world counters. See determinism.

Native Zendesk records

The zendesk object contains version: 1, principal_id and arrays for users, groups, organizations, memberships, tickets, comments and audits. Start from the bundled zendesk-support-v1 example in the dashboard, or an offline import. To inspect the bundled JSON, use GET /admin/seeds/zendesk-support-v1 on your local server; see the Admin API.

Native IDs and references are positive safe integers. The principal must be an active, nonsuspended agent or admin. Directory membership, assignment, comments and audit history are validated together; copying ticket rows alone is not sufficient.

In the beta.4 candidate and current source checkout, native timestamp chronology uses the full accepted ISO instant, including fractional digits beyond milliseconds and equivalent timezone spellings. The frozen published 0.9.0-beta.3 and published beta.1/beta.2 archives predate this validation fix and compare native seed timestamps at millisecond precision. Supplied creation and update times must be at or before the epoch; update must not precede creation. Omitted creation defaults to the epoch and omitted update to creation. A comment and its owning audit must have equal instants. Original timestamp strings survive export and reload.

The native scope documents supported behavior. Source checkouts also include the complete native seed schema for contributors.

Stripe records

Stripe seed records use explicit prefixed IDs: cus_, prod_, price_, in_, ch_ and sub_. References must point to records in the same seed.

Amounts are integer cents. Where supported, created_offset is a nonnegative number of seconds before the epoch; a larger value means an older record.

"recurring": { "interval": "month", "interval_count": 1 }

{
  "id": "in_example",
  "customer": "cus_example",
  "status": "paid",
  "currency": "usd",
  "lines": [
    { "description": "Monthly plan", "amount": 4000, "quantity": 1 }
  ],
  "charges": [
    { "id": "ch_example", "amount": 4000 }
  ]
}

{
  "id": "sub_example",
  "customer": "cus_example",
  "price": "price_monthly",
  "quantity": 1,
  "current_period_start": 1766361600,
  "current_period_end": 1769040000,
  "cancel_at_period_end": false
}

Legacy ticket records

data.tickets[] serves the demo-grade, Zendesk-shaped desk. It is separate from native Zendesk. IDs are assigned in file order as "1", "2" and so on.

Referential integrity

Validation rejects unknown fields, duplicate IDs, missing references and inconsistent history. Errors name the JSON path to fix.

For Stripe, it also rejects charges on unpaid invoices, over-refunded charges, subscriptions on one-time prices and inverted periods. For native Zendesk, it checks directory relationships, principal authority, comment/audit links and lifecycle metadata.

Imported native IDs set allocator floors so runtime-created records cannot reuse them. Native wire IDs are numeric; admin state keys remain strings.

Import a Stripe account

Provide a restricted read-only key through STRIPE_API_KEY, then run:

worlds seed import --from-stripe --name my-account --manifest worlds/my-account.manifest.json

The importer reads supported account records and writes a validated seed. By default it samples up to 100 objects per resource and writes seeds/my-account.json, or the directory set by WORLDS_SEEDS_DIR.

This is pseudonymization, not anonymity. Amounts and timing can still identify an account. Product and price IDs remain verbatim, including merchant-chosen text. Review the manifest before sharing an imported seed.

The same source state and options produce identical files. The default epoch comes from the newest source creation timestamp, rounded up to UTC midnight.

Offline native Zendesk import

worlds seed import --from-zendesk --input support-export.json --name my-support

This CLI accepts a complete native seed or the explicit worlds-zendesk-native-export format below. It does not fetch a live Zendesk account or accept arbitrary vendor exports. The dashboard offers guided data preparation, including supported offline Zendesk Full JSON conversion.

The import remaps identities, replaces supported identifying text and preserves valid relationships, privacy, timestamps and audit history. Attachments and unsupported fields are omitted and counted. Review the generated manifest.

Defaults are seeds/my-support.json and worlds/my-support.manifest.json. An optional --identity-map is private. See native import workflows for destination rules and composition with Stripe.

Save a world's current state as a seed

In the dashboard, choose Save as starting setup from an eligible world. From the CLI:

worlds world export w_abc123def456 --name my-fork

The admin equivalent is GET /admin/worlds/:id/export-seed?name=my-fork. Use the result to start another test from the state your agent produced.

The export uses the world's current logical clock as its epoch and validates as a seed. Its lossy report lists state the seed format cannot retain:

Native Zendesk export keeps supported directory records, tickets, comments, full audit history and lifecycle metadata. Stripe and legacy record offsets remain relative to the new epoch.

Exporting and reloading represents settled state, not a replay of the run. Re-exporting that loaded world preserves the same data block.

Library seeds

Bundled seeds are synthetic fixtures. See the generated seed catalog for their builders and starter packs for ready-made tasks.