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

The *_RESERVED_MODEL_NAME codes below are one problem in thirteen languages: a schema whose type name collides with a type the generated SDK itself uses. Left alone, your model silently takes over the SDK’s own references and the build fails with errors pointing at the SDK rather than at the collision — or, in Elixir, does not fail at all and quietly replaces your model.

Generation resolves this for you. The affected SDK emits the model under a deterministic alternative — Data becomes DataModel, and a second collision becomes DataModel2 — and generation reports every rename it applied. Only that language’s type name changes; your other SDKs keep the original name. To choose the name yourself, pin it per target with models: { Data: { name: { swift: MyName } } }, which always wins over the automatic rename and leaves your other SDKs alone; a rename_schema transform renames it in every target instead.

You will only see one of these diagnostics if the rename cannot be applied — it names every colliding schema and the identifier each one shadows. In practice that means one thing: you pinned the name yourself, with models: { Data: { name: { swift: … } } }, onto an identifier that language reserves. A pin is treated as a decision rather than a suggestion, so generation will not quietly substitute a different name for the one you asked for — it refuses that target and tells you. Choose another name, or remove the pin and let the automatic rename resolve it.

Two things hold for all thirteen. Names that merely look built-in are not affected: each engine reserves only what its generated code actually names without qualification, which is why every safe column below has entries in it. And the fixed half of each reserved set — the language builtins and the SDK’s own scaffolding — already covers every type that SDK can use, not only the ones your current endpoints reach, so turning on streaming, pagination or a new auth scheme cannot widen that half under a build that used to work. The derived half is where it can, and that is the next paragraph’s whole subject.

One case cuts across every language, and it is a fact about your spec rather than about the engine. Alongside the fixed vocabulary above, every SDK also declares names derived from your own IR keys — the shared baseline is one class or module per resource: an orders resource makes the Swift SDK declare public final class OrdersResource, and a nested pets/photos pair makes PetsPhotosResource. Because a derived name is a function of your own resource, operation and model keys rather than of the language, it can appear on a spec that used to build — unlike the fixed vocabulary, which a spec either always or never reaches. Adding a resource, turning on SSE for an operation you already had, or growing a discriminated union is what creates the collision, not anything Glotto changed between generations. The remedy is the same either way: rename the model, or rename the resource, operation, event or discriminator value that produced the name it collided with — and the diagnostic always names which one.

Most engines add one or more families beyond that shared resource case, and they differ enough to be worth reading rather than assumed. Throughout — and in the table below — <Resource> is the PascalCase join of a resource key path (a nested pets/photos gives PetsPhotos), <Method> a method key, <Union> a discriminated-union model key, <Member> one of that union’s discriminator values, <Event> a key of an operation’s event_types map, <Scope> a declared OAuth2 scope, and <Parameter> an optional query parameter.

• Swift and Rust add one <Method>StreamEvent enum per streaming operation with event types — so turning on SSE for an operation you already had is enough to create a collision that a previous generate certified absent.
• Dart and C# add that same enum and one type per mapped event name, so a new key in an operation’s event_types reserves a name of its own: a sealed class plus its variants in Dart, an abstract record plus its per-event variants in C#.
• TypeScript and React Native derive the same five families — <Resource>Resource, a <Resource>ResourceWithRawResponse sibling wherever that resource has buffered operations, <Method>StreamEvent, one <Union><Member> per discriminated-union member, and the <Union>Unknown catch-all. They also share a behavior worth knowing about even when the build stays green: TypeScript merges a same-named interface declaration into an existing one rather than rejecting it, so the compiler can accept the collision while your model’s type silently means the SDK’s instead.
• PHP and Ruby add one <Resource><Method>Request class per operation whose request body is an inline JSON or multipart object.
• Kotlin adds that same request-body family plus the stream-event pair (<Resource><Method>StreamEvent and one <Resource><Method>StreamEvent<Event> per mapped event) — and is worth knowing about even on a green build for a different reason: the Kotlin SDK emits one file per top-level type, so two declarations claiming one path means one of them never reaches disk, with no compiler error at all.
• Java collects all four of Kotlin’s families and the discriminated-union pair, because it puts every type in one package. Two of its failure modes are silent, and they are not the same: a collision with a class nested in the generated client compiles clean, because javac binds the SDK’s own reference to its own type and your schema is simply never used; and, separately, where two files would claim one path, one is dropped before the compiler runs — which is Kotlin’s case.
• Python’s resource family is the largest of the thirteen: four names per node, where TypeScript’s and React Native’s are two and everyone else’s is one. It emits a sync and an async accessor class, plus a WithRawResponse sibling for each where the node has at least one buffered method, so a single orders resource can reserve all four spellings at once. It adds a <Union>Unknown catch-all and no stream-event family at all — its SSE events are emitted as the model types your spec already carries, so there is no per-method union type to collide with.
• Elixir has the resource case with no suffix (an orders resource emits defmodule Glotto.Orders, so the reserved identifier is a bare <Resource>) plus the discriminated-union pair; see below for the failure it shares with Ruby, and the one thing only it has.
• Go derives the widest set of the thirteen: the resource accessors, a stream-event trio, a discriminated-union trio, a per-operation option type with one constructor per optional query parameter, and one member per declared OAuth2 scope — all of them sharing the one package-level namespace with the fixed half, because a Go package has no module boundary to keep them apart. Its fixed half, by contrast, holds nothing from the language at all: Go’s builtins and stdlib types are reached under a package qualifier or spelled in lower case, so a PascalCase schema name can never shadow one.

Every row below follows one convention. Collides with lists the fixed vocabulary first (language and runtime builtins the emitted code references or declares, unaffected by your spec), then the SDK’s own declared types (abbreviated to the handful worth recognizing, since several engines’ full lists run past thirty), then every derived family that engine has, phrased as one <X> per <key> in your spec. The abbreviation applies to the first two lists and never to the third — and that is a checked property rather than an editorial promise: our own CI derives the third list by running each engine’s derivation, and runs every identifier in the last two columns through the same resolver glotto generate calls, so a row that understated what its engine reserves fails our build rather than reaching you.

Two diagnostics in this family are not about our names at all. GLOTTO_REACT_NATIVE_COLLIDING_MODEL_NAMES and GLOTTO_TYPESCRIPT_COLLIDING_MODEL_NAMES cover the case where two of your own schemas emit the same type name — foo_bar and fooBar both become FooBar — which would declare that type twice in one module. TypeScript merges two declarations of one name rather than rejecting them, so the usual outcome is a green build shipping a public type that is your two schemas folded together; only a mismatched pair (an interface beside a type alias) is a Duplicate identifier error.

You will normally never see either code, because this is resolved the same way every other collision is: one of the schemas keeps the name and the rest are renamed with the Model suffix and a numeric tail — FooBar, FooBarModel, FooBarModel2 — and every rename is announced when you generate. The schema that keeps the name is the first of the group in sorted order, which depends only on your own keys, so it does not change when you add or rename an unrelated schema.

The code is emitted in one case: you pinned models.<M>.name.<target> on the schema that would have been renamed. Renaming over an explicit pin would give you a type name you did not ask for, so Glotto refuses that target instead — every other target you configured still generates — and the message names the sibling that keeps the name. Pin the other schema instead, drop the pin and let the automatic rename run, or rename one of them everywhere with rename_schema.

Java and Kotlin reserve binary helper names only when an operation declares a binary response. Both then reserve BinaryResponse, DownloadResult and BinaryExchange; Java also reserves BinaryPayload. With no binary responses, a customer model named BinaryResponse keeps that name. Runtime references are qualified so customer models named Java Runnable or Kotlin Set, Flow and Job remain available.

Swift is the strictest case and the reason the behavior exists: it resolves a bare type name to the declaration in the same module before any import, and offers no way to disambiguate. Kotlin’s Unit collides only in the Multiplatform packaging variant, and is reserved across all three so a variant switch cannot break your build.

Ruby is the quietest case: it does not refuse a second definition of a name already declared in scope — it rebinds it — so the collision produces no error at any moment a build could report one. It is worth knowing about even though you should never meet it.

A schema named after a class the Ruby SDK declares would replace that class outright while ruby -c passed, require 'glotto' exited 0, and the SDK’s own test suite stayed green. The failure would arrive as a NoMethodError from inside the SDK the first time you called the affected method. That is why these names are renamed rather than reported: there is no earlier moment at which anything could tell you. Two constants that look like they belong on that list are not on it — READ and WRITE live inside Glotto::OAuth2Scopes, which Ruby treats as a different constant from Glotto::READ, so a schema of either name is left exactly as you wrote it.

Elixir used to be Ruby’s failure one step further, and is now the opposite — it fails loudly. Like Go’s, and unlike every other engine’s, its reserved set contains no language builtin at all: a module named Map in your SDK’s namespace is Glotto.Map, which never captures Elixir’s own Map, so schemas called Map, String or Enum are perfectly safe. What is not safe is a schema named after a module the SDK declares itself.

Which way that fails depends on where the two defmodules land, and the idiomatic package layout moved them apart. Two declarations of one module name in a single file are accepted silently — the later one simply replaces the earlier, and a schema named Client would compile cleanly with your model’s struct, from_map/1 and to_map/1 quietly gone. That was the old single-file SDK. Each module now has its own file, and across two files Elixir refuses outright:

error: cannot define module Glotto.Client because it is currently being defined in lib/glotto/client.ex:1

The build stops; nothing is silently lost. So the rename is no longer protecting you from a missing model — it is protecting you from an SDK that does not compile at all, which is a better failure but still not one you should have to meet. It applies to your resource modules too: this engine names a resource module after the resource key with no suffix, so a pets resource emits defmodule Glotto.Pets and a schema named Pets collides with it. Like the Swift resource case above, that one is a fact about your spec rather than about the engine, so adding the resource later is what creates the collision — the diagnostic names the resource, and renaming or removing it resolves the collision just as renaming the schema does.

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.

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.