Optional and Nullable Properties

All APIMatic SDKs support both optional and nullable properties. This ensures accurate data serialization and deserialization, leading to better data integrity and API interactions.

Key Benefits

• Fine-Grained Field Control: Define fields as optional, nullable, or both, based on specific scenarios.
• Field-Based Operations: Distinguish between missing and explicitly null values at runtime.
• Language Consistency: Ensure consistent behavior across all supported SDK languages.

Understanding the Behavior

The table below shows how JSON can be mapped to the various combinations of optional and nullable values.

	Nullable = true	Nullable = false
Optional = true	Key can be omitted Key can have null as a value if set explicitly Key can have a valid value {}, {"key":value}, {"key":null}	Key can be omitted Key can't have null as a value {}, {"key":value}
Optional = false	Key must be included Key can have null as a value {"key":value}, {"key":null}	Key must be included Key can't have null as a value {"key":value}

Example OpenAPI Specification

Below is the schema definition for a Product model, containing the fields name (required), description (optional), quantity (required nullable), and notes (optional nullable).

schemas:
  Product:
    type: object
    properties:
      name:
        type: string
        description: The name of the product.
      description:
        type: string
        description: A detailed description of the product.
      quantity:
        type: integer
        description: Quantity of the product in stock.
        nullable: true
      notes:
        type: string
        description: Optional notes about the product.
        nullable: true
    required:
      - name
      - quantity

Acceptable values for this Product model include:

Full Product

{
  "name": "Laptop",
  "description": "A lightweight, powerful device",
  "quantity": 10,
  "notes": "This is a popular item."
}

Nullable set to `null`

{
  "name": "Tablet",
  "description": "A portable, touch-screen device",
  "quantity": null,
  "notes": null
}

Without Optional fields

{
  "name": "Monitor",
  "quantity": 15,
  "notes": "High resolution display"
}

Required fields only

{
  "name": "Smartphone",
  "quantity": 50
}

SDK Examples

TypeScript

const apiController = new ApiController(client);

const body: Product = {
  name: 'Laptop',
  quantity: 10,
  description: 'A lightweight, powerful device',
  notes: 'This is a popular item.',
};

await apiController.createProduct(body);

Java

ApiController apiController = client.getApiController();

Product body = new Product.Builder(
    "Laptop",
    10
)
.description("A lightweight, powerful device")
.notes("This is a popular item.")
.build();

apiController.createProductAsync(body);

Python

client_controller = client.client
body = Product(
    product_name='Laptop',
    quantity=10,
    description='A lightweight, powerful device',
    notes='This is a popular item.'
)

client_controller.create_product(body)

PHP

$body = ProductBuilder::init(
    'Laptop'
)
    ->description('A lightweight, powerful device')
    ->quantity(10)
    ->notes('This is a popular item.')
    ->build();

$client = ProductManagementApiClientBuilder::init()->build();

$client->getAPIController()->createProduct($body);

.NET

ApiController apiController = client.ApiController;

Product body = new Product
{
    Name = "Laptop",
    Quantity = 10,
    Description = "A lightweight, powerful device",
    Notes = "This is a popular item.",
};

await apiController.CreateProductAsync(body);

Ruby

body = Product.new(
  'Laptop',
  10,
  'A lightweight, powerful device',
  'This is a popular item.'
)

client = ProductManagementApi::Client.new

client.client.create_product(body)

Go

apiController := client.ApiController()

ctx := context.Background()

body := models.Product{
    Name:           "Laptop",
    Description:    models.ToPointer("A lightweight, powerful device"),
    Quantity:       models.ToPointer(10),
    Notes:          models.NewOptional(models.ToPointer("This is a popular item.")),
}

apiController.CreateProduct(ctx, body)

note

OneOf or AnyOf properties also support optional and nullable combinations.