Repository navigation
feat(datamodel/v3)!: model OAS 3.2 prefixEncoding, itemEncoding and nested Encoding fields - #706
Tjmstudios wants to merge 1 commit into
Conversation
…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 Report✅ All modified and coverable lines are covered by tests. 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
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
| nodes.Store(prefixL.Line, prefixL) | ||
| } | ||
|
|
||
| item, err := low.ExtractObject[*Encoding](ctx, ItemEncodingLabel, root, idx) |
There was a problem hiding this comment.
[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) |
There was a problem hiding this comment.
[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) |
There was a problem hiding this comment.
[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) |
There was a problem hiding this comment.
[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 |
There was a problem hiding this comment.
[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) |
There was a problem hiding this comment.
[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.
OpenAPI 3.2 defines
itemEncodingon the Media Type Object as a single Encoding Object, addsprefixEncodingas an array of them, and addsencoding,prefixEncodinganditemEncodingto the Encoding Object for nested multipart parts (§4.14, §4.15.1.1). libopenapi modelsitemEncodingas a map, which contradicts its owndatamodel/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:
renders back as
itemEncoding: {contentType: {}}.prefixEncodingand 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.
ItemEncodingbecomes a singleEncodingandMediaTypeChanges.ItemEncodingChangesa 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 leaveItemEncodingstuck with the wrong type. If you'd rather avoid the break, I can keep it as a deprecatedyaml:"-"field and add the single object under a new name instead.A few things you may want differently:
itemEncoding: removal is breaking, add and modify aren't.encodingmap keeps its hardcoded what-changed behavior, so existing output doesn't move. The nested one uses the rules.encodingalongsideprefixEncoding/itemEncodingeven 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 inTestCompareMediaTypes_Modify), so I rewrote them to the 3.2 shape.TestCompareMediaTypes_Modifynow expects 2 breaking changes, because the change reads as anitemEncoding.contentTypemodification, whichEncodingRules.ContentTypealready marks breaking. The render test now checks an exact round trip instead ofContains("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.encodingvalidates, sinceencodingis both the component and one of its properties.Tests pass with
LIBOPENAPI_RUN_NETWORK_TESTS=1, and with-racefordatamodelandwhat-changed.