handle "dirty" documents

There are many (many, many) ways for OpenAPI documents to be not quite right. This issue is intended to collect the non-conforming issues we've seen in the wild. We have two options for how to address them:

• extend progenitor/typify to handle those constructs, possibly under some "permissive" mode or with flags to accept various types of permissiveness
• build a tool to "clean" documents

The former would be a nicer OOB experience for progenitor and typify, but it might booger up the code (quite a lot) to handle all kinds of weirdo constructions inline. The latter might have the benefit of showing users the specific cleaning delta that occurred to their document. And there is the opportunity to invoke such a tool (or library) from progenitor/typify which might be the best of both worlds: ease of use, optional application, keeping the code free from out-of-spec special casing.

When adding to this list include:

• a description of the problem and consequence
• a link of the issue in the wild
• an example
• the proposed remediation algorithm

Enumerated values that don't conform to the schema but would with a string -> value conversion

Sometimes enumerated values don't actually conform e.g. the type is an integer, but the value is "7". We reject those schemas as invalid because the enumerated value isn't valid.

Seen here: https://github.com/Bungie-net/api/blob/6a7d761ae032ed9df9dfac149832c71c4a987d7d/openapi.json

      {
        "type": "integer",
        "format": "int64",
        "enum": [
          "1",
          "2",
          "4",
          "8",
        ]
     }

It should be possible to have a heuristic where we say "let's try serde_json::Value::from_str(value) and if that works out and is valid, then let's use it!"

Nesting within $defs

Sometimes schemas creating a "nesting" structure under $defs to group types (e.g.) by category or use or whatever. This isn't really valid (i.e. because values within $defs are supposed to be schemas not... object that contain schemas) and the result is that we don't find them and fail to resolve $refs to them.

Seen here: https://lottiefiles.github.io/lottie-docs/schema/lottie.schema.json

    "$defs": {
        "animated-properties": {
            "animated-property": {
                "type": "object",

We could chase valid $refs and remove the layer of indirection under $defs; we could further strip out the remaining $defs contents that are unreferenced and/or trivial e.g. "animated-properties": {}

Missing operationIds

Some specs lack the operationId field. We could generate those based on unique data such as the path and method... albeit with care around path parameters to avoid conflicts.

The issue names no source files, tests, or entry point; start by reading progenitor and typify's handling of invalid OpenAPI documents and the three listed cases. Define whether permissive handling or a cleaning tool is in scope, then verify the chosen approach against the enumerated-value, nested-$defs, and missing-operationId examples.