Build your integrationSpecs

Spec patches

Small, deterministic OpenAPI corrections applied to the resolved Spec before every review and Generation.

Spec patches carry a small correction when the upstream OpenAPI source cannot be changed immediately. They apply to the same resolved Spec Revision used by Diagnostics, compatibility checks, previews, and every Target.

[
  { "op": "set", "path": "/components/schemas/Customer/properties/id/type", "value": "string", "reason": "ids are strings" },
  { "op": "rename", "path": "/components/schemas/Cust", "to": "Customer" }
]

Supported operations are set, append, remove, and rename. Paths are JSON Pointers with *, **, and [key=value] pattern segments. A patch that no longer matches is skipped and reported in the result. Check warnings after upstream changes to confirm your corrections still apply.

Prefer fixing the source when you own it so all consumers receive the correction. You can copy an exact patch suggested by Diagnostics, review it, and apply it in the source or through PATCH /specs/{spec_id}.

For GraphQL, edit the source SDL using Diagnostic guidance; these JSON Pointer patches apply only to OpenAPI.

Save patches and regenerate

Saving a changed patch list starts generation for every active Target when the Project's auto_generate setting is true. Removing patches with [] also regenerates. Saving the same list does not start another Generation. Patch-only changes keep the current Spec Revision because the source bytes have not changed.

typeship specs update <spec_id> --patches '<json>' returns the saved Spec without waiting for generation. Read the current patches before replacing the complete list, then inspect typeship generations list --project-id <project_id> for the new runs. A Target already queued or running reuses that Generation.

With auto_generate: false, saving patches does not regenerate. Run typeship projects generate <project_id> after saving; the CLI waits for each Target's files and reports its result. You can also call POST /projects/{project_id}/generate and poll the returned Generations.

If saving returns 502 follow_up_failed, the patches were saved but automatic generation could not be queued. Retrieve the Spec to confirm its patches, then generate the Project explicitly.

For AI agentsSpec patches live at spec.patches and are updated with PATCH /specs/{spec_id}. Read the current list before replacing it. Up to 50 patches are accepted.

On this page