speakeasy-api Updating Artifact Schemas
- Inspect every reader, writer, strict parser, test, and historical shape before editing.
- For hand-written artifacts, prefer ordered, shape-driven, idempotent migrations without a required version key. Use explicit versions only when shapes cannot be distinguished safely.
- Parse into a generic representation, run all migrations in order, then strictly deserialize the latest shape.
- Add one migration per schema change; never rewrite an older migration. Preserve the new value when old and new fields coexist.
- Make every writer emit only the latest shape. Do not rewrite user-owned files on read unless explicitly required.
- Test legacy and current shapes, mixed-key conflicts, malformed values, and writer output.
- Follow repository release rules, then run the smallest relevant format, test, and lint checks.