Schema Versions

The YAML schema field identifies which version of the format a file uses. This allows the tool to detect incompatible files, provide clear upgrade messages, and evolve the format over time.

How It Works

Every exported YAML file includes a schema field as the first line:

schema: nebula
name: My Flow

Behavior:

• Export — always writes the current schema version
• Create / Update — reads the schema field; if missing, assumes the current version
• Validate — checks that the schema name is recognized; unknown schemas produce a clear error
• Unknown schema — if a file uses a schema version newer than your tool supports, you'll see: unknown schema version "xyz"; upgrade letitflow-sn

Naming Convention

Schema versions use celestial codenames — short, memorable names drawn from astronomy. The codename is what appears in YAML files and documentation.

Each version also has an internal date for ordering (not shown to users).

Version History

Version	Date	Description
nebula	2026-02-25	Initial versioned schema. Baseline format covering flows, subflows, triggers, all step types, variables, stages, and pill references.

Backward Compatibility

Files without a schema field are treated as nebula (the initial version). This means existing YAML files created before schema versioning was introduced will continue to work without modification.

Adding New Versions

When the YAML format changes in a breaking way, a new schema version is added to the registry with a new codename. The tool can then:

1. Detect old-format files and provide migration guidance
2. Reject files from newer versions with a clear "upgrade" message
3. Support multiple versions simultaneously if needed