AI-assisted spec editing
Describe a change in plain language and Elva returns a precise, reviewable edit you can preview as a diff before it ever touches your spec. This is a Monaco-based OpenAPI editor with an AI composer that speaks JSON Patch, so every suggestion is surgical, not a wholesale rewrite.
Edit by describing, not hand-typing
The composer takes an instruction like “add an email field to the User schema” and returns an RFC-6902 JSON Patch proposal. Elva parses the patch, validates it, and applies it against a copy of your document, so a bad suggestion can never silently corrupt the spec. Under the hood the composer runs applyJsonPatch with validation on and mutation off: the patch is checked with fast-json-patch first, then applied to produce new YAML only if it holds.
Because edits are expressed as discrete operations (add, remove, replace), they are additive and targeted. The composer adds a property to a schema, appends to a required array, or inserts a single operation. It does not blindly replace whole objects, so your descriptions, examples, and unrelated fields stay intact.
Every proposal is a preview first. Nothing is written to your spec until you press Accept all. Reject and the document is untouched.
From prompt to applied patch
1
Describe the change
Open the composer in the editor and type what you want in plain language, for example "add a cursor pagination parameter to GET /orders". The composer sends your instruction to Elva's model proxy along with the relevant slices of your spec.
2
Preview the diff
Elva returns a patch proposal card summarizing each change (+ add, ~ update, - remove) with a count of changes in your file. Expand any row with View changes to inspect the exact content that will be added, updated, or removed, rendered as a syntax-highlighted diff.
3
Apply or discard
Press Accept all to apply the patch. The editor updates, the card flips to Changes Applied, and Elva jumps you to the first changed line. Press Reject all to discard the proposal with zero side effects.
A returned patch is just a JSON array of operations. Here is the shape the composer works with:
[
{
"op": "add",
"path": "/components/schemas/User/properties/email",
"value": { "type": "string", "format": "email" }
},
{
"op": "add",
"path": "/components/schemas/User/required/-",
"value": "email"
}
]
Notice the second operation appends to the required array with /- instead of overwriting it. That is the additive discipline in action: the new field is added and marked required without disturbing the fields already there.
Live linting with a Fix with AI shortcut
As you type, Elva lints your spec with Spectral against the recommended OpenAPI ruleset and surfaces issues inline in the editor. Each finding carries a severity: error, warning, info, or hint.
Every issue comes with a Fix with AI quick-fix. Trigger it and Elva drafts the composer prompt for you from the marker, seeding the composer with the exact rule, message, and location so you can turn a lint failure into an applied patch in one move.
Validation runs off the main thread in a Web Worker so the editor stays responsive. For large or heavy specs it transparently offloads to the backend instead of blocking your browser.
Condition | What happens |
Spec under ~250,000 characters, fast device | Linted locally in the worker |
Spec over ~250,000 characters | Offloaded to the backend linting endpoint |
Previous run took over 800 ms | Offloaded to the backend on the next run |
Fewer than 4 CPU cores detected | Offloaded to the backend |
Backend unreachable | Falls back to local Spectral automatically |
Choose your model provider
Composer and Fix-with-AI calls route through Elva’s multi-provider model proxy. You pick who runs the model, and you can bring your own key or lean on Elva’s shared quota.
Route composer requests to OpenAI models through the proxy. Provide your own OpenAI key in AI Model Settings, or leave it blank to use Elva's configured key where available.
Use Claude models for spec edits. Supply your own Anthropic key to run on your own quota and billing.
Run edits on Gemini models. Elva offers a shared Gemini quota so you can try the composer without a key, and you can switch to your own key any time.
Shared quota or your own key. Choose Use Elva's API key to start instantly on shared quota, or Use my API key to run on your own provider account. Custom keys are stored encrypted behind a session passphrase, never in plain text.
Details worth knowing
What exactly does Fix with AI do?
What exactly does Fix with AI do?
It reads the Spectral marker at your cursor, builds a targeted composer prompt from the rule id, message, and severity, and drafts the edit for you. You still preview the proposed patch as a diff and decide whether to apply it. The lint is never auto-fixed silently.
Which Spectral rules run?
Which Spectral rules run?
Elva extends the recommended OpenAPI ruleset out of the box. You can tune which rules are active, toggle individual checks, and adjust severities, so the linting matches your team's house style.
Can an AI edit break my spec?
Can an AI edit break my spec?
No. Proposals are validated as JSON Patch and applied to a copy with validation enabled and mutation disabled. If a patch is malformed, it is rejected before anything is written. You always see the diff and confirm before it lands.
Are edits precise or sweeping?
Are edits precise or sweeping?
Precise. The composer emits granular add, remove, and replace operations scoped to the exact path you want changed. It appends to arrays and inserts single properties rather than replacing entire objects, so surrounding content is preserved.
On this page
- AI-assisted spec editing