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

[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

var schema = new OpenApiSchema
{
    Reference = new OpenApiReference
    {
        Type = ReferenceType.Schema,
        Id = "Pet"
    },
    Description = "Local description"
};

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

---

Question

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

[baywet]

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.