Typed Additional Model Properties Support in All SDKs

We’re introducing support for typed additional model properties across all SDKs, enhancing type safety and alignment with OpenAPI specifications.

Details

Model classes in C#, Java, PHP, Python, Ruby, Go, and TypeScript SDKs now support typed additional properties. This update improves type safety and aligns with OpenAPI specifications by allowing models to store additional properties with specific, user-defined data types. The feature enhances data consistency, reduces runtime errors, and improves SDK flexibility while closely adhering to OpenAPI standards.

Open Api Example

Here’s an example schema of type StudentResult, which contains an email field for student identification and additional properties of type number. The StudentResult model represents a student's results in various subjects, where the subject names are the keys and their respective scores are the values:

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

What's New?

Previously, the EnableAdditionalModelProperties CodeGen setting allowed additional properties in model classes to be stored using a generic any type, leaving type management to the user. With this update, SDKs now support user-defined types for additional properties, ensuring more reliable data handling and seamless integration with OpenAPI specifications.

With this release, enabling ExtendedAdditionalPropertiesSupport through CodeGen Settings will automatically provide typed additional properties in your SDK models.

Key Features

• Typed Additional Properties: Users can now define specific types for additionalProperties, enhancing type safety.
• Inheritance Handling: In cases of typed additionalProperties definitions in inherited models, the root model's definition will apply to all child models, regardless of whether it is disabled in individual child models. This minimizes type conflicts and ensures consistency.
• Conflict Prevention: Adding additionalProperties with keys that conflict with existing model properties will trigger runtime exceptions, catching issues early during serialization/deserialization.

SDK Request Examples

Here’s how to define a request object of type StudentResult in various languages:

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 properties
  "Functional programming": 78.3
}

After deserialization, the "Continuous mathematics" additional property will be ignored due to invalid type. To access "Functional programming" additional property use the following code snippet to print the value in different programming languages:

TypeScript

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

Java

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

Python

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

PHP

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

.NET

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

Ruby

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

Go

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