Enhancement: Allow `Parameter(schema_extra=...)` / `ResponseSpec(schema_extra=...)`

[tuukkamustonen]

Summary

Pydantic provides Field(json_schema_extra=...) which allows to do something like:

def forbid_internal_labels(value):
    if re.match(r"^reserved-for-internal-use:.*$", value):
        raise ValueError(...)

class Foo(BaseModel):
    label: Annotated[str, AfterValidator(forbid_internal_labels), Field(json_schema_extra={
        "not": {
            {
                "type": "string",
                "pattern": "^reserved-for-internal-use:.*$"
            },
        }
    })]

This would generate:

                "type": "string",
                "not": {
                    {
                        "type": "string",
                        "pattern": "^reserved-for-internal-use:.*$"
                    },
                }

It doesn't actually add/do any validation, it merely impacts the generated JSON schema.

Similar mechanism is needed for Parameter, to inject discriminators (e.g. anyOf, not) into the OpenAPI spec (although the validation is decoupled from the schema declaration).

The builtin generation uses oneOf for union types (IIRC Pydantic uses anyOf for those). But I don't think it's possible to declare something like above.

Workarounds at this point would be:

• To adjust via custom Operation class (did not try but I assume it could work)
• To adjust the OpenAPI generation on a more global level (by extending OpenAPIPlugin?)

Both are quite ugly hacks, while something like this should be supported out-of-the-box.

Basic Example

No response

Drawbacks and Impact

No response

Unresolved questions

No response

---

[!NOTE]
While we are open for sponsoring on GitHub Sponsors and OpenCollective, we also utilize Polar.sh to engage in pledge-based sponsorship.

Check out all issues funded or available for funding on our Polar.sh dashboard

• If you would like to see an issue prioritized, make a pledge towards it!
• We receive the pledge once the issue is completed & verified
• This, along with engagement in the community, helps us know which features are a priority to our users.

[tuukkamustonen]

As mentioned in https://github.com/litestar-org/litestar/issues/3018#issuecomment-1924002760 Parameter(schema_extra=...) could be supported, and that's what this ticket is about.

Having an independent schema_extra for Parameter seems fine though.

I guess ResponseSpec(schema_extra=...) should exist, too.

[tuukkamustonen]

Parameter(shema_extra=...) has been merged in https://github.com/litestar-org/litestar/pull/3204.

It did not add the same for ResponseSpec, however (due to technical difficulties, see the PR description).