Limitations of OpenAPI Spec with Complex Objects in Copilot Declarative Agents

Introduction

In a previous post, I detailed the steps for Building a Copilot Agent with Microsoft 365 Agents Toolkit and Microsoft Graph Plugin to list my ToDo Tasks. However, I encountered issues with the CreateTask function when using an OpenAPI spec generated with Kiota. Upon investigation, I identified the problem as being related to the handling of complex objects, particularly those involving dates. Even after simplifying the object structure, the CreateTask function continued to fail.

Open API Spec

Below is an excerpt from the OpenAPI spec for the CreateTask function, highlighting the body and dueDateTime properties from Ms Graph:

body:
          type: object
          nullable: true
          properties:
            content:
              type: string
              example: ""
            contentType:
              type: string
              example: "text"
        dueDateTime:
          type: object
          nullable: true
          description: >-
              The due date and time for the task. The time is in the user's time zone. 
              If the user has not set a time zone, the default is UTC. 
              **Do not include this property in the request body if it is empty.**              
          x-omit-if-empty: true
          properties:
            dateTime:
              type: string
              format: date-time
              example: "2021-07-11T09:00:00.0000000"
            timeZone:
              type: string
              default: "Europe/London"
              example: "Australia/Sydney"

Problem

For object properties like dueDateTime, the OpenAPI spec even if attributes such as nullable: true and x-omit-if-empty: true to indicate that the property should be excluded from the request body if it is empty, they do not seem to work as expected in practice.

Even when dueDateTime is not provided, it is still included in the request body, causing the API call to fail. This behavior is particularly problematic for properties like dates, where the API explicitly requires them to be omitted if empty.

Example Issue

The dueDateTime object is included in the request body even when it is empty, as shown below:

Due Date Time object not optional

Workaround

To address this limitation, a middleware or preprocessing layer is required to ensure that the JSON payload sent to the API is correctly formatted. This middleware can dynamically remove empty or nullable properties from the request body before it is sent to the API.

Conclusion

While OpenAPI specifications provide a robust framework for defining APIs, they have limitations when dealing with complex objects like dates. Attributes such as nullable: true and x-omit-if-empty: true may not always behave as expected, leading to issues with API calls.

For better control over updating tasks or handling similar scenarios, implementing a middleware or preprocessing layer is essential to ensure that the JSON payload adheres to the API’s requirements. This approach can help overcome the limitations of OpenAPI specs and improve the reliability of your Copilot declarative agents.

References