SHARE THIS ARTICLE

Models

A model is a type of data structure that is used in an API description. We can think of it as a complex type.

We will need to define models whenever we describe our API. Basically in the model, 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 models and define the model relationship as well.
We have 2 main sections present on the Model Definition page. Let’s go over each section one-by-one.

Model Settings

Model

Name

This is the name of the custom model that we are creating. The model name will uniquely identify a model in the API. Therefore, keep this name unique.

Description

This 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.

Base Model

If we want our model to inherit from another model, we can do that using this option. Basically, 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 we can only inherit from other models if the model type is Struct. Model inheritance is not available for Enum types.

Model Type

This describes the nature of implementation of the model. A model can be of 3 types:

FieldDescription
StructureThis means that the complex type is a structure of data e.g. an object.
EnumerationThis means that the model can have any value from a set of values only. These set of values will be integers or strings.
ExceptionThis 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.

Discriminator

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.

Note   Discriminator fields are only supported for models of structure type.

Discriminator Value

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.

Fields

A model can have multiple fields. Each field can be thought of as a property of the custom data type (model)

Field

Field Name

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.

Description

This 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 Value

We 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.

Type

This option lets us set the type of the field. The type can be primitive types 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

DateTime Format

This option becomes visible when the Type of the Field is chosen to be DateTime. 3 formats for DateTime are allowed:

  • Rfc1123
  • Rfc3339
  • Unix TimeStamp

For more details about each format, check out the documentation about Field Types

FlagDescription
NullableSelecting this option means that the field can have null value.
Read-OnlySelecting 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 ArrayThis flag indicates whether the field is an array or a collection. When set, code generation creates appropriate collection structure, e.g. List etc.
Is MapThis flag indicates whether the field is a dictionary. When set, the generated field will be a dictionary with keys that are strings, e.g. `Dictionary<String, type>.
Is AttributeThis 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.

Note   Is Attribute is available for use in Java only.


Have questions? Submit a request.