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?

[baywet]

Hi mdaneri,

Thank you for using the SDK and for reaching out.

I think we need to break this down further:

OpenAPI 2 & 3.0

For any kind of reference (schema, path item, etc..), no sibling keyworks (description, summary, anything really) are allowed. We should drop them during serialization. Extension are not allowed either.

Source specification for v2

Source specification for v3

OpenAPI 3.1 & 3.2

For JSON Schema references, any keyword that's defined as a "peer keyword" can appear alongside the $ref property. That's effectively anything that has a setter in the reference type. Extensions are also allowed.

Source for schema object

For any other kind of reference (path item, etc...), ONLY summary and description are allowed alongside with $ref. Anything else (extensions included) is prohibited and should be dropped during serialization.

source

Note: the specification technically says any properties added SHALL be ignored. So it's technically valid for those properties to be present, but ignored by the tooling. In practical terms, most tooling, especially linters, probably warns the user upon seeing those properties, or even errors out. So best drop those properties.