Should an OData client generate typed proxies from $metadata at build time or discover the model at runtime, and how does each cope with model changes?

## Two ways to consume $metadata - **Build-time proxy generation**: a tool reads `$metadata` and emits typed code, with classes for entity and complex types, enumerations, accessors for entity sets and singletons, and methods for actions and functions. The model is frozen into the client when it is built. - **Runtime discovery**: the client fetches `$metadata` when it starts, or on demand, and drives itself from the model, choosing columns, building `$filter` and `$select` expressions and reading annotations. The OData protocol presents this as the reason a service advertises its model in machine-readable form: so that generic clients can interact with it in a well-defined way. | | Generated proxies | Runtime discovery | |---|---|---| | Type safety | checked when the client is compiled | checked only at run time | | Developer experience | typed entities and operations | generic code and string paths | | A new property or type | invisible until regeneration | visible on the next fetch | | Start-up cost | none | fetching and parsing a possibly large document | | Good fit | a fixed integration with a known service | admin UIs, explorers, multi-tenant or configurable models | ## What OData promises about change The specification treats the data model as a contract between the service and its clients: a service may extend it only in ways that do not break existing clients. Its list of **safe changes** includes: - adding a property that is nullable or has a default value, or a navigation property that is nullable or collection-valued; - adding entity types, complex types, entity sets, singletons, type definitions, enumerations and terms; - adding actions, functions and their imports, and adding, after the existing ones, a nullable action parameter or a parameter annotated `Core.OptionalParameter`; - adding annotations a client need not understand to interact correctly. Clients SHOULD be prepared for such changes, in particular for properties and derived types the service did not define before. Breaking changes, such as removing a property, changing its type, adding or removing key properties, or reordering operation parameters, require a new service version at a different service root. OData 4.01 adds a second option: versioning the metadata with the `Core.SchemaVersion` annotation. ## What that means for generated proxies 1. Deserialization must tolerate unknown properties. The payload rules already require clients to handle or safely ignore content their payload version does not define. 2. An entity that arrives with a derived type the proxy has no class for should map to the nearest known base type instead of failing. 3. The safe-change list mentions adding new enumerations, not new members of an existing one, so a generator that turns an enumeration into a closed type should still decide what an unknown value does. 4. Generate from the fullest model. Services SHOULD NOT vary the model by authenticated user, and if they do, every difference MUST be a safe change relative to the full model, so a proxy generated with a restricted account can lack types that other users see. ## Noticing that the model moved - A service MAY return an `ETag` on the metadata document, which lets a client make a conditional request instead of downloading it again. - When it does, it SHOULD also put that value in responses as the metadata ETag control information (`@odata.metadataEtag`, or `@metadataEtag` in a 4.01 payload) under minimal or full metadata, so a client can see that a response was produced from a newer model. - In OData 4.01, a service that versions its metadata MUST support the `$schemaversion` system query option. On `$metadata`, `$schemaversion=*` returns the current version; the client SHOULD then send the `Core.SchemaVersion` value it found on later requests to pin itself. An unknown version gets `404 Not Found`, and without `$schemaversion` the service MUST serve metadata free of breaking changes over time. ## A pragmatic split One resolution is to combine both: typed proxies for the entities and operations a product depends on, and runtime reading of `$metadata` for annotations, optional fields and capabilities. Whichever the team chooses, regeneration belongs in the build pipeline, the client must follow the tolerance rules above, and the service team should treat the safe-change list as the line it does not cross without a new service root or schema version.