Versions and references

A decision schema lives in a registry, the same place your prompts live, and is versioned the same way. Your code never sends the schema itself: it sends a reference to a published version, and the gateway looks it up.

Drafts and published versions

• A draft is the version you are editing. It is saved as you work, you can have several open at once, and no call from your code can reach it by reference.
• A published version is read-only, for good. It has a version number in the form major.minor.patch and a fingerprint of its content. To change it, choose Draft New Version, edit the draft and publish it as a new version.
• Draft New Version suggests the next free patch number, refuses one that is already a draft or published, and lists the schema's open drafts so you can continue one instead.
• Publishing exactly the content of an existing version under the same name does not create a new one: you get the existing version back.
• Compare (in the version list or a schema's menu) shows what changed between two versions: the instructions with changed lines marked, and a summary of the kind, options added, removed or renamed, inputs and scale.

References

A reference has the form registry/name, with an optional @version after it.

You may put your organization's slug in front (acme/support/duplicate-charge@1.2.0); it has to be your own organization.

Which one to use

• Pin an exact version in production. The decision your code gets then changes only when you change the reference, and you can roll back by changing it back.
• Use a range when you want improvements to arrive on their own, and you trust whoever publishes. A range moves to a new matching version the moment it is published.
• latest follows every publish, including a change of kind or of options. It suits experiments, not code that acts on the answer.

Every answer says exactly what ran: schema.ref, schema.version and schema.contentHash. The same fields are in the decision log, so a change in behavior can be traced to the version that caused it. The statistics show, for each version, how often each decision came out.

Names and access

• A decision schema and a prompt cannot share a name in a registry. Publishing one under the other's name is refused with 409, which names the type of the one that holds it.
• A private registry needs access: a signed-in person needs a grant on it, and an API key needs to belong to the same organization. A public registry can be read by anyone.
• A registry, name or version that does not exist is 404. A private registry you may not read is 403 whatever name you try, so guessing names tells you nothing about what it holds.