Skip to content

feat(datamodel/v3)!: model OAS 3.2 prefixEncoding, itemEncoding and nested Encoding fields - #706

Open
Tjmstudios wants to merge 1 commit into
pb33f:mainfrom
Tjmstudios:oas32-encoding-fields
Open

Tjmstudios wants to merge 1 commit into
pb33f:mainfrom
Tjmstudios:oas32-encoding-fields

Conversation

@Tjmstudios

@Tjmstudios Tjmstudios commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

OpenAPI 3.2 defines itemEncoding on the Media Type Object as a single Encoding Object, adds prefixEncoding as an array of them, and adds encoding, prefixEncoding and itemEncoding to the Encoding Object for nested multipart parts (§4.14, §4.15.1.1). libopenapi models itemEncoding as a map, which contradicts its own datamodel/schemas/oas32-schema.json (:807-815, :883-891). The other fields aren't modeled at all.

The map typing corrupts documents on a round trip. This:

itemEncoding:
  contentType: image/png

renders back as itemEncoding: {contentType: {}}. prefixEncoding and the nested fields are dropped.

This PR models all of them as the spec defines them, in the low and high models, hashing and what-changed. ItemEncoding becomes a single Encoding and MediaTypeChanges.ItemEncodingChanges a single *EncodingChanges. That's a breaking change, so I've added an "Upgrading past v0.42" section to MIGRATING.md. I didn't keep the old map field. For a valid 3.2 document it holds the Encoding Object's fields as map keys, so there's nothing correct to keep compatible, and keeping it would leave ItemEncoding stuck with the wrong type. If you'd rather avoid the break, I can keep it as a deprecated yaml:"-" field and add the single object under a new name instead.

A few things you may want differently:

  • The new breaking rules default to the same as itemEncoding: removal is breaking, add and modify aren't.
  • The Media Type's own encoding map keeps its hardcoded what-changed behavior, so existing output doesn't move. The nested one uses the rules.
  • The model builds encoding alongside prefixEncoding/itemEncoding even though the spec says they MUST NOT appear together. I left that to validation.

Some existing tests asserted the map shape (ItemEncoding.Len() == 2, and a sequence fixture in TestCompareMediaTypes_Modify), so I rewrote them to the 3.2 shape. TestCompareMediaTypes_Modify now expects 2 breaking changes, because the change reads as an itemEncoding.contentType modification, which EncodingRules.ContentType already marks breaking. The render test now checks an exact round trip instead of Contains("itemEncoding:").

New tests cover building, hashing (including prefix order), rendering, what-changed down to nested and positional entries, and overriding the new breaking rules. One of them checks that a breaking-rules config with encoding.encoding validates, since encoding is both the component and one of its properties.

Tests pass with LIBOPENAPI_RUN_NETWORK_TESTS=1, and with -race for datamodel and what-changed.

…ested Encoding fields

OpenAPI 3.2 defines itemEncoding as a single Encoding Object, adds
prefixEncoding as an array of them, and adds encoding, prefixEncoding
and itemEncoding to the Encoding Object for nested multipart parts.

- Retype MediaType.ItemEncoding (low and high) from a map to a single
  Encoding, and MediaTypeChanges.ItemEncodingChanges to a pointer.
- Add PrefixEncoding to MediaType, and Encoding, PrefixEncoding and
  ItemEncoding to Encoding, in the low and high models, hashing and
  what-changed, with breaking rules matching itemEncoding.
- Document the migration in MIGRATING.md.
@codecov

codecov Bot commented Nov 12, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (88615e4) to head (fe9a2df).

Additional details and impacted files
@@            Coverage Diff            @@
##              main      #706   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          315       315           
  Lines        39758     39842   +84     
=========================================
+ Hits         39758     39842   +84     
Flag Coverage Δ
unittests 100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

nodes.Store(prefixL.Line, prefixL)
}

item, err := low.ExtractObject[*Encoding](ctx, ItemEncodingLabel, root, idx)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Read encoding fields only from the current mapping. I round-tripped a multipart/mixed media type with itemEncoding.contentType: multipart/form-data and itemEncoding.encoding.photo. The output copied encoding.photo onto the media type alongside itemEncoding, a combination OAS 3.2 forbids. An itemEncoding key inside example also became a real media-type field. Both ExtractMap and ExtractObject fall back to searching child nodes when the direct key is absent. Locate the direct keys first and build only their values. This also avoids allocating an Encoding for media types with no itemEncoding.

prefixEncoding *low.NodeReference[[]low.ValueReference[*Encoding]],
itemEncoding *low.NodeReference[*Encoding],
) error {
encs, encsL, encsN, err := low.ExtractMap[*Encoding](ctx, EncodingLabel, root, idx)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Keep property names that start with x- in the encoding map. With a schema property named x-file, itemEncoding.encoding.x-file.contentType disappeared during build/render while the adjacent photo entry survived. Keys at this level are user-defined property names. ExtractMap filters extension-prefixed keys. Use the map extractor that retains them for the directly located encoding map, and test FindEncoding("x-file") and the round trip.

m.PrefixEncoding = extractEncodingSlice(mediaType.PrefixEncoding.Value)
if !mediaType.ItemEncoding.IsEmpty() {
m.ItemEncoding = ExtractEncoding(mediaType.ItemEncoding.Value)
m.ItemEncoding = NewEncoding(mediaType.ItemEncoding.Value)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Preserve specification extensions on the Encoding Object. itemEncoding: {contentType: image/png, x-vendor: abc} rendered with only contentType. Encoding Objects allow specification extensions, and callers lose their metadata on a read/write cycle. Please carry extensions through the low and high Encoding models and include them in hashing and comparison. Cover an extension directly on an item or prefix entry.

low.HashBool(h, en.AllowReserved.Value)
h.WriteByte(low.HASH_PIPE)
low.HashMap(h, "encoding", en.Encoding.Value)
hashEncodingFields(h, en.PrefixEncoding.Value, en.ItemEncoding.Value)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Include explode presence in nested encoding hashes. I added explode: false to a style: form encoding under itemEncoding.encoding.photo. The two media types had equal hashes and CompareMediaTypes returned nil. CompareEncoding already compares the YAML value nodes, but the parent equality check skips it. Hash the presence of Encoding.Explode as well as its value, and test the diff through the enclosing media type.

// extractEncodingSlice converts a low-level prefixEncoding array into high-level Encoding objects, keeping order.
func extractEncodingSlice(elements []lowmodel.ValueReference[*lowv3.Encoding]) []*Encoding {
if len(elements) == 0 {
return nil

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Preserve an explicitly empty prefixEncoding array. I parsed a multipart media type with schema: {type: array} and prefixEncoding: []. Render() omitted the field and CompareMediaTypes returned nil against a document where the field was absent. The 3.2 schema allows an empty array. Carry field presence from the low node through conversion, rendering, hashing, and comparison, and cover both an empty array and an omitted field.

BreakingAdded(component, PropPrefixEncoding), nil, rp[i].Value)
default:
if ch := CompareEncoding(lp[i].Value, rp[i].Value); ch != nil {
prefixChanges = append(prefixChanges, ch)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Retain the changed part’s original position. I changed only the second prefixEncoding entry. The JSON report put the change at prefixEncoding[0] with no source array index. A consumer can recover the position only by going back to the source document. Preserve i in the report, for example with an explicit index on each change, and assert that changing only the second part reports index 1.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants