[Schema Inaccuracy] Consider using discriminator properties for union types

[baywet]

Schema Inaccuracy

GET /repos/{owner}/{repo}/contents/{path}

Was recently updated from a single "object" schema to

application/json:
              schema:
                oneOf:
                - "$ref": "#/components/schemas/content-directory"
                - "$ref": "#/components/schemas/content-file"
                - "$ref": "#/components/schemas/content-symlink"
                - "$ref": "#/components/schemas/content-submodule"

While this is great to #650 's point as it more accurately describes the possible values, it also makes deserialization work on client applications much harder.

Expected

Consider adding something along the lines of

discriminator:
            propertyName: newPropertyName
            mapping:
              content-file: "#/components/schemas/content-file"
              content-submodule: "#/components/schemas/content-submodule"
              content-symlink: "#/components/schemas/content-symlink"

(this would require introducing a new property if one with the mapping values doesn't already exist)

This way client applications can match the discrimator mapping value with the object type during deserialization.

Reproduction Steps

[nickfloyd]

Closing due to the issue becoming stale. Please re open if you feel like this still needs to be addressed.

[WyriHaximus]

Still think this would be very valuable

[nickfloyd]

Hey @WyriHaximus & @baywet I have transferred this issue to the internal owning team to get their 👀 on it.

[WyriHaximus]

Awesome, thank you for that @nickfloyd!