SDK generation diagnostics

SDK generation

Raised while a codegen engine emits an SDK, when the engine can tell in advance that the source it would write cannot compile. Generation stops rather than writing it, so the failure names your spec instead of the SDK’s own runtime.

These stop the one target, not the whole run. When an engine refuses, glotto generate drops that target and still writes every other one — a refused Swift SDK does not cost you your TypeScript and Python SDKs. The run exits non-zero and names the target it could not build, so a CI pipeline that asked for thirteen SDKs and received twelve fails rather than passing quietly. glotto generate reports these before anything is written, so you can see the problem without waiting for a build.

Reserved model names

A schema whose type name collides with a type the generated SDK itself uses is a family of its own, with a row for every language and a full account of what each engine reserves: Reserved model names. The rest of this page is about a collision between two of your own schemas, which is a different question with a different remedy.

Two of your own schemas emitting one type name

A separate problem with a separate code, and no name of the SDK’s involved. C# writes each model to its own Glotto/<Name>.cs and derives that name in PascalCase, which is lossy — so two schemas that differ only in casing or separators (widget and Widget, foo_bar and FooBar) emit one type name and claim one file. Left alone, whichever file is written last destroys the other, the SDK builds cleanly, and one of your schemas is simply not in it.

Generation resolves this for you in every other case. The schema whose name is already spelled exactly as the type it emits keeps that type name, and each other takes the model suffix — FooBar and fooBar become FooBar and FooBarModel. Where no schema is spelled that way, the first key in code-point order keeps it — and generation reports every rename it applied, exactly as it does for a reserved model name. Only the C# type name changes; your other SDKs keep both original names. Pinning the schema that already keeps its spelling does not trigger this diagnostic: that schema was never going to move, so the pin asks for nothing generation was not already doing.

A pin is a decision, so it is never renamed over. Where the schema generation would otherwise RENAME got its name from models.<M>.name.csharp, the C# target is refused instead: renaming over an explicit pin would give you a type name you did not ask for. Give one of the two a different C# name, or rename one schema everywhere with a rename_schema transform. Every other target still generates.

Two of your own schemas sharing one name

Every code above is about a collision with something Glotto declares. This one is not: it fires when two schemas you wrote would emit the same type, so neither name is reserved and there is nothing of ours in the way.

PHP gives every model its own file, so before the rename existed the second schema’s file simply replaced the first on disk and the model was gone — with php -l reporting the survivor clean, the SDK loading without complaint, and its own test suite passing. That is the failure the automatic rename removes.

Two situations still stop the PHP target rather than renaming, and both raise the code above. The first is a pin you cannot have: if you set models: { A: { name: { php: FooBar } } } while another of your schemas already emits FooBar, generation refuses instead of quietly giving your pinned model a different name — a pin is a decision, not a suggestion. Rename either schema, or drop the pin and let the automatic rename resolve it. The second is a collision the rename does not yet cover — a schema named after a discriminated-union variant class, such as PetCat for a Pet union with a cat discriminator value. Generation stops and names both files rather than writing an SDK with one of the declarations deleted out of it; renaming the schema resolves it.

When two of your own schemas collide

Everything above is a schema colliding with a name the SDK itself puts in scope. Two of your own schemas can collide the same way, and Glotto resolves that by renaming too — the second schema keeps its data, its fields and its file, under a <Name>Model type name that the generate run reports. Nothing is dropped, and no target is skipped.

There is one case it cannot resolve for you: when you pinned the name it would have to move.

A pin is treated as a decision rather than a suggestion, which is why this is reported instead of renamed: quietly emitting your pinned schema under a different name would substitute a type name you never asked for. A pin on the schema that keeps its name is never reported — that one generates exactly as you pinned it.

Two generated Kotlin types that claim one file

Kotlin is the one language where two generated types can claim one file without a schema being involved, because it writes one file per top-level type and names each file after the type. The same property is why the Kotlin reserved set above compares the SDK’s own type names case-insensitively while leaving List, Map and Any alone: Client and CLIENT are two perfectly good Kotlin types, but they compile to Client.class and CLIENT.class, which are one file on macOS and Windows. That build is green and the class is simply absent, so a schema named CLIENT is renamed to CLIENTModel rather than left for a compiler that will not complain. A separate problem with a separate code, and no name of the SDK’s involved. Java writes each model to its own com/glotto/<Name>.java and derives that name in PascalCase, which is lossy — so two schemas that differ only in casing or separators (widget and Widget, foo_bar and FooBar) emit one type name and claim one file. Left alone, whichever file is written last destroys the other, the SDK builds cleanly, and one of your schemas is simply not in it.

Generation resolves this for you when you have not pinned a name. The schema whose name is already spelled exactly as the type it emits keeps that type name, and each other takes the model suffix — FooBar and fooBar become FooBar and FooBarModel. Where no schema is spelled that way, the first key in code-point order keeps it — and generation reports every rename it applied, exactly as it does for a reserved model name. The order your schemas appear in your document never decides this, so re-ordering two of them never moves a type name. Only the named target’s type name changes; your other SDKs keep both original names.

A pin is a decision, so it is never renamed over. Where the schema the rename would have moved got its name from models.<M>.name.<target>, that one target is refused instead: renaming over an explicit pin would give you a type name you did not ask for. Give one of the two a different name for that target, or rename one schema everywhere with a rename_schema transform. Every other target still generates.

The same collision in every other target

The rule above is not C#’s, Java’s, PHP’s or Ruby’s — it is one rule, and every target Glotto generates applies it. Six more raise their own code for the pinned case:

Two of those six say nothing, and that is the reason the rename exists. In Elixir and Python the generated SDK builds, imports, and passes its own emitted tests with one of your schemas missing — there is no error to look for, and no exit code that would tell you. The four that fail loudly are the easy half.

Everything in the two paragraphs above applies unchanged to all of them: the collision is renamed automatically and every rename is reported, only the affected target’s type name moves, and a pin is refused rather than renamed over.

Two Dart resource groups sharing one class name

A property name Go cannot carry

Go is the one target that stores a field’s wire name in a struct tag — `json:"color"` — and neither the tag’s own quoting nor encoding/json’s tag grammar can hold an arbitrary string. A tag carries a name built from letters, digits, and the punctuation !#$%&()*+-./:;<=>?@[]^_{|}~ plus the space; any other character is unrepresentable. Among printable ASCII that is these five, each measured against the pinned Go toolchain rather than read off the standard library:

One whole name is refused for a different reason: a property named exactly -, which encoding/json reads as skip this field, so the field would leave the wire altogether rather than under a truncated key. A dash inside a name is fine, as are a space, a dot and $ — this is not a rule about unusual-looking names.

A request body the SDK cannot encode

Go and Python send a request body as JSON, a raw string or bytes, multipart, or application/x-www-form-urlencoded. A form body is a set of name=value pairs, so its schema must be an object or a map. An operation whose body is none of these, such as application/xml over an object schema, a form body declared as a scalar or array, or a multipart body that is not an object, would either have no method in that SDK or, for a paginated or streaming operation, be sent with the wrong body. It is refused instead. Every other SDK that sends a form body refuses one declared over anything but an object or a map the same way, each under its own code below.

The TypeScript and React Native SDKs also send an application/x-www-form-urlencoded body from the typed object or map, and refuse a form body declared as anything else.

Java and Kotlin take a form operation’s model as its body and encode it themselves, so for them only a form body that is neither an object nor a map has nothing to take, and is refused the same way.

A paginated operation whose success is not a JSON document

Every SDK Glotto generates ships its own integration-test suite, and for an operation paginating by cursor or cursor id that suite walks two real pages. Building it needs the operation’s documented success to be a JSON document in which your locators actually resolve: itemsPath, plus nextCursorPath or lastItemIdPath. Those always come from the operation’s x-pagination extension — a query-parameter name can tell Glotto that an operation paginates, but never where its items or its next cursor live, so this diagnostic only reaches operations whose extension names them. Pagination covers the SDK surface they produce.

This one stops every target, not one. The plan behind those suites is language-agnostic and is built once for all thirteen SDKs, so the run names each target with the same message and writes nothing. That is the right reading: what it reports is a disagreement between the locators you declared and your own response schema, and no single language is involved.

A mixed success is fine — an operation documenting both a JSON page and a binary download at the same status paginates over the JSON side, and the generated mock server answers it with that side too. What cannot work is a success with no JSON side at all: an application/octet-stream body is an opaque byte stream, and the locators exist nowhere in it. Generation refuses that combination for cursor and cursor-id pagination; on the page, offset and link-header strategies it is not yet detected.

The spec-repo target

Raised when targets.spec_repo asks for a document your input cannot produce. Both are refusals of an input domain, not of postponed work — and both stop the run rather than publishing a spec repo with a document missing, because a published spec repo is a surface your consumers read: an absent file there reads as a fact about your API rather than as a Glotto refusal.

Retiring a file Glotto no longer generates

Raised when a Glotto release stops emitting a file your project already has — a build config the stack outgrew, a module a newer layout replaced. Regeneration removes it, so your tree keeps matching the project Glotto builds today rather than accumulating files nothing reads.

Only a file Glotto can prove it wrote is ever removed, and only while your copy still matches the bytes Glotto produced. Every generated source carries a @glotto:generated-checksum comment; that comment is what makes the removal safe. A file with no checksum comment — anything you added yourself, and anything Glotto emits unstamped, such as the machine-readable mirrors under public/ — is left exactly where it is, whether or not Glotto still generates it. Turning a target off in glotto.yml deletes nothing either: the tree it wrote stays until you remove it.

That leaves one case Glotto will not decide for you.

Terraform objects with declared additional values

Generation refuses this object before returning provider source instead of presenting a closed Terraform attribute schema as equivalent. Objects without the declaration and ordinary map attributes retain their existing behavior.