Generated Types
This page documents what type definitions in TypeSpec are generated as in emitted libraries
Models
Flattening
Python will do dynamic flattening, exposing the non-flattening syntax, and dynamically accepting the flattened access.
CSharp will generate the model with properties being flattened. During serialization/deserialization, the model will be serialized/deserialized as a non-flattened model.
In Java, @flattenProperty
have no effect on generated libraries.
Models with additional properties
Additional properties of any type
Recommend usage:
Other usages:
Python models are designed to support adding any additional properties.
Additional properties of specific type
Python models are designed to support adding any additional properties.
Due to currently there is no way to know whether a Json could be correctly mapped into the specified type in .Net
, we currently generate any non-primitive value type in additional properties property as BinaryData
.
For typespec:
The C#
generated code is the same as if the type is unknown
:
For typespec with additional properties of primitive types:
The C#
generated code still has the specified type in AdditionalProperties
property:
Additional properties of union type
Python models are designed to support adding any additional properties.
Additional properties of nullable type
Python models are designed to support adding any additional properties.
Discriminator
TypeSpec uses @discriminator
decorator to add a discriminator to a model.
TypeSpec now has two ways to represent a discriminated set.
- Use model
The type of the discriminator property could be an enum (extensible or fixed):
- Use union
TCGC currently only supports the discriminated set based on models, discriminated union is not supported yet.
This is a brief structure of the models in a discriminated set in the output of TCGC.
In .Net generated code, the discriminator property will be generated as internal by default, but configurable to be public.
Nullable
TypeSpec uses | null
to represent nullable types. Nullability is handled differently in languages, but emitter authors will find information
about nullability by inspecting the type of a property.
A nullable type has kind nullable
and property valueType
. The kind of the type tells you the property is nullable, while the valueType
tells you the underlying type you want to generate.
Python treat nullable as optional. If you actually want to send the value null
to the service without the property being ignored, you can send in corehttp.serialization.NULL
. Python does not restrict you from setting any property to this value.
TODO
TODO
TODO
Unions
Union of literals with same type
All emitters will generate their version of a closed enum.
Python never generates closed enum by design. We will always permit users to pass in additional values.
Serialization/deserialization will respect the value defined, in this case it is “left” for LR.Left
and “right” for LR.Right
respectively.
Inline union of literals with same type
This is union defined inline at point of usage.
Python generates this as a union of literals, not as enum. We also don’t generate a closed set of literals.
Union of basic type and literals of that type
Each language will generate their version of an open enum.
Python generates open enum again here.
Inline union of basic type and literals of that type
This is union defined inline at point of usage which include the base type as an option.
Python generates a union of literals again.
Union of other union/enum, basic type and literals of that type
For union of other union or enum. TCGC will do the flatten according to the flag.
With flatten-union-as-enum
flagged true
:
With flatten-union-as-enum
flagged false
:
Python generates a single open enum.
Union of other unions of literals with same type
For union of other union or enum. TCGC will do the flatten according to the flag.
With flatten-union-as-enum
flagged true
:
With flatten-union-as-enum
flagged false
:
Inline union of other unions of literals with same type
For union of other union or enum. TCGC will do the flatten according to the flag.
With flatten-union-as-enum
flagged true
:
With flatten-union-as-enum
flagged false
:
Since this is inline, Python will generate this as a single union of all possible literal values.
Union with multiple types
These are unions where the values don’t share same type.
Python will generate this as a union since these entries don’t share the same type
Enums
Standard
Standard enums will be generated as closed enums.
Python never generates closed enums by design. We will always permit users to pass in additional values.
Versioning Enums
Spread
Spreading enums will return the resultant enum as a new single closed enum.
Python generates one open enum, because Python never generates an enum as fully closed.
Scalars
Encoding
We will take the @encode
decorator into account, determining how we serialize inputted scalars to send over the wire.
When you specify an encoding type, say that you want to encode an integer as a string, that will also be represented in our generated SDKs.
Namespace
The namespace for models, enums, and unions will follow the namespace they belong to. You can use @clientNamespace
to override it if needed.