flowgraph/docs/architecture/decisions/004-no-schema-version.md

ADR-004: No Schema Version Field in Serialized Format

Status

Accepted

Context

Flowgraph's FlowGraphSerialized type follows graphology's native JSON format. The format does not include a schemaVersion field. This decision affects:

1. Backward compatibility — how consumers handle format changes across versions
2. Persistence — whether stored graphs can be reliably migrated
3. Interoperability — whether different versions of flowgraph can exchange data

The review (001-architecture-gap-analysis.md, W-07) flagged this as a potential gap: "Consumers that need persistence wrap it in their own versioned envelope."

Decision

Flowgraph's serialized format will NOT include a schemaVersion field. This follows the same pattern as taskgraph. Consumers that need versioned persistence must wrap the serialized format in their own envelope that includes version metadata.

Rationale

1. Graphology format is upstream — the serialized format is graphology's native JSON format. Adding a schemaVersion field modifies a format we don't own. This creates a fork between what graphology produces and what flowgraph expects.

2. Flowgraph is not a persistence layer — the library handles in-memory graph construction, validation, and analysis. Persistence is explicitly the consumer's responsibility (see ADR-003). Adding versioning to the serialized format would blur this boundary.

3. Versioning belongs at the envelope level — a consumer storing graphs in Postgres should wrap the serialized data in a versioned envelope: { version: 1, data: FlowGraphSerialized, metadata: {...} }. This gives the consumer full control over migration logic, which they need anyway for their own schema migrations.

4. Breaking changes are breaking changes — if the serialized format changes incompatibly, no version field will help. The consumer must handle the migration. A version field would give false confidence that "old versions can be read" when in practice the consumer must write migration code.

5. Taskgraph precedent — taskgraph uses the same approach and it has worked well. The pattern is established in the ecosystem.

Consequences

• Positive: Simpler serialized format, no dependency on version parsing, no false confidence in backward compatibility.
• Positive: Clean separation of concerns — flowgraph handles graph operations, consumers handle persistence and versioning.
• Negative: Consumers must implement their own versioned envelope if they persist graphs. This is a small burden documented in the consumer integration guide.
• Negative: There's no standard way for two different flowgraph versions to detect incompatibility. The consumer must track this themselves.

Mitigation

The consumer integration guide documents the recommended pattern:

// Consumer-side versioned envelope
interface PersistedGraph {
  version: number;         // Increment on breaking changes
  data: FlowGraphSerialized;  // Raw graphology format
  metadata: {
    createdAt: string;
    graphType: "operation" | "call";
    flowgraphVersion: string;  // The npm package version for reference
  };
}

When restoring a graph, the consumer checks version and flowgraphVersion to decide whether migration is needed. This is outside flowgraph's responsibility.

References

• Schema: schema.md — FlowGraphSerialized, SerializedGraph factory
• Storage decoupled ADR: 003-storage-decoupled.md
• Consumer integration: consumer-integration.md
• Review: 001-architecture-gap-analysis.md — W-07