OpenApiSchema.Serialize does not fully resolve references

[muecahit-uzun]

Swagger file for reproduction: Microsoft WorkItemTracking Sagger JSON

Hi,

something is wrong with serialization or I am missing something. When you try to serialize an OpenApiSchema instance, with OpenApiSchema.Serialze, OpenApiSchema.SerializeAsV2 or OpenApiSchema.SerializeAsV3 it does not fully resolve references. If you check the parsed OpenApiDocument instance, everthing is resolved and fine.

Code is something like this:

var settings = new OpenApiReaderSettings() { ReferenceResolution = ReferenceResolutionSetting.ResolveLocalReferences };
var openApiDocument = new OpenApiStringReader(settings).Read(documentAsString, out var diagnostic);

OpenApiSchema schema = GetSchema(); // get response schema instance at line 6453

var sb = new StringBuilder();
var writer = new OpenApiJsonWriter(new StringWriter(sb), new OpenApiWriterSettings { ReferenceInline = ReferenceInlineSetting.InlineLocalReferences });

schema.Serialize(writer, diagnostic.SpecificationVersion);

string serializedSchema = sb.ToString(); // Not fully resolved

When I serialize the OpenApiSchema instance with e.g. System.Text.Json.JsonSerializer, it works.

[muecahit-uzun]

I did a little bit of debugging and I think the LoopDetector falsely detects a loop. Somewhere about Microsoft.OpenApi.Models.OpenApiSchema Line 455

[darrelmiller]

When you say "it does not fully resolve references" do you mean that it doesn't inline the reference? i.e. Are you seeing the $ref appearing in the serialized string? If so, that is by design. Resolving and inlining are distinct features. Resolving replaces the unresolved reference with the object from the components collection, but still maintains the fact that a $ref was used. This is so that we can round trip documents with $ref. Inlining can be achieved by using the OpenAPIWriter and setting the inlining setting.

[muecahit-uzun]

{
  "swagger": "2.0",
  "info": {
    "title": "WorkItemTracking",
    "description": "",
    "termsOfService": "https://go.microsoft.com/fwlink/?LinkId=329770",
    "contact": {
      "name": "nugetvss",
      "email": "nugetvss@microsoft.com"
    },
    "license": {
      "name": "MICROSOFT SOFTWARE LICENSE TERMS",
      "url": "https://go.microsoft.com/fwlink/?LinkId=329770"
    },
    "version": "6.1-preview"
  },
  "host": "dev.azure.com",
  "x-ms-vss-area": "WorkItemTracking",
  "x-ms-vss-resource-area-id": "5264459e-e5e0-4bd8-b118-0985e68a4ec5",
  "basePath": "/",
  "paths": {
    "/{organization}/{project}/{team}/_apis/wit/wiql": {
      "post": {
        "description": "Gets the results of the query given its WIQL.",
        "operationId": "Wiql_Query By Wiql",
        "responses": {
          "200": {
            "description": "successful operation",
            "schema": {
              "$ref": "#/definitions/WorkItemQueryResult"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "WorkItemFieldReference": {
      "description": "Reference to a field in a work item",
      "type": "object",
      "properties": {
        "name": {
          "description": "The friendly name of the field.",
          "type": "string"
        },
        "referenceName": {
          "description": "The reference name of the field.",
          "type": "string"
        },
        "url": {
          "description": "The REST URL of the resource.",
          "type": "string"
        }
      }
    },
    "WorkItemLink": {
      "description": "A link between two work items.",
      "type": "object",
      "properties": {
        "rel": {
          "description": "The type of link.",
          "type": "string"
        },
        "source": {
          "description": "The source work item.",
          "$ref": "#/definitions/WorkItemReference"
        },
        "target": {
          "description": "The target work item.",
          "$ref": "#/definitions/WorkItemReference"
        }
      }
    },
    "WorkItemQueryResult": {
      "description": "The result of a work item query.",
      "type": "object",
      "properties": {
        "asOf": {
          "description": "The date the query was run in the context of.",
          "type": "string",
          "format": "date-time"
        },
        "columns": {
          "description": "The columns of the query.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/WorkItemFieldReference"
          }
        },
        "queryResultType": {
          "description": "The result type",
          "enum": [
            "workItem",
            "workItemLink"
          ],
          "x-ms-enum": {
            "name": "QueryResultType",
            "values": [
              {
                "value": "workItem",
                "description": "A list of work items (for flat queries)."
              },
              {
                "value": "workItemLink",
                "description": "A list of work item links (for OneHop and Tree queries)."
              }
            ]
          }
        },
        "queryType": {
          "description": "The type of the query",
          "enum": [
            "flat",
            "tree",
            "oneHop"
          ],
          "x-ms-enum": {
            "name": "QueryType",
            "values": [
              {
                "value": "flat",
                "description": "Gets a flat list of work items."
              },
              {
                "value": "tree",
                "description": "Gets a tree of work items showing their link hierarchy."
              },
              {
                "value": "oneHop",
                "description": "Gets a list of work items and their direct links."
              }
            ]
          }
        },
        "sortColumns": {
          "description": "The sort columns of the query.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/WorkItemQuerySortColumn"
          }
        },
        "workItemRelations": {
          "description": "The work item links returned by the query.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/WorkItemLink"
          }
        },
        "workItems": {
          "description": "The work items returned by the query.",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "description": "Work item ID.",
                "type": "number"
              },
              "url": {
                "description": "REST API URL of the resource",
                "type": "string"
              }
            }
          }
        }
      }
    },
    "WorkItemQuerySortColumn": {
      "description": "A sort column.",
      "type": "object",
      "properties": {
        "descending": {
          "description": "The direction to sort by.",
          "type": "boolean"
        },
        "field": {
          "description": "A work item field.",
          "$ref": "#/definitions/WorkItemFieldReference"
        }
      }
    },
    "WorkItemReference": {
      "description": "Contains reference to a work item.",
      "type": "object",
      "properties": {
        "id": {
          "description": "Work item ID.",
          "type": "string"
        },
        "url": {
          "description": "REST API URL of the resource",
          "type": "string"
        }
      }
    }
  }
}

I mean inline. Please check the only path's response above. It is a schema referencing an object WorkItemQueryResult in definitions. When I try to serialize this schema object, it would inline the object defined below in the definitions section. But this object below has also parts of its definition as a reference to some other object. But those will stay as a reference and are not inlined.

This is the result:

{
  "description": "The result of a work item query.",
  "type": "object",
  "properties": {
    "asOf": {
      "format": "date-time",
      "description": "The date the query was run in the context of.",
      "type": "string"
    },
    "columns": {
      "description": "The columns of the query.",
      "type": "array",
      "items": {
        "description": "Reference to a field in a work item",
        "type": "object",
        "properties": {
          "name": {
            "description": "The friendly name of the field.",
            "type": "string"
          },
          "referenceName": {
            "description": "The reference name of the field.",
            "type": "string"
          },
          "url": {
            "description": "The REST URL of the resource.",
            "type": "string"
          }
        }
      }
    },
    "queryResultType": {
      "description": "The result type",
      "enum": [
        "workItem",
        "workItemLink"
      ],
      "x-ms-enum": {
        "name": "QueryResultType",
        "values": [
          {
            "value": "workItem",
            "description": "A list of work items (for flat queries)."
          },
          {
            "value": "workItemLink",
            "description": "A list of work item links (for OneHop and Tree queries)."
          }
        ]
      }
    },
    "queryType": {
      "description": "The type of the query",
      "enum": [
        "flat",
        "tree",
        "oneHop"
      ],
      "x-ms-enum": {
        "name": "QueryType",
        "values": [
          {
            "value": "flat",
            "description": "Gets a flat list of work items."
          },
          {
            "value": "tree",
            "description": "Gets a tree of work items showing their link hierarchy."
          },
          {
            "value": "oneHop",
            "description": "Gets a list of work items and their direct links."
          }
        ]
      }
    },
    "sortColumns": {
      "description": "The sort columns of the query.",
      "type": "array",
      "items": {
        "description": "A sort column.",
        "type": "object",
        "properties": {
          "descending": {
            "description": "The direction to sort by.",
            "type": "boolean"
          },
          "field": {
            "$ref": "#/definitions/WorkItemFieldReference"
          }
        }
      }
    },
    "workItemRelations": {
      "description": "The work item links returned by the query.",
      "type": "array",
      "items": {
        "description": "A link between two work items.",
        "type": "object",
        "properties": {
          "rel": {
            "description": "The type of link.",
            "type": "string"
          },
          "source": {
            "description": "Contains reference to a work item.",
            "type": "object",
            "properties": {
              "id": {
                "description": "Work item ID.",
                "type": "string"
              },
              "url": {
                "description": "REST API URL of the resource",
                "type": "string"
              }
            }
          },
          "target": {
            "$ref": "#/definitions/WorkItemReference"
          }
        }
      }
    },
    "workItems": {
      "description": "The work items returned by the query.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Work item ID.",
            "type": "number"
          },
          "url": {
            "description": "REST API URL of the resource",
            "type": "string"
          }
        }
      }
    }
  }
}

As you can see in my code example on the top, I am setting the inline settings. What am I doing wrong? My expectation would be, that every reference would get inlined.

[MaggieKimani1]

Closing the issue as this seems to be working correctly using the following code snippet:

 // Arrange
 var outputStringWriter = new StringWriter(CultureInfo.InvariantCulture);
 var writer = new OpenApiJsonWriter(outputStringWriter, new() { Terse = false });

 // Act
 using var stream = Resources.GetStream(Path.Combine(SampleFolderPath, "testDoc.json"));
 var doc = new OpenApiStreamReader().Read(stream, out var diags);

 var schema = doc.Paths["/{organization}/{project}/{team}/_apis/wit/wiql"].Operations[OperationType.Post].Responses["200"].Content["application/octet-stream"].Schema;
 schema.SerializeAsV2(writer);
 var fieldSchema = schema.Properties["sortColumns"].Items.Properties["field"];
 var targetSchema = schema.Properties["workItemRelations"].Items.Properties["target"];

 Assert.False(fieldSchema.UnresolvedReference);
 Assert.False(targetSchema.UnresolvedReference);