Include tag_value as discriminator attribute when writing Ash.Type.Union to OpenAPI

[deerob4]

It would be really useful to include more information about union type variants inside the OpenAPI output.

Say that I declare these types:

defmodule Circle do
  use Ash.Resource, data_layer: :embedded

  attributes do
    attribute :radius, :integer, public?: true, allow_nil?: false
  end
end

defmodule Square do
  use Ash.Resource, data_layer: :embedded

  attributes do
    attribute :length, :integer, public?: true, allow_nil?: false
  end
end

defmodule EquilateralTriangle do
  use Ash.Resource, data_layer: :embedded

  attributes do
    attribute :length, :integer, public?: true, allow_nil?: false
  end
end

defmodule Shape do
  use Ash.Type.NewType,
    subtype_of: :union,
    constraints: [
      types: [
        circle: [
          type: Circle,
          tag: :type,
          tag_value: :circle
        ],
        square: [
          type: Square,
          tag: :type,
          tag_value: :square
        ],
        equilaterial_triangle: [
          type: EquilateralTriangle,
          tag: :type,
          tag_value: :triangle
        ],
      ]
    ]
end

As things stand today, the output will be this:

{
  "shape": {
    "anyOf": [
      {
        "properties": {
          "length": {
            "description": "Field included by default.",
            "type": "integer"
          }
        },
        "required": [
          "length"
        ],
        "type": "object"
      },
      {
        "properties": {
          "radius": {
            "description": "Field included by default.",
            "type": "integer"
          }
        },
        "required": [
          "radius"
        ],
        "type": "object"
      }
    ],
    "description": "Field included by default."
  }
}

Notice how it doesn't include the tag_value property defined in the embedded resources, and how Square and EquilaterialTriangle are merged into the same object due to having the same fields.

This is a bit unfortunate, since it throws away information about which variant the data comes from. This is useful information to have when using the OpenAPI specification to generate e.g. TypeScript or Swift types, since these languages can use the discriminator field to narrow down the current variant.

Ideally, I'd like to see this output instead:

{
  "schemas": {
    "Shape": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/Circle"
        },
        {
          "$ref": "#/components/schemas/Square"
        },
        {
          "$ref": "#/components/schemas/EquilateralTriangle"
        }
      ],
      "discriminator": {
        "propertyName": "type",
        "mapping": {
          "circle": "#/components/schemas/Circle",
          "square": "#/components/schemas/Square",
          "triangle": "#/components/schemas/EquilateralTriangle",
        }
      }
    },
    "Circle": {
      "type": "object",
      "required": ["type", "radius"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["circle"]
        },
        "radius": {
          "type": "integer"
        }
      },
    },
    "Square": {
      "type": "object",
      "required": ["type", "length"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["square"]
        },
        "length": {
          "type": "integer"
        }
      } 
    },
    "EquilateralTriangle": {
      "type": "object",
      "required": ["type", "length"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["triangle"]
        },
        "length": {
          "type": "integer"
        }
      } 
    },
  }
}

In this version, the union type has a "discriminator" field, and how "type" has been added as a single enum property to each variant type.

Is this something you think could be useful? I'm happy to have a go at implementing it and making a PR.

[zachdaniel]

It makes sense to set a discriminator on unions where they all share a tag, yeah. We also need to set the tag and tag value into the map while serializing in order for it to be exposed given resources like yours that don't store their type.

Sounds like a good change to me, and like it should be non-breaking.