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

[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

2. Description ignored when targeting OAS 3.0

3. 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

• This is a clone of OpenApiSchemaReference allows Description alongside $ref producing non-spec-compliant output in OAS 3.0 #2745

---

Question

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