title: Writing OpenAPI schema and generating client code for HTTP API that responds with polymorphic array
body: <p>I'm trying to write an OpenAPI 3.0 schema for an HTTP API. One of its requests responds with a polymorphic array of objects something like this:</p>
  <pre class="lang-json prettyprint-override"><code>[
    {
      &quot;type&quot;: &quot;Base&quot;,
      &quot;properties&quot;: {
        &quot;baseProp1&quot;: &quot;Alpha&quot;,
        &quot;baseProp2&quot;: &quot;Bravo&quot;,
        &quot;baseProp3&quot;: &quot;Charlie&quot;
      }
    },
    {
      &quot;type&quot;: &quot;Derived&quot;,
      &quot;properties&quot;: {
        &quot;baseProp1&quot;: &quot;Delta&quot;,
        &quot;baseProp2&quot;: &quot;Echo&quot;,
        &quot;baseProp3&quot;: &quot;Foxtrot&quot;,
        &quot;derivedPropA&quot;: &quot;Golf&quot;
      }
    }
  ]
  </code></pre>
  <p>In other words, the response can be an array of <code>Base</code> objects and/or <code>Derived</code> objects, which is derived from <code>Base</code>. The exact names and properties are different to the actual API in question, but convention for representing object inheritance is the same.</p>
  <p>I have a number of questions related to this:</p>
  <ol>
  <li>I notice that the properties for the objects are wrapped in a <code>&quot;properties&quot;</code> property. Is the example above a JSON compliant way for an HTTP API to serialize polymorphic arrays?</li>
  <li>Will a typical API code generator be able to deserialize this correctly? The particular code generator I'm using is <a href="https://devblogs.microsoft.com/dotnet/generating-http-api-clients-using-visual-studio-connected-services/" rel="nofollow noreferrer">Visual Studio's 2022 build-in OpenAPI 'connected service'</a> generator (essentially <em>NSwag</em>). Ideally I would want the generated classes for <code>Base</code> and <code>Derived</code> not to expose the fact that the JSON they were deserialized from had their properties wrapped in <code>&quot;properties&quot;</code> (i.e. <code>BaseProp1</code>, <code>BaseProp2</code>, etc. are defined on the class itself`)</li>
  <li>Assuming my code generator can accommodate this, is there a particular way I must define the response in the OpenAPI schema for it to do this correctly?</li>
  </ol>
  <p>Preferably, I'd like to use the generated C# client code as-is, but I'm open to extending it (via partial class) if need be.</p>
  <p>I admit, I could (and will) do more research around the technologies involved, in particular Newtonsoft Json.NET used in client code, but I wanted to submit the question first.</p>