How does MAGI handle versioning of ai-script instructions?

[aquilesswick73]

I'm integrating MAGI into our document pipeline and wondering about forward compatibility. If the ai-script schema evolves (e.g., new fields are added or provider values change), how should we handle versioning?

For example, if I write an ai-script block targeting gpt-4o today and the model gets deprecated, does MAGI have a recommended fallback pattern? Or is there a version field planned for the ai-script schema itself?

[jenalysematejek42]

We had the same concern at my previous team. What we ended up doing was treating the provider and model-name fields as hints rather than hard requirements. The processing layer would map them to whatever was currently available.

Would love to see MAGI add an optional model-fallback array field in the spec.

[aquilesswick73]

Both good approaches. I think the hint-based approach makes the most sense for MAGI since the format is designed to be durable. Having the processor resolve model availability at runtime keeps the .mda files from going stale.

@adoniyahbobay26 the model-fallback array idea is solid - maybe worth opening as a feature request?

[deara-builds]

This is a great question — I've been thinking about this too for a project where we're iterating on prompts frequently.

One approach I've been considering is adding a version field to the ai-script JSON block:

{
  "script-id": "summarizer-v2",
  "version": "2.1.0",
  "prompt": "..."
}

Then the processing pipeline could maintain a mapping of script-id → latest supported version. This way you could deprecate old instruction formats gracefully.

Does the spec have any plans for a formal versioning mechanism, or is this something the community should propose?

[junipervandenberg27]

Curious if there's tooling in the works for mda lint --check-script-version — that's the missing CI piece for us.

[merrittunderwood99]

We treat ai-script semver as a hard contract — minor bumps are additive, majors require explicit migration. Same approach as protobuf has worked for years.