OpenAPI 3.1.0 file importation fails in Azure APIM

Question

OpenAPI 3.1.0 file importation fails in Azure APIM

Guillaume LUDWIG 5

Hi,

When I try to manually import a OpenAPI 3.1.0 file into the API Management in Azure, it fails and complains that the file isn’t valid :

Parsing error(s): The input OpenAPI file is not valid for the OpenAPI specification https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md(schemahttps://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.yaml).

But my file is OpenAPI 3.1.0, not 3.0.1. In the json, the value "openapi" is "3.1.0".

To my understanding of the documentation, it should support this version.

Any help ?

Regards,

Anonymous

2025-02-06T06:26:51.21+00:00
Hi @Guillaume LUDWIG ,

Welcome to the Microsoft Q&A Platform! Thank you for asking your question here.

The issue you are facing might stem from the fact that while Azure API Management does support OpenAPI version 3.1.0, it only allows for the import of OpenAPI specifications to a limited extent. Specifically, although the import of OpenAPI 3.1.0 is permitted, the error message you received indicates that the system is trying to validate your file against the OpenAPI 3.0.1 schema.

To troubleshoot this issue, make sure that your OpenAPI 3.1.0 file complies with the specifications and does not include any elements that are unsupported by Azure API Management.

There are some limitations and restrictions when importing an API. You can find more information in the following document: https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions

To validate your OpenAPI document locally before importing it to APIM, you can use a third-party tool such as Swagger Editor: https://editor.swagger.io/
Guillaume LUDWIG 5 Reputation points

2025-02-06T08:30:22.28+00:00

Hi @Anonymous ,

thanks for your reply and your time.

My file complies with the OpenAPI 3.1.0 and actually this is the problem. My nullable types are using the ["myType", "null"] syntax but not the Microsoft import system. I’ve successfully imported my json by replacing this with nullable: true. But this is not accepted in strict OpenAPI 3.1 tools sadly (if I read the specifications correctly).

Maybe I’ve missed it in the Microsoft restrictions documentation, but I doesn’t seem to be listed. To me this is not a limitation/restriction but an unsolvable incompatibility between 3.0 and 3.1.
Anonymous

2025-02-11T06:47:08.7733333+00:00
Hi @Guillaume LUDWIG ,

I apologize for the delay in my response and thank you for your understanding.

The issue you're encountering with importing OpenAPI 3.1.0 files into Azure API Management (APIM) may stem from the differences in how nullable types are defined between OpenAPI 3.0 and 3.1. While Azure APIM does support importing OpenAPI 3.1.0 specifications, it has specific limitations and requirements that may not fully align with the OpenAPI 3.1.0 standard.

In your situation, the use of the ["myType", "null"] syntax for nullable types is not recognized by Azure APIM, which prefers the nullable: true syntax. This discrepancy can result in validation errors during the import process. Unfortunately, this is a known limitation when working with OpenAPI specifications in Azure APIM.

To resolve this issue, you may need to modify your OpenAPI 3.1.0 file to meet Azure APIM's requirements, such as replacing the nullable type definitions with the supported syntax. If making these adjustments is not feasible for your use case, you might need to explore alternative approaches or tools that offer better support for OpenAPI 3.1.0 without these limitations.

To help you better understand, kindly refer to the documentation below:

API import restrictions and known issues

I hope this helps! Let me know if you have any further questions or need additional assistance.
Anonymous

2025-02-12T06:17:15.0933333+00:00

Hi @Guillaume LUDWIG ,

Just checking in to see if the information above was helpful. If you have any further updates on this issue, please feel free to post them here.
Anonymous

2025-02-13T05:18:57.03+00:00

Hi @Guillaume LUDWIG ,

Following up to see if you have chance to check my previous response and help us with requested information to check and assist you further on this.
Guillaume LUDWIG 5 Reputation points

2025-02-13T09:13:25.4766667+00:00
Hi @Anonymous ,

No worry for the delay.

Yes this is my understanding of the issue. The problem is ["myType, "null"] is the 3.1 nullable, and nullable: true is the 3.0 nullable ; and they are mutually exclusive. If I use the 3.0 nullable in a 3.1 file, even if Azure APIM supports it other tools won’t.

So I can’t modify my 3.1 file to use the 3.0 nullable because it would break elsewhere (outside Azure APIM). This is not "supporting 3.1 with some limitations". If 3.1 had some features A and B on top on the 3.0 syntax it would be ok to not support feature B, but we’re not in this case. The nullable is specified in two incompatible ways between 3.0 and 3.1, so asking for the 3.0 syntax in a 3.1 file is a bug.

To resolve this issue, Microsoft has to : 

fix the nullable (and maybe some other things) in the 3.1 import, or

stop saying it supports 3.1 because it is factually false

In the documentation you linked (https://github.com/rust-lang/rust-analyzer/pull/18934) it doesn’t specify this issue, this is a big problem.

Is there a way to file a bug report somewhere ?

Regards
Anonymous

2025-02-13T09:39:40.2966667+00:00

Hi @Guillaume LUDWIG ,

Thanks for your patience on this.

We noticed your recent experience on the Q&A community platform was rated low (Answer provided was not helpful).Thank you for taking time to share your feedback. Kindly let us know what we could have done better to make your experience a positive one.

We are here to help you and strive to make your experience better and **greatly value your feedback. **

Regarding your question related to any workaround --> I am checking with team internally and will update you here once I hear back from them.

We would appreciate if you may consider re-surveying for the engagement you received on the thread by

Your feedback is very important to us.
RChotu 3,210 Reputation points Microsoft External Staff Moderator

2025-02-20T03:26:18.0933333+00:00

Can you provide your input that your using or importing it. There might be other issues.
RChotu 3,210 Reputation points Microsoft External Staff Moderator

2025-02-20T06:20:42.83+00:00

You can use "test": ["string : null"] instead of ["myType", "null"]. Also please provide the details requested in Private chat
RChotu 3,210 Reputation points Microsoft External Staff Moderator

2025-02-21T07:39:54.7166667+00:00

Just checking to see if you have tried the above approach, else please let us know the details as requested
Guillaume LUDWIG 5 Reputation points

2025-05-15T10:12:08.2233333+00:00

Hi, did you saw my comment from the March 14th ?
Guillaume LUDWIG 5 Reputation points

2025-07-01T08:23:14.49+00:00

up…

Yes @RChotu I tried it, and it help for Azure APIM. But… it is NOT compatible with OpenAPI 3.1 thus it won’t work in any other tool which is not acceptable.

4 answers

Your answer

Anonymous

2025-02-06T06:26:51.21+00:00

Hi @Guillaume LUDWIG ,

Welcome to the Microsoft Q&A Platform! Thank you for asking your question here.

The issue you are facing might stem from the fact that while Azure API Management does support OpenAPI version 3.1.0, it only allows for the import of OpenAPI specifications to a limited extent. Specifically, although the import of OpenAPI 3.1.0 is permitted, the error message you received indicates that the system is trying to validate your file against the OpenAPI 3.0.1 schema.

To troubleshoot this issue, make sure that your OpenAPI 3.1.0 file complies with the specifications and does not include any elements that are unsupported by Azure API Management.

There are some limitations and restrictions when importing an API. You can find more information in the following document: https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions

To validate your OpenAPI document locally before importing it to APIM, you can use a third-party tool such as Swagger Editor: https://editor.swagger.io/
Guillaume LUDWIG 5 Reputation points

2025-02-06T08:30:22.28+00:00

Hi @Anonymous ,

thanks for your reply and your time.

My file complies with the OpenAPI 3.1.0 and actually this is the problem. My nullable types are using the ["myType", "null"] syntax but not the Microsoft import system. I’ve successfully imported my json by replacing this with nullable: true. But this is not accepted in strict OpenAPI 3.1 tools sadly (if I read the specifications correctly).

Maybe I’ve missed it in the Microsoft restrictions documentation, but I doesn’t seem to be listed. To me this is not a limitation/restriction but an unsolvable incompatibility between 3.0 and 3.1.
Anonymous

2025-02-11T06:47:08.7733333+00:00

Hi @Guillaume LUDWIG ,

I apologize for the delay in my response and thank you for your understanding.

The issue you're encountering with importing OpenAPI 3.1.0 files into Azure API Management (APIM) may stem from the differences in how nullable types are defined between OpenAPI 3.0 and 3.1. While Azure APIM does support importing OpenAPI 3.1.0 specifications, it has specific limitations and requirements that may not fully align with the OpenAPI 3.1.0 standard.

In your situation, the use of the ["myType", "null"] syntax for nullable types is not recognized by Azure APIM, which prefers the nullable: true syntax. This discrepancy can result in validation errors during the import process. Unfortunately, this is a known limitation when working with OpenAPI specifications in Azure APIM.

To resolve this issue, you may need to modify your OpenAPI 3.1.0 file to meet Azure APIM's requirements, such as replacing the nullable type definitions with the supported syntax. If making these adjustments is not feasible for your use case, you might need to explore alternative approaches or tools that offer better support for OpenAPI 3.1.0 without these limitations.

To help you better understand, kindly refer to the documentation below:

API import restrictions and known issues

I hope this helps! Let me know if you have any further questions or need additional assistance.
Anonymous

2025-02-12T06:17:15.0933333+00:00

Hi @Guillaume LUDWIG ,

Just checking in to see if the information above was helpful. If you have any further updates on this issue, please feel free to post them here.
Anonymous

2025-02-13T05:18:57.03+00:00

Hi @Guillaume LUDWIG ,

Following up to see if you have chance to check my previous response and help us with requested information to check and assist you further on this.
Guillaume LUDWIG 5 Reputation points

2025-02-13T09:13:25.4766667+00:00

Hi @Anonymous ,

No worry for the delay.

Yes this is my understanding of the issue. The problem is ["myType, "null"] is the 3.1 nullable, and nullable: true is the 3.0 nullable ; and they are mutually exclusive. If I use the 3.0 nullable in a 3.1 file, even if Azure APIM supports it other tools won’t.

So I can’t modify my 3.1 file to use the 3.0 nullable because it would break elsewhere (outside Azure APIM). This is not "supporting 3.1 with some limitations". If 3.1 had some features A and B on top on the 3.0 syntax it would be ok to not support feature B, but we’re not in this case. The nullable is specified in two incompatible ways between 3.0 and 3.1, so asking for the 3.0 syntax in a 3.1 file is a bug.

To resolve this issue, Microsoft has to : 

fix the nullable (and maybe some other things) in the 3.1 import, or

stop saying it supports 3.1 because it is factually false

In the documentation you linked (https://github.com/rust-lang/rust-analyzer/pull/18934) it doesn’t specify this issue, this is a big problem.

Is there a way to file a bug report somewhere ?

Regards
Anonymous

2025-02-13T09:39:40.2966667+00:00

Hi @Guillaume LUDWIG ,

Thanks for your patience on this.

We noticed your recent experience on the Q&A community platform was rated low (Answer provided was not helpful).Thank you for taking time to share your feedback. Kindly let us know what we could have done better to make your experience a positive one.

We are here to help you and strive to make your experience better and **greatly value your feedback. **

Regarding your question related to any workaround --> I am checking with team internally and will update you here once I hear back from them.

We would appreciate if you may consider re-surveying for the engagement you received on the thread by

Your feedback is very important to us.
RChotu 3,210 Reputation points Microsoft External Staff Moderator

2025-02-20T03:26:18.0933333+00:00

Can you provide your input that your using or importing it. There might be other issues.
RChotu 3,210 Reputation points Microsoft External Staff Moderator

2025-02-20T06:20:42.83+00:00

You can use "test": ["string : null"] instead of ["myType", "null"]. Also please provide the details requested in Private chat
RChotu 3,210 Reputation points Microsoft External Staff Moderator

2025-02-21T07:39:54.7166667+00:00

Just checking to see if you have tried the above approach, else please let us know the details as requested
Guillaume LUDWIG 5 Reputation points

2025-05-15T10:12:08.2233333+00:00

Hi, did you saw my comment from the March 14th ?
Guillaume LUDWIG 5 Reputation points

2025-07-01T08:23:14.49+00:00

up…

Yes @RChotu I tried it, and it help for Azure APIM. But… it is NOT compatible with OpenAPI 3.1 thus it won’t work in any other tool which is not acceptable.

Answer 1

We are in the same position. We have bumped to .NET 10 and attempting to be good and keep current with our packages but are unable to publish to APIM. May you please provide a roadmap for when APIM will support publishing of Open API 3.1 schema?

In the meantime, should anyone else stumble over this, you can use the following options to stay with the latest package but specify the schema version produced:

Via DI registration which will only affect the document served up at runtime:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
});

Via csproj which will affect the documents generated at build time if you are doing so:

<OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_0</OpenApiGenerateDocumentsOptions>

Answer 2

Gerard C 0

With the release of NET 10 and Microsoft.OpenApi generating 3.1 by default, full 3.1 support is even more important. I just tested migration from Swagger to Microsoft.OpenAPI v3.1 only to have it fail on the APIM import.

Do you have any update on plans to fully support the OpenAPI 3.1 generated by Microsoft.OpenAPI?

Thanks,

--Gerard

Guillaume LUDWIG 5 Reputation points

2025-11-27T09:00:30.4266667+00:00

Exactly, I’ve also tested with .NET 10 and the resulting OpenAPI file is rejected by the Azure APIM. I guess the number of people complaining will sky rocket.

Answer 3

Kishore Srirama 0

Hi @Shireesha Eeraboina ,

Do we have an update when Azure APIM will support Open API 3.1 ?

Regards,

Kishore.S

0 comments

Answer 4

Hi, my turn to say sorry for the delay @Anonymous and @RChotu

Here is a minimal example of a OpenAPI 3.1 file with only one nullable property : 

{
  "openapi": "3.1.0",
  "info": {
    "title": "Test",
    "version": "1"
  },
  "paths": {
    "/test_path": {
      "get": {
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/myObject"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "myObject": {
        "type": "object",
        "properties": {
          "myProperty": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}

It has been generated with https://editor-next.swagger.io/ and the result is correctly displayed on it as shown in the attached image. And it works as expected elsewhere (internal tooling, openapi viewers, etc).microsoft_openapi_issue.png

Except it won’t work on Azure APIM, I attached an image of the error during import.[azure_apim_import_error.png](/api/attachments/42479827-df07-4570-abcd-9e2fd6ac5ca6?platform=QnA)

I’m quite sure this is a bug in Azure APIM, because the example is valid OpenAPI 3.1 data, and none of the "limitations" listed on APIM documentation are used here. Plus this is really a trivial example, only a single array of an object containing one nullable string.

Does it help you ?

Share via

OpenAPI 3.1.0 file importation fails in Azure APIM

4 answers

Your answer