Skip to main content

Models

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:

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, remember to 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.

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

Example Value

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 Structure and Exception model types, a valid JSON example is required while for Enumeration a string/number value is accepted.

Fields

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

Field

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. Is Attribute is available for use in Java only.

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

Example

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.

Import JSON/XML

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:

  1. JSON schema
  2. JSON example
  3. XML schema
  4. XML example
note

Importing from a schema will provide a more accurate representation than importing from an example.

Import JSON/XML

Name

This can be set as the name of the new custom type in the API.

JSON/XML

You can paste the JSON/XML for import in this field.