Skip to content

OpenApiSchemaReference allows Description alongside $ref producing non-spec-compliant output in OAS 3.0 #2745

Description

@mdaneri

Description

The Microsoft.OpenApi library allows setting Description on OpenApiSchemaReference, which results in serialized output containing both $ref and description.

However, according to OpenAPI 3.0.x specification:

When a $ref is used, all other properties SHALL be ignored.

This makes $ref effectively a replacement, meaning sibling keywords like description should not appear.


Example

Code

using System;
using System.IO;
using Microsoft.OpenApi.Models;
using Microsoft.OpenApi.Writers;

class Program
{
    static void Main()
    {
        var document = new OpenApiDocument
        {
            Info = new OpenApiInfo
            {
                Title = "Ref Description Test",
                Version = "1.0.0"
            },

            Components = new OpenApiComponents
            {
                Schemas =
                {
                    ["Pet"] = new OpenApiSchema
                    {
                        Type = "object",
                        Properties =
                        {
                            ["name"] = new OpenApiSchema { Type = "string" }
                        }
                    }
                }
            },

            Paths = new OpenApiPaths
            {
                ["/test"] = new OpenApiPathItem
                {
                    Operations =
                    {
                        [OperationType.Get] = new OpenApiOperation
                        {
                            Responses =
                            {
                                ["200"] = new OpenApiResponse
                                {
                                    Description = "OK",
                                    Content =
                                    {
                                        ["application/json"] = new OpenApiMediaType
                                        {
                                            Schema = new OpenApiSchemaReference("Pet")
                                            {
                                                Description = "Local description"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        };

        using var stream = new MemoryStream();
        using var writer = new OpenApiJsonWriter(new StreamWriter(stream));

        document.SerializeAsV3(writer);
        writer.Flush();

        stream.Position = 0;
        Console.WriteLine(new StreamReader(stream).ReadToEnd());
    }
}

Output

$ref: '#/components/schemas/Pet'
description: Local description

Expected behavior

One of:

  1. Serializer wraps in allOf
allOf:
  - $ref: '#/components/schemas/Pet'
description: Local description
  1. Description ignored when targeting OAS 3.0

  2. Validation warning


Notes

  • In OAS 3.1 sibling keywords are allowed due to JSON Schema alignment
  • Behavior difference between 3.0 and 3.1 is currently unclear
  • This can lead to portability issues across tooling

Question

What is the intended behavior when serializing references with annotations for OAS 3.0 vs 3.1?

Activity

baywet commented on Feb 20, 2026

@baywet
Member

Hi mdaneri
Thank you for using the SDK and for reaching out.

The snippet you've provided looks like a 1.X code snippet, for which we don't provide support anymore.

Could you please provide an updated snippet? As well as validate you're facing this issue with 2.x or 3.x?

Thanks!

Let us know if you have any additional comments or questions.

microsoft-github-policy-service commented on Feb 25, 2026

@microsoft-github-policy-service
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions