Error `ServerVariableMustHaveDefaultValue`, even though the author wanted the variable to be empty

[pomianowski]

Describe the bug
The OpenAPI contract for the Camunda BPMN engine defines a servers section that includes a custom server option with a {url} variable whose default is an empty string:

https://docs.camunda.org/manual/latest/reference/rest/

{
  "url": "{url}",
  "description": "The API server with a custom url",
  "variables": {
    "url": {
      "default": ""
    }
  }
}

This causes an exception to be thrown by the OpenAPI.NET reader, which seems to expect that default values for variables must not be empty strings.

While this is may be a valid OpenAPI document according to the spec, the parser does not handle this edge case gracefully. Other interpreters like NSwagStudio does not have problem with that.

OpenApi File To Reproduce

{
  "openapi": "3.0.2",
  "info": {
    "title": "Camunda Platform REST API",
    "description": "OpenApi Spec for Camunda Platform REST API.",
    "version": "7.22.0",
    "license": {
      "name": "Apache License 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "externalDocs": {
    "description": "Find out more about Camunda Rest API",
    "url": "https://docs.camunda.org/manual/7.22/reference/rest/overview/"
  },
  "servers": [
    {
      "url": "http://{host}:{port}/{contextPath}",
      "description": "The API server for the default process engine",
      "variables": {
        "host": {
          "default": "localhost"
        },
        "port": {
          "default": "8080"
        },
        "contextPath": {
          "default": "engine-rest"
        }
      }
    },
    {
      "url": "http://{host}:{port}/{contextPath}/engine/{engineName}",
      "description": "The API server for a named process engine",
      "variables": {
        "host": {
          "default": "localhost"
        },
        "port": {
          "default": "8080"
        },
        "contextPath": {
          "default": "engine-rest"
        },
        "engineName": {
          "default": "default"
        }
      }
    },
    {
      "url": "{url}",
      "description": "The API server with a custom url",
      "variables": {
        "url": {
          "default": ""
        }
      }
    }
  ],
  "paths": {}

Expected behavior
The OpenAPI.NET reader should allow variables with empty string defaults, or at least fail with a meaningful validation message rather than an exception.

Screenshots/Code Snippets

Additional context

I'm building an OpenAPI client source generator for C#, and I'm using OpenAPI.NET as the foundation for parsing and modeling OpenAPI documents according to the spec. This issue blocks support for compliant but loosely structured documents such as Camunda’s.

[pomianowski]

rel lepoco/openapi.client#1

[baywet]

Hi @pomianowski
Thank you for using the SDK and for reaching out.
Which version of the library are you using? Are you facing the same issue with version 2?

[pomianowski]

Hey @baywet, thanks for following up. I'm currently using version 2.0.0 of Microsoft.OpenApi, as defined here:
https://github.com/lepoco/openapi.client/blob/e207248eaa0da5560adc590287c7177cfbda348d/Directory.Packages.props?plain=1#L12

The failing test is located in the ClientGeneratorTests.cs file:
https://github.com/lepoco/openapi.client/blob/e207248eaa0da5560adc590287c7177cfbda348d/tests/OpenApi.Client.SourceGenerators.UnitTests/ClientGeneratorTests.cs#L18C1-L18C57

For now, I've worked around the issue by adding a space in the JSON here:
https://github.com/lepoco/openapi.client/blob/e207248eaa0da5560adc590287c7177cfbda348d/tests/OpenApi.Client.SourceGenerators.UnitTests/OpenApis/openapi-3.0.2.extended.json#L55

Let me know if you'd like me to isolate this further or provide a minimal repro.

[pomianowski]

Also, some OpenAPI documents I've obtained from various sources include trailing commas, which causes parsing issues with the default reader. To handle these cases, I had to slightly modify the reader to use extended JsonDocumentOptions:

https://github.com/lepoco/openapi.client/blob/e207248eaa0da5560adc590287c7177cfbda348d/src/OpenApi.Client.SourceGenerators/Readers/CustomOpenApiJsonReader.cs#L23

It would be useful if the built-in reader exposed a way to configure JsonDocumentOptions or supported common formatting deviations like this.

[baywet]

Thank you for the additional information.

Nothing in the specification forbids the value from being empty so my understanding is that it should be allowed.

https://spec.openapis.org/oas/v3.1.1.html#server-variable-object

[baywet]

The parsing happens here but I don't think this is the source of the issue.

https://github.com/microsoft/OpenAPI.NET/blob/main/src%2FMicrosoft.OpenApi%2FReader%2FV31%2FOpenApiServerVariableDeserializer.cs#L27

Are you able to get a stack trace?

[microsoft-github-policy-service]

This issue has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 4 days. It will be closed if no further activity occurs within 3 days of this comment.