A type/model is a data structure that is used in an API definition. We can think of it as a complex type.
We will need to define types whenever we describe our API. Basically in the type, we will define fields that will be used to get the API response that we need.
If our API response requires inheritance, we will need to create multiple types and define the type relationship as well. We have two main sections present on the Model Definition page which are described below:
This is the name of the custom model that we are creating. The model name will uniquely identify a model in the API. Therefore, remember to keep this name unique.
DescriptionThis section can be used to give a brief description of the model or include any comments/remarks about it. A good description would be to mention what the model is used for.
If we want our model to inherit from another model, we can do that using this option.
All the models we have defined in our API are listed here. We can choose any model from the list to be the parent model of this one i.e. we can choose any model from which we want our current model to inherit. In the example, we are not inheriting from any other model.
It is important to note here that
Structure type models can only inherit from other
Structure models. Similarly,
Exception type models can only inherit from other
Exception models. Model inheritance is not available for
This describes the nature of implementation of the model.
A model can be of 3 types:
|Structure||This means that the complex type is a structure of data e.g. an object.|
|Enumeration||This means that the model can have any value from a set of values only. These set of values will be integers or strings.|
|Exception||This means that the model is a type of exception and its properties will be returned in the response by the API server in the case of an error.|
A discriminator field helps the generated SDK determine which model to deserialize the response from the server into.
This behavior might be required when the return type of an endpoint or the type of a field of a model is set to a specific model but the server may also return JSON corresponding to any of the child classes of that model. The value in this text box should exactly match the JSON key of the chosen discriminator field in the response.
Discriminator fields are only supported for models of structure type.
The discriminator value of a model serves as a deserialization marker for the generated SDK. If the value of the discriminator field in the JSON response from the server matches the discriminator value of a model, the SDK will deserialize the response into an instance of that specific model.
Discriminator values must be provided for all models which specify discriminator fields and all of their child classes.
Read more about discriminators here.
A sample value for the model that will be used in documentation to indicate to the users what a model instance can look like. For
Exception model types, a valid JSON example is required while for
Enumeration a string/number value is accepted.
A type can have multiple fields. Each field can be thought of as a property of the custom data type (model).
|Nullable||Selecting this option means that the field can have null value.|
|Read-Only||Selecting this option means this field’s value can only be obtained, not changed in the generated SDK. When set, the generated code will have a public getter but no public setter for this property.|
|Is Array||This flag indicates whether the field is an array or a collection. When set, code generation creates appropriate collection structure, e.g. |
|Is Map||This flag indicates whether the field is a dictionary. When set, the generated field will be a dictionary with keys that are strings, e.g. |
|Is Attribute||This flag is only available for use in languages that provide support for XML. As of now, it is only available for use in Java. In XML, we can either have elements or attribute values. So, if Is Attribute flag is set, this field will be an attribute (which can be used with any XML element). Otherwise, it will be treated as an XML element. Is Attribute is available for use in Java only.|
Each field has to have a name. This name identifies the field (or the property) of the model.
Care must be taken not to use any programming language-specific keywords as field name.
DescriptionThis option lets us include a small description for the field. This description is converted into comments that will be placed with the field definition in the generated code.
Default ValueWe can specify a default value for our field. The default value specified must match with the type of the field. For example, if the type of our field is `Boolean`, the default value can be `true` or `false`.
TypeThis option lets us set the type of the field. The type can be a primitive type like `Number`, `String` etc. or it can be a complex type that we have defined ourselves (i.e. a custom model). More detail about types can be found [here](/define-apis/field-types).
This option helps you include a sample value for the field that will be used in the documentation to indicate what the field value can look like.
This example must be valid according to the field type.
You can also add a new custom type in the API using the Import JSON/XML section. Any of the following can be used for importing a model using this option:
- JSON schema
- JSON example
- XML schema
- XML example
Importing from a schema will provide a more accurate representation than importing from an example.
This can be set as the name of the new custom type in the API.
You can paste the JSON/XML for import in this field.