Which constructs would you keep out of a shared IDL contract that several ecosystems generate readers from, and why?

## The rule under all of the specifics A contract compiled for several ecosystems must be **modelled in the IDL's own type system**. Whenever a construct's meaning comes from one language, the generator for every other target must approximate it, and the approximations differ — which means consumers disagree about what the same bytes mean. The single test worth remembering: *if explaining a field requires naming a runtime, the contract has leaked.* ## The constructs that leak - **Runtime-typed polymorphism.** A field declared as "some subtype, identified by a type name written into the payload" asks every generator to invent a dispatch mechanism and forces every consumer to share the producer's class taxonomy. It is also the construct most likely to turn a decoder into an object factory driven by untrusted input. Model the alternatives explicitly instead — a declared, closed set of variants with an explicit discriminator field, so every generator emits the same choice. - **Deep or recursive nesting.** A record that contains itself to arbitrary depth is expressible in most IDLs, but generated accessors for it diverge sharply, and a decoder's recursion behaviour on a hostile input is not uniform. Flatten to a list with parent references when the depth is genuinely unbounded. - **Collections whose semantics are assumed.** "A map" hides three questions: is iteration order part of the contract, which key types are permitted, and what happens on a duplicate key? Ecosystems answer all three differently by default. State the answer in the contract, or use a repeated record of explicit key/value pairs when order or duplicates matter. - **Identifier collisions.** A field name that is a reserved word in one target, or that differs from another field only by case, forces that generator to mangle the identifier. The wire key is unaffected — the contract still says what it said — but the generated name differs per ecosystem, which is confusing in review and invisible until someone adds the affected target. - **Types whose only definition is a runtime's.** Any field whose meaning is "whatever that ecosystem's native type does" — including free-form blobs that consumers are expected to decode with their own native mechanism — is a contract in name only. ## What belongs there instead | Leaky construct | Neutral modelling | |---|---| | Subtype chosen by a runtime type name | closed variant set with an explicit, declared discriminator | | Unbounded recursive record | flat list of records carrying a parent reference | | Map with assumed ordering | repeated key/value records, order stated in the contract | | Free-form native blob | declared record, or bytes with a stated encoding and owner | | Name colliding with a reserved word | a name chosen to survive every target's conventions | ## Why this is a review property, not a coding one These defects are cheap to fix in the contract and expensive to fix after generation, because by then several teams have generated against them. That makes them the core of a contract review: a reviewer is not asking "is this field useful", but **"does this mean exactly one thing in every ecosystem that will compile it, and can the generator for a target we have not added yet express it?"** The forward-looking half matters. A contract is usually written when two ecosystems consume it and lives long enough to reach four. Constructs that were fine for the original pair — because both happened to share a convention — become the reason the fourth consumer's reader is subtly different. Ecosystems genuinely differ on how they represent absent values, how they order collections, and whether they can express unsigned or arbitrary-precision numbers at all; the contract's job is to say which behaviour is required, so no generator has to guess. ## The pragmatic counterweight None of this argues for a contract so minimal it is useless. Nested records, enumerations, repeated fields and optional fields are all expressible everywhere and should be used freely. The line is not "avoid structure", it is **avoid structure whose meaning is inherited from one implementation**. A contract that can be read by someone who has never seen the producer's source, and implemented by a generator for a target that did not exist when it was written, is the target to describe in an interview.