Additional Model Properties

APIMatic SDKs provide support for the JSON Schema additionalProperties keyword, which controls how additional properties(those not defined in properties or patternProperties) are handled. This enables SDKs to handle dynamic or unpredictable data structures in API requests and responses.

Configure Additional Model Properties

To leverage additional properties in your SDKs, enable the ExtendedAdditionalPropertiesSupport Code Generation setting while generating your SDKs.

Additional properties can be defined in OpenAPI definitions using the additionalProperties keyword, as demonstrated below:

components:
  schemas:
    StudentResult:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
      additionalProperties:
        type: number

In this example, the StudentResult model defines a required email property of type string. Additionally, it supports any number of additionalProperties where keys are strings, and values are number.

Usage in SDK

After configuring your API definition, the generated SDK will expose these additional properties with type safety. For instance:

SDK Request Examples

Here’s how an object of type StudentResult can be initialized:

TypeScript

const body: StudentResult = {
  email: 'student616@oxford.ac.uk',
  additionalProperties: {
    'Theory Of Automata': 82.1,
    'Computational complexity': 72.5,
    'Functional programming': 78.3
  },
};

Java

StudentResult body = new StudentResult.Builder(
        "student616@oxford.ac.uk"
    )
    .additionalProperty("Theory Of Automata", 82.1D)
    .additionalProperty("Computational complexity", 72.5D)
    .additionalProperty("Functional programming", 78.3D)
    .build();

Python

body = StudentResult(
    email='student616@oxford.ac.uk',
    additional_properties={
        'Theory Of Automata': 82.1,
        'Computational complexity': 72.5,
        'Functional programming': 78.3
    }
)

PHP

$body = StudentResultBuilder::init(
    'student616@oxford.ac.uk'
)
    ->additionalProperty('Theory Of Automata', 82.1)
    ->additionalProperty('Computational complexity', 72.5)
    ->additionalProperty('Functional programming', 78.3)
    ->build();

.NET

StudentResult body = new StudentResult
{
    Email = "student616@oxford.ac.uk",
    ["Theory Of Automata"] = 82.1,
    ["Computational complexity"] = 72.5,
    ["Functional programming"] = 78.3,
};

Ruby

body = StudentResult.new(
  'student616@oxford.ac.uk',
  {
    'Theory Of Automata': 82.1,
    'Computational complexity': 72.5,
    'Functional programming': 78.3
  }
)

Go

body := models.StudentResult{
    Email:                "student616@oxford.ac.uk",
    AdditionalProperties: map[string]float64{
        "Theory Of Automata": float64(82.1),
        "Computational complexity": float64(72.5),
        "Functional programming": float64(78.3),
    },
}

SDK Response Examples

Here’s a sample JSON response representing a StudentResult object:

{
  "email": "student616@oxford.ac.uk",
  "Theory Of Automata": 82.1,
  "Computational complexity": 72.5,
  "Continuous mathematics": "87", // invalid additional property
  "Functional programming": 78.3
}

During deserialization, the "Continuous mathematics" property will be ignored due to a type mismatch, while the "Functional programming" property will be correctly deserialized. The "Functional programming" property can be printed to the console as follows:

TypeScript

// Printing the value of `Functional programming` AdditionalProperty
console.log(response.result.additionalProperties['Functional programming']);
// Output: 78.3

Java

// Printing the value of `Functional programming` AdditionalProperty
System.out.println(response.getAdditionalProperty("Functional programming"));
// Output: 78.3

Python

# Printing the value of `Functional programming` AdditionalProperty
print(response.additional_properties.get('Functional programming'))
# Output: 78.3

PHP

// Printing the value of `Functional programming` AdditionalProperty
var_dump($response->findAdditionalProperty('Functional programming'));
// Output: 78.3

.NET

// Printing the value of `Functional programming` AdditionalProperty
Console.WriteLine(response["Functional programming"]);
// Output: 78.3

Ruby

# Printing the value of `Functional programming` AdditionalProperty
puts response.additional_properties["Functional programming"]
# Output: 78.3

Go

// Printing the value of `Functional programming` AdditionalProperty
fmt.Println(response.Data.AdditionalProperties["Functional programming"])
// Output: 78.3

Real-World Use Cases

Flexible Data Structures: Handle unknown or optional fields returned in API responses, such as metadata or custom attributes.

Extensible Models: Support user-defined properties in API requests while ensuring consistency and type correctness.