go-openapi
diff --git a/‎.golangci.yml‎
Lines changed: 2 additions & 0 deletions b/‎.golangci.yml‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎client/runtime.go‎
Lines changed: 30 additions & 10 deletions b/‎client/runtime.go‎
Lines changed: 30 additions & 10 deletions
diff --git a/‎constants.go‎
Lines changed: 6 additions & 2 deletions b/‎constants.go‎
Lines changed: 6 additions & 2 deletions
diff --git a/‎docs/MEDIA_TYPES.md‎
Lines changed: 111 additions & 0 deletions b/‎docs/MEDIA_TYPES.md‎
Lines changed: 111 additions & 0 deletions
diff --git a/‎middleware/context.go‎
Lines changed: 42 additions & 3 deletions b/‎middleware/context.go‎
Lines changed: 42 additions & 3 deletions
diff --git a/‎middleware/validation.go‎
Lines changed: 4 additions & 4 deletions b/‎middleware/validation.go‎
Lines changed: 4 additions & 4 deletions
@@ -53,6 +53,7 @@ linters:
       - legacy
       - std-error-handling
     paths:
+      - .worktrees
       - third_party$
       - builtin$
       - examples$
@@ -63,6 +64,7 @@ formatters:
   exclusions:
     generated: lax
     paths:
+      - .worktrees
       - third_party$
       - builtin$
       - examples$
 
@@ -17,6 +17,7 @@ import (
 	"github.com/go-openapi/runtime/client/internal/request"
 	"github.com/go-openapi/runtime/logger"
 	"github.com/go-openapi/runtime/middleware"
+	"github.com/go-openapi/runtime/server-middleware/mediatype"
 	"github.com/go-openapi/runtime/yamlpc"
 	"github.com/go-openapi/strfmt"
 )
@@ -48,6 +49,14 @@ type Runtime struct {
 	Debug  bool
 	logger logger.Logger
 
+	// MatchSuffix enables RFC 6839 structured-syntax suffix tolerance
+	// for codec lookup. When true, a response with Content-Type
+	// "application/problem+json" finds the JSON consumer registered
+	// under "application/json"; with the default false, the lookup
+	// is strict and falls through to the "*/*" wildcard if present.
+	// See [mediatype.AllowSuffix] for the semantics.
+	MatchSuffix bool
+
 	clientOnce *sync.Once
 	client     *http.Client
 	schemes    []string
@@ -340,23 +349,34 @@ func (r *Runtime) dumpResponse(res *http.Response, ct string) error {
 }
 
 // resolveConsumer parses ct and returns the registered Consumer for
-// that media type, falling back to the "*/*" entry if any.
+// that media type. Lookup is alias-aware (RFC 9512 §2.1 — yaml
+// aliases) and, when [Runtime.MatchSuffix] is true, also tolerates
+// RFC 6839 structured-syntax suffix media types (+json, +xml, +yaml).
+// Falls back to the "*/*" entry if no match found.
 func (r *Runtime) resolveConsumer(ct string) (runtime.Consumer, error) {
-	mt, _, err := mime.ParseMediaType(ct)
-	if err != nil {
+	if _, _, err := mime.ParseMediaType(ct); err != nil {
 		return nil, fmt.Errorf("parse content type: %s", err)
 	}
-	cons, ok := r.Consumers[mt]
-	if ok {
+	if cons, ok := mediatype.Lookup(r.Consumers, ct, r.matchOpts()...); ok {
 		return cons, nil
 	}
-	if cons, ok = r.Consumers["*/*"]; ok {
+	if cons, ok := r.Consumers["*/*"]; ok {
 		return cons, nil
 	}
 	// scream about not knowing what to do
 	return nil, fmt.Errorf("no consumer: %q", ct)
 }
 
+// matchOpts builds the mediatype.MatchOption slice for codec
+// lookups on the Runtime, currently just the AllowSuffix opt-in.
+func (r *Runtime) matchOpts() []mediatype.MatchOption {
+	if !r.MatchSuffix {
+		return nil
+	}
+
+	return []mediatype.MatchOption{mediatype.AllowSuffix()}
+}
+
 // createHTTPRequestContext is the context-aware builder of a [http.Request].
 //
 // The returned [http.Request] carries a context derived from parentCtx that
@@ -403,8 +423,8 @@ func (r *Runtime) prepareRequest(operation *runtime.ClientOperation) (*request.R
 		})
 	}
 
-	cmt := pickConsumesMediaType(operation.ConsumesMediaTypes, r.Producers, r.DefaultMediaType)
-	if _, ok := r.Producers[cmt]; !ok && cmt != runtime.MultipartFormMime && cmt != runtime.URLencodedFormMime {
+	cmt := pickConsumesMediaType(operation.ConsumesMediaTypes, r.Producers, r.DefaultMediaType, r.matchOpts()...)
+	if _, ok := mediatype.Lookup(r.Producers, cmt, r.matchOpts()...); !ok && cmt != runtime.MultipartFormMime && cmt != runtime.URLencodedFormMime {
 		return nil, "", nil, fmt.Errorf("none of producers: %v registered. try %s", r.Producers, cmt)
 	}
 
@@ -440,7 +460,7 @@ func (r *Runtime) applyHostScheme(httpReq *http.Request, operation *runtime.Clie
 // Step 2 closes part of issues #32 and #386: an operation declaring
 // `consumes: [application/x-vendor, application/json]` with no vendor
 // producer registered now silently uses JSON instead of erroring.
-func pickConsumesMediaType(consumes []string, producers map[string]runtime.Producer, def string) string {
+func pickConsumesMediaType(consumes []string, producers map[string]runtime.Producer, def string, opts ...mediatype.MatchOption) string {
 	for _, mt := range consumes {
 		if strings.EqualFold(mt, runtime.MultipartFormMime) {
 			return mt
@@ -457,7 +477,7 @@ func pickConsumesMediaType(consumes []string, producers map[string]runtime.Produ
 		if isStructuralMime(mt) {
 			return mt
 		}
-		if _, ok := producers[mt]; ok {
+		if _, ok := mediatype.Lookup(producers, mt, opts...); ok {
 			return mt
 		}
 	}
 
@@ -21,8 +21,12 @@ const (
 	DefaultMime = "application/octet-stream"
 	// JSONMime the json mime type.
 	JSONMime = "application/json"
-	// YAMLMime the [yaml] mime type.
-	YAMLMime = "application/x-yaml"
+	// YAMLMime the [yaml] mime type. Set to the canonical RFC 9512
+	// name (application/yaml). Legacy forms application/x-yaml,
+	// text/yaml, and text/x-yaml — per RFC 9512 §2.1 "Deprecated
+	// alias names for this type" — resolve to the same codec via
+	// the mediatype alias bridge.
+	YAMLMime = "application/yaml"
 	// XMLMime the [xml] mime type.
 	XMLMime = "application/xml"
 	// TextMime the text mime type.
 
@@ -86,6 +86,105 @@ The asymmetry is intrinsic to the semantics ("loose if the bound has no
 params, otherwise the constraint must be a subset"), not to which side is
 the server.
 
+## Beyond strict matching — alias and suffix tolerances
+
+The bare `Matches` rule above is strict RFC 7231: type, subtype, and the
+parameter subset. Two extensions sit on top of it, both surfaced through
+the graded result of `MediaType.Match`:
+
+| Tier | Reached when | Example |
+|---|---|---|
+| `MatchExact` | Strict RFC 7231 match. | `application/json` vs `application/json` |
+| `MatchAlias` | Strict fails but both sides resolve to the same canonical form via the package-internal alias table. | `application/x-yaml` vs `application/yaml` |
+| `MatchSuffix` | Strict and alias both fail but both sides resolve to the same base after folding the RFC 6839 structured-syntax suffix. | `application/vnd.api+json` vs `application/json` |
+| `MatchNone` | None of the above. | |
+
+`Set.BestMatch`, `MatchFirst`, and `mediatype.Lookup` rank candidates by
+this tier in addition to q-value and specificity — when two offers fit a
+constraint at different tiers, the stronger tier wins regardless of
+offer order. Exact beats alias, alias beats suffix.
+
+### Alias bridge — always on
+
+RFC 9512 §2.1 enumerates three deprecated alias names for the
+`application/yaml` registration:
+
+| Alias | Canonical |
+|---|---|
+| `application/x-yaml` | `application/yaml` |
+| `text/yaml` | `application/yaml` |
+| `text/x-yaml` | `application/yaml` |
+
+A request, offer, or codec registration in any of these forms matches a
+counterpart in any of the others. The bridge is wire-format equivalence
+backed by an explicit IANA registration-template field — no opt-in
+needed and no way to disable it.
+
+### Structured-syntax suffix tolerance — opt-in
+
+`+json`, `+xml`, and `+yaml` are the RFC 6839 structured-syntax suffixes
+the runtime recognises. Their wire format is the underlying base
+(`+json` is JSON), but their semantics carry application-specific
+structure on top (`application/problem+json` is JSON-on-the-wire with
+the RFC 7807 problem-details document shape). Tolerating these as
+equivalent to the base format is a contract loosening, so the runtime
+defaults to strict and surfaces the leniency through an explicit
+opt-in.
+
+Three matching knobs at three layers:
+
+```go
+// per-call (in negotiation only)
+chosen := negotiate.ContentType(r, offers, "",
+    negotiate.WithMatchSuffix(true),
+)
+
+// server-wide
+ctx := middleware.NewContext(spec, api, nil).SetMatchSuffix(true)
+
+// client-wide
+rt := client.New(host, basePath, schemes)
+rt.MatchSuffix = true
+```
+
+All three feed the same `mediatype.AllowSuffix()` option through
+`Set.BestMatch`, `MatchFirst`, and `mediatype.Lookup`. With the flag on,
+a spec declaring `consumes: [application/json]` end-to-end tolerates
+request bodies sent with `Content-Type: application/vnd.api+json` (and
+likewise for `+xml` / `+yaml`). With the flag off — the default — such
+a request is rejected with 415, exactly as before.
+
+The opt-in is intended for situations where the user does not control
+both sides of the wire:
+
+- a server that wants to accept `application/problem+json` errors from
+  upstream services declared as `application/json`;
+- a client that needs to consume `application/problem+json` responses
+  from servers whose spec only declares `application/json` in `produces`.
+
+If both sides are under your control, **prefer to align the spec**:
+list `application/vnd.api+json` (or whichever variant applies)
+explicitly in `consumes` / `produces`. The opt-in is leeway for the
+common real-world mismatch, not a substitute for a faithful spec.
+
+### Tier interactions worth pinning
+
+- **Parameters still bind at every tier.** A constraint of
+  `application/yaml; charset=utf-8` does not match an offer of
+  `application/yaml; charset=ascii` even with subtypes equal — the
+  parameter-subset rule from `Matches` applies regardless of which tier
+  resolved the subtype. Suffix tolerance does not loosen the param
+  rule.
+- **Exact registrations always win.** If `application/vnd.api+json` is
+  explicitly in `consumes` (or registered as a producer), routing and
+  codec lookup never fall through to the suffix tier for that mime —
+  even with `WithMatchSuffix(true)`.
+- **Map-side suffix folding is intentionally absent.** A registration
+  at `application/vnd.api+json` does *not* receive a query of
+  `application/json` even with the opt-in. The inverse case ("only the
+  vendor consumer is registered, plain-base query arrives") is not a
+  scenario the runtime tries to cover.
+
 ## Server side — inbound `Content-Type` validation
 
 Flow when a request arrives with a body:
@@ -395,6 +494,16 @@ your `produces` use mismatched charset/version params and you treat
 those as informational, opt out with `negotiate.WithIgnoreParameters(true)`
 (per call) or `Context.SetIgnoreParameters(true)` (server-wide).
 
+**"My server rejects `application/vnd.api+json` (or `application/problem+json`) with 415."**
+The default match is strict RFC 7231 — a vendor `+json` mime is *not*
+a `application/json` mime. Two routes forward: (1) list the vendor
+mime explicitly in the operation's `consumes` and register a codec
+under that key (the spec-faithful path); or (2) enable
+`Context.SetMatchSuffix(true)` server-wide to fold `+json` / `+xml` /
+`+yaml` to the underlying base codec at lookup time (the leeway path,
+for situations where the client is not under your control). See
+the "Beyond strict matching" section above.
+
 **"My client request returns 415 even though the API lists my type in `consumes`."**
 Check the wire `Content-Type` against your server's `consumes` matching
 rules. The client sends the picker's choice (with Stage-2 upgrades for
@@ -425,6 +534,8 @@ or the cached value at `middleware.MatchedRouteFrom(r).Consumes`.
 
 - Server matching primitive: `github.com/go-openapi/runtime/server-middleware/mediatype`
 - Server negotiator: `github.com/go-openapi/runtime/server-middleware/negotiate`
+- Codec lookup helper: `mediatype.Lookup[T]` — used by both server (`middleware/context.go`, `middleware/validation.go`) and client (`client/runtime.go`)
+- Alias and suffix tolerances: `mediatype.Match`, `mediatype.MatchKind`, `mediatype.AllowSuffix`; opt-in surfaces `negotiate.WithMatchSuffix`, `middleware.Context.SetMatchSuffix`, `client.Runtime.MatchSuffix`
 - Server validation: `middleware/validation.go` (`validateContentType`)
 - Client Stage-1 picker: `client/runtime.go` (`pickConsumesMediaType`)
 - Client Stage-2 fallback: `client/request.go` (`setStreamContentType`,
 
@@ -22,6 +22,7 @@ import (
 	"github.com/go-openapi/runtime/middleware/untyped"
 	"github.com/go-openapi/runtime/security"
 	"github.com/go-openapi/runtime/server-middleware/docui"
+	"github.com/go-openapi/runtime/server-middleware/mediatype"
 	"github.com/go-openapi/runtime/server-middleware/negotiate"
 )
 
@@ -80,6 +81,7 @@ type Context struct {
 	router           Router
 	debugLogf        func(string, ...any) // a logging function to debug context and all components using it
 	ignoreParameters bool                 // see SetIgnoreParameters / WithIgnoreParameters
+	matchSuffix      bool                 // see SetMatchSuffix / WithMatchSuffix
 }
 
 // NewRoutableContext creates a new context for a routable API.
@@ -151,6 +153,27 @@ func (c *Context) SetIgnoreParameters(ignore bool) *Context {
 	return c
 }
 
+// SetMatchSuffix toggles RFC 6839 structured-syntax suffix tolerance
+// server-wide. When enabled, both Accept negotiation and codec lookup
+// fall back through the suffix base for the recognised suffixes
+// (+json, +xml, +yaml) — so an operation declaring
+// consumes: [application/json] also accepts request bodies sent with
+// Content-Type: application/vnd.api+json (or any other +json variant).
+//
+// Default: strict (false). Use only when interoperating with clients
+// that do not strictly abide by the spec.
+//
+// Returns the receiver for fluent configuration:
+//
+//	ctx := middleware.NewContext(spec, api, nil).SetMatchSuffix(true)
+//
+// See [negotiate.WithMatchSuffix] for the per-call form and rationale.
+func (c *Context) SetMatchSuffix(enable bool) *Context {
+	c.matchSuffix = enable
+
+	return c
+}
+
 type routableUntypedAPI struct {
 	api             *untyped.API
 	hlock           *sync.Mutex
@@ -348,7 +371,7 @@ func (c *Context) BindValidRequest(request *http.Request, route *MatchedRoute, b
 				res = append(res, err)
 			}
 			if len(res) == 0 {
-				cons, ok := route.Consumers[ct]
+				cons, ok := mediatype.Lookup(route.Consumers, ct, c.matchOpts()...)
 				if !ok {
 					res = append(res, errors.New(http.StatusInternalServerError, "no consumer registered for %s", ct))
 				} else {
@@ -722,11 +745,27 @@ func (c Context) uiOptionsForHandler(opts []UIOption) []docui.Option {
 }
 
 func (c *Context) negotiateOpts() []negotiate.Option {
-	if !c.ignoreParameters {
+	var opts []negotiate.Option
+	if c.ignoreParameters {
+		opts = append(opts, negotiate.WithIgnoreParameters(true))
+	}
+	if c.matchSuffix {
+		opts = append(opts, negotiate.WithMatchSuffix(true))
+	}
+
+	return opts
+}
+
+// matchOpts builds the mediatype.MatchOption slice that the
+// codec-lookup and Content-Type validation paths apply server-wide.
+// Mirrors negotiateOpts but at the mediatype level (without going
+// through the negotiate.Option wrapper).
+func (c *Context) matchOpts() []mediatype.MatchOption {
+	if !c.matchSuffix {
 		return nil
 	}
 
-	return []negotiate.Option{negotiate.WithIgnoreParameters(true)}
+	return []mediatype.MatchOption{mediatype.AllowSuffix()}
 }
 
 func cantFindProducer(format string) string {
 
@@ -33,11 +33,11 @@ type validation struct {
 // a 400 [errors.ParseError]). This function therefore only sees the
 // malformed case when invoked directly by callers that have bypassed
 // that step.
-func validateContentType(allowed []string, actual string) error {
+func validateContentType(allowed []string, actual string, opts ...mediatype.MatchOption) error {
 	if len(allowed) == 0 {
 		return nil
 	}
-	_, ok, err := mediatype.MatchFirst(allowed, actual)
+	_, ok, err := mediatype.MatchFirst(allowed, actual, opts...)
 	if ok {
 		return nil
 	}
@@ -96,12 +96,12 @@ func (v *validation) contentType() {
 
 		if len(v.result) == 0 {
 			v.debugLogf("validating content type for %q against [%s]", ct, strings.Join(v.route.Consumes, ", "))
-			if err := validateContentType(v.route.Consumes, ct); err != nil {
+			if err := validateContentType(v.route.Consumes, ct, v.context.matchOpts()...); err != nil {
 				v.result = append(v.result, err)
 			}
 		}
 		if ct != "" && v.route.Consumer == nil {
-			cons, ok := v.route.Consumers[ct]
+			cons, ok := mediatype.Lookup(v.route.Consumers, ct, v.context.matchOpts()...)
 			if !ok {
 				v.result = append(v.result, errors.New(http.StatusInternalServerError, "no consumer registered for %s", ct))
 			} else {