diff --git a/MIGRATING.md b/MIGRATING.md index 4ee36604..dc1c8a46 100644 --- a/MIGRATING.md +++ b/MIGRATING.md @@ -2,6 +2,86 @@ This file lists breaking changes to the libopenapi Go API and how to update code for each one. +## Upgrading past v0.42 + +OpenAPI 3.2 defines `itemEncoding` as one Encoding Object, not a map, and adds `prefixEncoding` and nested +`encoding`, `prefixEncoding` and `itemEncoding` to the Encoding Object. libopenapi modeled `itemEncoding` as a map, so +a valid 3.2 `itemEncoding` was read as a map keyed by its own field names and rendered back corrupted. This release +models all of them as the specification defines them. + +You don't need to change anything if your code doesn't read `ItemEncoding` or `ItemEncodingChanges`. + +### `MediaType.ItemEncoding` is a single `Encoding` + +| v0.42 | now | +|---|---| +| high: `ItemEncoding *orderedmap.Map[string, *Encoding]` | `ItemEncoding *Encoding` | +| low: `ItemEncoding low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Encoding]]]` | `ItemEncoding low.NodeReference[*Encoding]` | +| what-changed: `MediaTypeChanges.ItemEncodingChanges map[string]*EncodingChanges` | `ItemEncodingChanges *EncodingChanges` | + +Under the old type, each map key was a field of the Encoding Object, such as `contentType`. Read those fields from +`ItemEncoding` directly. + +### New fields + +| model | fields | +|---|---| +| high and low `MediaType` | `PrefixEncoding`, applied to parts by position | +| high and low `Encoding` | `Encoding`, `PrefixEncoding` and `ItemEncoding`, for nested multipart parts | +| what-changed `MediaTypeChanges` | `PrefixEncodingChanges` | +| what-changed `EncodingChanges` | `EncodingChanges`, `PrefixEncodingChanges` and `ItemEncodingChanges` | +| breaking rules `MediaTypeRules` | `PrefixEncoding` | +| breaking rules `EncodingRules` | `Encoding`, `PrefixEncoding` and `ItemEncoding` | + +The new breaking rules default to the same as `itemEncoding`: removing one is breaking, adding or changing one is +not. + +This program reads the encoding of each part of a `multipart/mixed` request body: + +```go +package main + +import ( + "fmt" + + "github.com/pb33f/libopenapi" +) + +const spec = `openapi: 3.2.0 +info: + title: Burger Shop + version: 1.0.0 +paths: + /orders: + post: + requestBody: + content: + multipart/mixed: + itemSchema: + type: object + prefixEncoding: + - contentType: application/json + itemEncoding: + contentType: image/png +` + +func main() { + doc, _ := libopenapi.NewDocument([]byte(spec)) + model, _ := doc.BuildV3Model() + mt := model.Model.Paths.PathItems.GetOrZero("/orders").Post.RequestBody.Content.GetOrZero("multipart/mixed") + + fmt.Println("first part:", mt.PrefixEncoding[0].ContentType) + fmt.Println("other parts:", mt.ItemEncoding.ContentType) +} +``` + +Output: + +``` +first part: application/json +other parts: image/png +``` + ## Upgrading past v0.40 This release makes two changes to the low-level model API. They don't change parsing, rendering, bundling or diff --git a/datamodel/high/v3/encoding.go b/datamodel/high/v3/encoding.go index 79b9f310..64fdb881 100644 --- a/datamodel/high/v3/encoding.go +++ b/datamodel/high/v3/encoding.go @@ -20,7 +20,13 @@ type Encoding struct { Style string `json:"style,omitempty" yaml:"style,omitempty"` Explode *bool `json:"explode,omitempty" yaml:"explode,omitempty"` AllowReserved bool `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"` - low *lowv3.Encoding + + // Encoding, PrefixEncoding and ItemEncoding describe nested multipart parts (OpenAPI 3.2+). + Encoding *orderedmap.Map[string, *Encoding] `json:"encoding,omitempty" yaml:"encoding,omitempty"` + PrefixEncoding []*Encoding `json:"prefixEncoding,omitempty" yaml:"prefixEncoding,omitempty"` + ItemEncoding *Encoding `json:"itemEncoding,omitempty" yaml:"itemEncoding,omitempty"` + Extensions *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"` + low *lowv3.Encoding } // NewEncoding creates a new instance of Encoding from a low-level one. @@ -33,7 +39,13 @@ func NewEncoding(encoding *lowv3.Encoding) *Encoding { e.Explode = &encoding.Explode.Value } e.AllowReserved = encoding.AllowReserved.Value + e.Extensions = high.ExtractExtensions(encoding.Extensions) e.Headers = ExtractHeaders(encoding.Headers.Value) + e.Encoding = ExtractEncoding(encoding.Encoding.Value) + e.PrefixEncoding = extractEncodingSlice(encoding.PrefixEncoding) + if !encoding.ItemEncoding.IsEmpty() { + e.ItemEncoding = NewEncoding(encoding.ItemEncoding.Value) + } return e } @@ -76,3 +88,16 @@ func (e *Encoding) MarshalYAMLInlineWithContext(ctx any) (interface{}, error) { func ExtractEncoding(elements *orderedmap.Map[lowmodel.KeyReference[string], lowmodel.ValueReference[*lowv3.Encoding]]) *orderedmap.Map[string, *Encoding] { return low.FromReferenceMapWithFunc(elements, NewEncoding) } + +// extractEncodingSlice converts a low-level prefixEncoding array into high-level Encoding objects, keeping order. +// An absent prefixEncoding becomes nil, and a present but empty one becomes an empty slice so it renders as []. +func extractEncodingSlice(prefix lowmodel.NodeReference[[]lowmodel.ValueReference[*lowv3.Encoding]]) []*Encoding { + if prefix.IsEmpty() && len(prefix.Value) == 0 { + return nil + } + extracted := make([]*Encoding, 0, len(prefix.Value)) + for i := range prefix.Value { + extracted = append(extracted, NewEncoding(prefix.Value[i].Value)) + } + return extracted +} diff --git a/datamodel/high/v3/media_type.go b/datamodel/high/v3/media_type.go index f9af064b..26b5f961 100644 --- a/datamodel/high/v3/media_type.go +++ b/datamodel/high/v3/media_type.go @@ -20,14 +20,15 @@ import ( // Each Media Type Object provides schema and examples for the media type identified by its key. // - https://spec.openapis.org/oas/v3.1.0#media-type-object type MediaType struct { - Schema *base.SchemaProxy `json:"schema,omitempty" yaml:"schema,omitempty"` - ItemSchema *base.SchemaProxy `json:"itemSchema,omitempty" yaml:"itemSchema,omitempty"` - Example *yaml.Node `json:"example,omitempty" yaml:"example,omitempty"` - Examples *orderedmap.Map[string, *base.Example] `json:"examples,omitempty" yaml:"examples,omitempty"` - Encoding *orderedmap.Map[string, *Encoding] `json:"encoding,omitempty" yaml:"encoding,omitempty"` - ItemEncoding *orderedmap.Map[string, *Encoding] `json:"itemEncoding,omitempty" yaml:"itemEncoding,omitempty"` - Extensions *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"` - low *low.MediaType + Schema *base.SchemaProxy `json:"schema,omitempty" yaml:"schema,omitempty"` + ItemSchema *base.SchemaProxy `json:"itemSchema,omitempty" yaml:"itemSchema,omitempty"` + Example *yaml.Node `json:"example,omitempty" yaml:"example,omitempty"` + Examples *orderedmap.Map[string, *base.Example] `json:"examples,omitempty" yaml:"examples,omitempty"` + Encoding *orderedmap.Map[string, *Encoding] `json:"encoding,omitempty" yaml:"encoding,omitempty"` + PrefixEncoding []*Encoding `json:"prefixEncoding,omitempty" yaml:"prefixEncoding,omitempty"` // OpenAPI 3.2+ + ItemEncoding *Encoding `json:"itemEncoding,omitempty" yaml:"itemEncoding,omitempty"` // OpenAPI 3.2+ + Extensions *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"` + low *low.MediaType } // NewMediaType will create a new high-level MediaType instance from a low-level one. @@ -44,8 +45,9 @@ func NewMediaType(mediaType *low.MediaType) *MediaType { m.Examples = base.ExtractExamples(mediaType.Examples.Value) m.Extensions = high.ExtractExtensions(mediaType.Extensions) m.Encoding = ExtractEncoding(mediaType.Encoding.Value) + m.PrefixEncoding = extractEncodingSlice(mediaType.PrefixEncoding) if !mediaType.ItemEncoding.IsEmpty() { - m.ItemEncoding = ExtractEncoding(mediaType.ItemEncoding.Value) + m.ItemEncoding = NewEncoding(mediaType.ItemEncoding.Value) } return m } diff --git a/datamodel/high/v3/media_type_itemschema_test.go b/datamodel/high/v3/media_type_itemschema_test.go index 127314bb..e41b04c3 100644 --- a/datamodel/high/v3/media_type_itemschema_test.go +++ b/datamodel/high/v3/media_type_itemschema_test.go @@ -64,15 +64,12 @@ itemSchema: metadata: type: object itemEncoding: - data: - contentType: application/octet-stream - allowReserved: true - metadata: - contentType: application/json - headers: - X-Meta-Type: - schema: - type: string` + contentType: application/json + allowReserved: true + headers: + X-Meta-Type: + schema: + type: string` var idxNode yaml.Node _ = yaml.Unmarshal([]byte(yml), &idxNode) @@ -84,22 +81,11 @@ itemEncoding: highMediaType := NewMediaType(&lowMediaType) - // Check itemEncoding exists + // itemEncoding is a single Encoding Object (OpenAPI 3.2) assert.NotNil(t, highMediaType.ItemEncoding) - assert.Equal(t, 2, highMediaType.ItemEncoding.Len()) - - // Check data encoding - dataEnc := highMediaType.ItemEncoding.GetOrZero("data") - assert.NotNil(t, dataEnc) - assert.Equal(t, "application/octet-stream", dataEnc.ContentType) - assert.True(t, dataEnc.AllowReserved) - - // Check metadata encoding - metaEnc := highMediaType.ItemEncoding.GetOrZero("metadata") - assert.NotNil(t, metaEnc) - assert.Equal(t, "application/json", metaEnc.ContentType) - assert.NotNil(t, metaEnc.Headers) - assert.Equal(t, 1, metaEnc.Headers.Len()) + assert.Equal(t, "application/json", highMediaType.ItemEncoding.ContentType) + assert.True(t, highMediaType.ItemEncoding.AllowReserved) + assert.Equal(t, 1, highMediaType.ItemEncoding.Headers.Len()) } func TestNewMediaType_WithBothEncodingTypes(t *testing.T) { @@ -114,9 +100,8 @@ encoding: contentType: text/plain style: form itemEncoding: - streamField: - contentType: application/json - explode: false` + contentType: application/json + explode: false` var idxNode yaml.Node _ = yaml.Unmarshal([]byte(yml), &idxNode) @@ -132,7 +117,6 @@ itemEncoding: assert.NotNil(t, highMediaType.Encoding) assert.NotNil(t, highMediaType.ItemEncoding) assert.Equal(t, 1, highMediaType.Encoding.Len()) - assert.Equal(t, 1, highMediaType.ItemEncoding.Len()) // Check regular encoding regularEnc := highMediaType.Encoding.GetOrZero("regularField") @@ -141,7 +125,7 @@ itemEncoding: assert.Equal(t, "form", regularEnc.Style) // Check item encoding - itemEnc := highMediaType.ItemEncoding.GetOrZero("streamField") + itemEnc := highMediaType.ItemEncoding assert.NotNil(t, itemEnc) assert.Equal(t, "application/json", itemEnc.ContentType) assert.NotNil(t, itemEnc.Explode) @@ -181,8 +165,7 @@ itemSchema: id: type: string itemEncoding: - id: - contentType: text/plain` + contentType: text/plain` var idxNode yaml.Node _ = yaml.Unmarshal([]byte(yml), &idxNode) @@ -205,8 +188,7 @@ func TestMediaType_GoLow_WithItemFields(t *testing.T) { yml := `itemSchema: type: string itemEncoding: - field: - contentType: application/json` + contentType: application/json` var idxNode yaml.Node _ = yaml.Unmarshal([]byte(yml), &idxNode) @@ -224,3 +206,179 @@ itemEncoding: assert.NotNil(t, lowResult.ItemSchema.Value) assert.NotNil(t, lowResult.ItemEncoding.Value) } + +// TestMediaType_OAS32Encoding_RoundTrip checks that prefixEncoding, a single-object itemEncoding and the +// nested Encoding Object fields build into the model and render back unchanged. +func TestMediaType_OAS32Encoding_RoundTrip(t *testing.T) { + for name, yml := range map[string]string{ + "prefix and item": `prefixEncoding: + - contentType: application/json + - contentType: image/png + headers: + X-Part: + schema: + type: string +itemEncoding: + contentType: text/plain +`, + "nested": `encoding: + batch: + contentType: multipart/mixed + prefixEncoding: + - contentType: application/json + itemEncoding: + contentType: image/png + form: + contentType: multipart/form-data + encoding: + file: + contentType: image/jpeg +`, + "item encoding with nested encoding": `itemEncoding: + contentType: multipart/form-data + encoding: + photo: + contentType: image/png + x-file: + contentType: application/pdf +`, + "encoding keys inside example": `example: + encoding: + photo: + contentType: image/png + itemEncoding: + contentType: text/plain +`, + "nested part headers": `encoding: + batch: + contentType: multipart/mixed + itemEncoding: + headers: + X-Part: + schema: + type: string +`, + "item encoding extension": `itemEncoding: + contentType: image/png + x-vendor: abc +`, + "extensions on every encoding level": `encoding: + batch: + contentType: multipart/mixed + x-batch: true + prefixEncoding: + - contentType: application/json + x-part: first + itemEncoding: + contentType: image/png + x-item: abc + encoding: + x-file: + contentType: application/pdf + x-inner: 1 +prefixEncoding: + - contentType: application/xml + x-part: top +`, + "empty prefix encoding": `schema: + type: array +prefixEncoding: [] +`, + "empty prefix encoding on nested parts": `encoding: + batch: + contentType: multipart/mixed + prefixEncoding: [] +itemEncoding: + contentType: multipart/mixed + prefixEncoding: [] +`, + } { + t.Run(name, func(t *testing.T) { + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var lowMediaType lowv3.MediaType + _ = low.BuildModel(&idxNode, &lowMediaType) + assert.NoError(t, lowMediaType.Build(context.Background(), nil, idxNode.Content[0], idx)) + + rendered, err := NewMediaType(&lowMediaType).Render() + assert.NoError(t, err) + assert.Equal(t, yml, string(rendered)) + }) + } +} + +func TestMediaType_OAS32Encoding_Model(t *testing.T) { + yml := `encoding: + batch: + contentType: multipart/mixed + prefixEncoding: + - contentType: application/json + - contentType: image/png + itemEncoding: + contentType: text/plain + encoding: + inner: + style: form +prefixEncoding: + - contentType: application/xml +itemEncoding: + contentType: image/gif` + + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var lowMediaType lowv3.MediaType + _ = low.BuildModel(&idxNode, &lowMediaType) + assert.NoError(t, lowMediaType.Build(context.Background(), nil, idxNode.Content[0], idx)) + mt := NewMediaType(&lowMediaType) + + assert.Len(t, mt.PrefixEncoding, 1) + assert.Equal(t, "application/xml", mt.PrefixEncoding[0].ContentType) + assert.Equal(t, "image/gif", mt.ItemEncoding.ContentType) + + batch := mt.Encoding.GetOrZero("batch") + assert.Len(t, batch.PrefixEncoding, 2) + assert.Equal(t, "image/png", batch.PrefixEncoding[1].ContentType) + assert.Equal(t, "text/plain", batch.ItemEncoding.ContentType) + assert.Equal(t, "form", batch.Encoding.GetOrZero("inner").Style) +} + +func TestMediaType_OAS32Encoding_Extensions(t *testing.T) { + yml := `itemEncoding: + contentType: image/png + x-vendor: abc +prefixEncoding: + - contentType: application/json + x-part: first` + + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var lowMediaType lowv3.MediaType + _ = low.BuildModel(&idxNode, &lowMediaType) + assert.NoError(t, lowMediaType.Build(context.Background(), nil, idxNode.Content[0], idx)) + mt := NewMediaType(&lowMediaType) + + assert.Equal(t, "abc", mt.ItemEncoding.Extensions.GetOrZero("x-vendor").Value) + assert.Equal(t, "first", mt.PrefixEncoding[0].Extensions.GetOrZero("x-part").Value) + assert.Equal(t, 0, mt.Extensions.Len()) +} + +func TestMediaType_OAS32Encoding_EmptyPrefixEncodingBuiltByCaller(t *testing.T) { + // an empty non-nil slice renders as [], a nil slice is omitted. + mt := &MediaType{ + PrefixEncoding: []*Encoding{}, + ItemEncoding: &Encoding{ContentType: "multipart/mixed", PrefixEncoding: []*Encoding{}}, + } + rendered, err := mt.Render() + assert.NoError(t, err) + assert.Equal(t, "prefixEncoding: []\nitemEncoding:\n contentType: multipart/mixed\n prefixEncoding: []\n", string(rendered)) + + rendered, err = (&MediaType{ItemEncoding: &Encoding{ContentType: "multipart/mixed"}}).Render() + assert.NoError(t, err) + assert.Equal(t, "itemEncoding:\n contentType: multipart/mixed\n", string(rendered)) +} diff --git a/datamodel/low/v3/constants.go b/datamodel/low/v3/constants.go index 473c2676..d02a3189 100644 --- a/datamodel/low/v3/constants.go +++ b/datamodel/low/v3/constants.go @@ -11,6 +11,7 @@ const ( EncodingLabel = "encoding" ItemSchemaLabel = "itemSchema" ItemEncodingLabel = "itemEncoding" + PrefixEncodingLabel = "prefixEncoding" HeadersLabel = "headers" ExpressionLabel = "expression" InfoLabel = "info" diff --git a/datamodel/low/v3/encoding.go b/datamodel/low/v3/encoding.go index e20a1f80..78826a0b 100644 --- a/datamodel/low/v3/encoding.go +++ b/datamodel/low/v3/encoding.go @@ -23,12 +23,19 @@ type Encoding struct { Style low.NodeReference[string] Explode low.NodeReference[bool] AllowReserved low.NodeReference[bool] - KeyNode *yaml.Node - RootNode *yaml.Node - index *index.SpecIndex - context context.Context - nodeStore low.NodeLines - reference low.Reference + + // Encoding, PrefixEncoding and ItemEncoding describe nested multipart parts (OpenAPI 3.2+). + Encoding low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Encoding]]] + PrefixEncoding low.NodeReference[[]low.ValueReference[*Encoding]] + ItemEncoding low.NodeReference[*Encoding] + Extensions *orderedmap.Map[low.KeyReference[string], low.ValueReference[*yaml.Node]] + + KeyNode *yaml.Node + RootNode *yaml.Node + index *index.SpecIndex + context context.Context + nodeStore low.NodeLines + reference low.Reference *low.Reference low.NodeMap } @@ -48,6 +55,16 @@ func (en *Encoding) FindHeader(hType string) *low.ValueReference[*Header] { return low.FindItemInOrderedMap[*Header](hType, en.Headers.Value) } +// FindExtension attempts to locate an extension with the supplied name +func (en *Encoding) FindExtension(ext string) *low.ValueReference[*yaml.Node] { + return low.FindItemInOrderedMap(ext, en.Extensions) +} + +// GetExtensions returns all Encoding extensions and satisfies the low.HasExtensions interface. +func (en *Encoding) GetExtensions() *orderedmap.Map[low.KeyReference[string], low.ValueReference[*yaml.Node]] { + return en.Extensions +} + // GetRootNode returns the root yaml node of the Encoding object func (en *Encoding) GetRootNode() *yaml.Node { return en.RootNode @@ -71,10 +88,20 @@ func (en *Encoding) Hash() uint64 { if en.Style.Value != "" { low.HashString(h, "style", en.Style.Value) } - low.HashBool(h, en.Explode.Value) - h.WriteByte(low.HASH_PIPE) + // explode's default depends on style, so an explicit value is hashed apart from an absent one. + if !en.Explode.IsEmpty() { + low.HashLabel(h, "explode") + low.HashBool(h, en.Explode.Value) + h.WriteByte(low.HASH_PIPE) + } low.HashBool(h, en.AllowReserved.Value) h.WriteByte(low.HASH_PIPE) + low.HashMap(h, "encoding", en.Encoding.Value) + hashEncodingFields(h, en.PrefixEncoding, en.ItemEncoding.Value) + for _, ext := range low.HashExtensions(en.Extensions) { + h.WriteString(ext) + h.WriteByte(low.HASH_PIPE) + } return h.Sum64() }) } @@ -95,12 +122,16 @@ func (en *Encoding) Build(ctx context.Context, keyNode, root *yaml.Node, idx *in en.Reference = &en.reference en.index = idx en.context = ctx + en.Extensions = low.ExtractExtensions(root) + low.ExtractExtensionNodes(ctx, en.Extensions, en.Nodes) - headers, hL, hN, err := low.ExtractMap[*Header](ctx, HeadersLabel, root, idx) - if err != nil { - return err - } - if headers != nil { + // headers is read only from this mapping, so a nested part's headers are not copied onto this one. + _, hL, hN := utils.FindKeyNodeFullTop(HeadersLabel, root.Content) + if hN != nil { + headers, err := low.ExtractMapNoLookupExtensions[*Header](ctx, hN, idx, true) + if err != nil { + return err + } en.Headers = low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Header]]]{ Value: headers, KeyNode: hL, @@ -111,5 +142,81 @@ func (en *Encoding) Build(ctx context.Context, keyNode, root *yaml.Node, idx *in v.Value.Nodes.Store(k.KeyNode.Line, k.KeyNode) } } + return extractEncodingFields(ctx, root, idx, en.Nodes, &en.Encoding, &en.PrefixEncoding, &en.ItemEncoding) +} + +// FindEncoding attempts to locate a nested Encoding with the supplied property name. +func (en *Encoding) FindEncoding(eType string) *low.ValueReference[*Encoding] { + return low.FindItemInOrderedMap[*Encoding](eType, en.Encoding.Value) +} + +// extractEncodingFields builds the encoding, prefixEncoding and itemEncoding fields shared by the +// Media Type Object and (for nested multipart parts) the Encoding Object. Each field is read only from the +// keys of root itself, so fields belonging to a nested part, or appearing inside an example, are left alone. +func extractEncodingFields(ctx context.Context, root *yaml.Node, idx *index.SpecIndex, nodes *low.NodeLines, + encoding *low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Encoding]]], + prefixEncoding *low.NodeReference[[]low.ValueReference[*Encoding]], + itemEncoding *low.NodeReference[*Encoding], +) error { + // encoding keys are schema property names, so names starting with x- are kept. + _, encsL, encsN := utils.FindKeyNodeFullTop(EncodingLabel, root.Content) + if encsN != nil { + encs, err := low.ExtractMapNoLookupExtensions[*Encoding](ctx, encsN, idx, true) + if err != nil { + return err + } + *encoding = low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Encoding]]]{ + Value: encs, + KeyNode: encsL, + ValueNode: encsN, + } + nodes.Store(encsL.Line, encsL) + for k, v := range encs.FromOldest() { + v.Value.Nodes.Store(k.KeyNode.Line, k.KeyNode) + } + } + + prefix, prefixL, prefixN, err := low.ExtractArray[*Encoding](ctx, PrefixEncodingLabel, root, idx) + if err != nil { + return err + } + if prefixL != nil { + *prefixEncoding = low.NodeReference[[]low.ValueReference[*Encoding]]{ + Value: prefix, + KeyNode: prefixL, + ValueNode: prefixN, + } + nodes.Store(prefixL.Line, prefixL) + } + + _, itemL, itemN := utils.FindKeyNodeFullTop(ItemEncodingLabel, root.Content) + if itemN != nil { + item, err, _, _ := low.ExtractObjectRaw[*Encoding](ctx, itemL, itemN, idx) + if err != nil { + return err + } + *itemEncoding = low.NodeReference[*Encoding]{ + Value: item, + KeyNode: itemL, + ValueNode: itemN, + } + itemEncoding.SetReference(item.GetReference(), item.GetReferenceNode()) + nodes.Store(itemL.Line, itemL) + } return nil } + +// hashEncodingFields hashes prefixEncoding in order, because each entry applies to the part at its position, +// then itemEncoding. A present but empty prefixEncoding hashes differently from an absent one. +func hashEncodingFields(h *maphash.Hash, prefix low.NodeReference[[]low.ValueReference[*Encoding]], item *Encoding) { + if !prefix.IsEmpty() { + low.HashLabel(h, "prefixEncoding") + h.WriteByte(low.HASH_PIPE) + } + for i := range prefix.Value { + low.HashString(h, "prefixEncoding", low.GenerateHashString(prefix.Value[i].Value)) + } + if item != nil { + low.HashString(h, "itemEncoding", low.GenerateHashString(item)) + } +} diff --git a/datamodel/low/v3/encoding_test.go b/datamodel/low/v3/encoding_test.go index 612ad1fc..3e5b4cba 100644 --- a/datamodel/low/v3/encoding_test.go +++ b/datamodel/low/v3/encoding_test.go @@ -5,11 +5,13 @@ package v3 import ( "context" + "fmt" "testing" "github.com/pb33f/go-yaml" "github.com/pb33f/libopenapi/datamodel/low" "github.com/pb33f/libopenapi/index" + "github.com/pb33f/libopenapi/orderedmap" "github.com/pb33f/testify/assert" ) @@ -51,8 +53,9 @@ explode: true` func TestEncoding_Build_Error(t *testing.T) { yml := `contentType: hot/cakes -headers: - $ref: #/borked` +headers: + ohMyStars: + $ref: '#/borked'` var idxNode yaml.Node mErr := yaml.Unmarshal([]byte(yml), &idxNode) @@ -120,3 +123,215 @@ func TestEncoding_Build_ScalarRoot(t *testing.T) { assert.Len(t, nodes[scalar.Content[0].Line], 1) assert.Equal(t, "hello", nodes[scalar.Content[0].Line][0].Value) } + +func TestEncoding_Build_Nested(t *testing.T) { + yml := `contentType: multipart/mixed +encoding: + meta: + contentType: application/json +prefixEncoding: + - contentType: application/xml + - contentType: image/png +itemEncoding: + contentType: text/plain` + + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var n Encoding + _ = low.BuildModel(idxNode.Content[0], &n) + assert.NoError(t, n.Build(context.Background(), nil, idxNode.Content[0], idx)) + + assert.Equal(t, "application/json", n.FindEncoding("meta").Value.ContentType.Value) + assert.Nil(t, n.FindEncoding("missing")) + assert.Len(t, n.PrefixEncoding.Value, 2) + assert.Equal(t, "image/png", n.PrefixEncoding.Value[1].Value.ContentType.Value) + assert.Equal(t, "text/plain", n.ItemEncoding.Value.ContentType.Value) +} + +func TestEncoding_Build_Error_Nested(t *testing.T) { + for name, yml := range map[string]string{ + "encoding": "encoding:\n part:\n $ref: '#/bork'", + "prefixEncoding": "prefixEncoding:\n - $ref: '#/bork'", + "itemEncoding": "itemEncoding:\n $ref: '#/bork'", + } { + t.Run(name, func(t *testing.T) { + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var n Encoding + _ = low.BuildModel(idxNode.Content[0], &n) + assert.Error(t, n.Build(context.Background(), nil, idxNode.Content[0], idx)) + }) + } +} + +// TestEncoding_Build_DirectKeysOnly checks that headers and the nested encoding fields are read only from the +// Encoding's own keys, never from the keys of a nested part. +func TestEncoding_Build_DirectKeysOnly(t *testing.T) { + yml := `contentType: multipart/mixed +itemEncoding: + contentType: multipart/form-data + headers: + X-Part: + description: a part header + encoding: + photo: + contentType: image/png + prefixEncoding: + - contentType: text/plain` + + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var n Encoding + _ = low.BuildModel(idxNode.Content[0], &n) + assert.NoError(t, n.Build(context.Background(), nil, idxNode.Content[0], idx)) + + assert.True(t, n.Headers.IsEmpty()) + assert.True(t, n.Encoding.IsEmpty()) + assert.True(t, n.PrefixEncoding.IsEmpty()) + + item := n.ItemEncoding.Value + assert.NotNil(t, item.FindHeader("X-Part")) + assert.Equal(t, "image/png", item.FindEncoding("photo").Value.ContentType.Value) + assert.Len(t, item.PrefixEncoding.Value, 1) + assert.Nil(t, item.ItemEncoding.Value) +} + +// TestEncoding_Build_ExtensionPrefixedNames checks that encoding property names and header names starting with +// x- are kept, because they are user-defined names rather than specification extensions. +func TestEncoding_Build_ExtensionPrefixedNames(t *testing.T) { + yml := `headers: + x-trace: + description: trace id +encoding: + photo: + contentType: image/png + x-file: + contentType: application/pdf` + + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var n Encoding + _ = low.BuildModel(idxNode.Content[0], &n) + assert.NoError(t, n.Build(context.Background(), nil, idxNode.Content[0], idx)) + + assert.Equal(t, "trace id", n.FindHeader("x-trace").Value.Description.Value) + assert.Equal(t, "image/png", n.FindEncoding("photo").Value.ContentType.Value) + assert.Equal(t, "application/pdf", n.FindEncoding("x-file").Value.ContentType.Value) +} + +func TestEncoding_Build_ItemEncodingReference(t *testing.T) { + yml := `itemEncoding: + $ref: '#/part' +part: + contentType: image/png` + + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var n Encoding + _ = low.BuildModel(idxNode.Content[0], &n) + assert.NoError(t, n.Build(context.Background(), nil, idxNode.Content[0], idx)) + + assert.Equal(t, "image/png", n.ItemEncoding.Value.ContentType.Value) + assert.True(t, n.ItemEncoding.IsReference()) + assert.Equal(t, "#/part", n.ItemEncoding.GetReference()) + assert.True(t, n.ItemEncoding.Value.IsReference()) +} + +func buildTestEncoding(t *testing.T, yml string) *Encoding { + t.Helper() + var idxNode yaml.Node + assert.NoError(t, yaml.Unmarshal([]byte(yml), &idxNode)) + var n Encoding + _ = low.BuildModel(idxNode.Content[0], &n) + assert.NoError(t, n.Build(context.Background(), nil, idxNode.Content[0], index.NewSpecIndex(&idxNode))) + return &n +} + +func TestEncoding_Build_Extensions(t *testing.T) { + n := buildTestEncoding(t, `contentType: multipart/mixed +x-vendor: abc +encoding: + x-file: + contentType: application/pdf + x-inner: 1 +prefixEncoding: + - contentType: application/json + x-part: first +itemEncoding: + contentType: image/png + x-item: abc`) + + assert.Equal(t, 1, orderedmap.Len(n.GetExtensions())) + assert.Equal(t, "abc", n.FindExtension("x-vendor").Value.Value) + assert.Equal(t, "1", n.FindEncoding("x-file").Value.FindExtension("x-inner").Value.Value) + assert.Equal(t, "first", n.PrefixEncoding.Value[0].Value.FindExtension("x-part").Value.Value) + assert.Equal(t, "abc", n.ItemEncoding.Value.FindExtension("x-item").Value.Value) + + // x- keys under encoding are part names, not extensions of the enclosing Encoding Object. + assert.Nil(t, n.FindExtension("x-file")) + assert.Nil(t, n.FindExtension("x-inner")) +} + +func TestEncoding_Hash_Extensions(t *testing.T) { + for name, yml := range map[string]string{ + "top": "contentType: image/png\nx-vendor: %s", + "item": "itemEncoding:\n contentType: image/png\n x-vendor: %s", + "prefix": "prefixEncoding:\n - contentType: image/png\n x-vendor: %s", + "nested": "encoding:\n photo:\n contentType: image/png\n x-vendor: %s", + } { + t.Run(name, func(t *testing.T) { + a := buildTestEncoding(t, fmt.Sprintf(yml, "abc")) + b := buildTestEncoding(t, fmt.Sprintf(yml, "xyz")) + assert.NotEqual(t, a.Hash(), b.Hash()) + assert.Equal(t, a.Hash(), buildTestEncoding(t, fmt.Sprintf(yml, "abc")).Hash()) + }) + } +} + +func TestEncoding_Hash_ExplodePresence(t *testing.T) { + absent := buildTestEncoding(t, "style: form").Hash() + explicitFalse := buildTestEncoding(t, "style: form\nexplode: false").Hash() + explicitTrue := buildTestEncoding(t, "style: form\nexplode: true").Hash() + + assert.NotEqual(t, absent, explicitFalse) + assert.NotEqual(t, absent, explicitTrue) + assert.NotEqual(t, explicitFalse, explicitTrue) + + nested := buildTestEncoding(t, "itemEncoding:\n encoding:\n photo:\n style: form").Hash() + nestedFalse := buildTestEncoding(t, "itemEncoding:\n encoding:\n photo:\n style: form\n explode: false").Hash() + assert.NotEqual(t, nested, nestedFalse) +} + +func TestEncoding_Hash_EmptyPrefixEncodingPresence(t *testing.T) { + low.ClearHashCache() + absent := buildTestEncoding(t, "contentType: multipart/mixed").Hash() + empty := buildTestEncoding(t, "contentType: multipart/mixed\nprefixEncoding: []").Hash() + emptyAgain := buildTestEncoding(t, "contentType: multipart/mixed\nprefixEncoding: []").Hash() + assert.NotEqual(t, absent, empty) + assert.Equal(t, empty, emptyAgain) + + nested := buildTestEncoding(t, "itemEncoding:\n contentType: multipart/mixed").Hash() + nestedEmpty := buildTestEncoding(t, "itemEncoding:\n contentType: multipart/mixed\n prefixEncoding: []").Hash() + assert.NotEqual(t, nested, nestedEmpty) + + buildMediaType := func(yml string) uint64 { + var node yaml.Node + assert.NoError(t, yaml.Unmarshal([]byte(yml), &node)) + var mt MediaType + _ = low.BuildModel(node.Content[0], &mt) + assert.NoError(t, mt.Build(context.Background(), nil, node.Content[0], index.NewSpecIndex(&node))) + return mt.Hash() + } + assert.NotEqual(t, buildMediaType("schema:\n type: array"), + buildMediaType("schema:\n type: array\nprefixEncoding: []")) +} diff --git a/datamodel/low/v3/hash_collision_test.go b/datamodel/low/v3/hash_collision_test.go index 54c13eea..ad4e7c39 100644 --- a/datamodel/low/v3/hash_collision_test.go +++ b/datamodel/low/v3/hash_collision_test.go @@ -70,7 +70,11 @@ func TestHash_FieldsAndKeysDoNotCollide(t *testing.T) { "itemSchema:\n type: string", "encoding:\n first:\n contentType: text/plain", "encoding:\n second:\n contentType: text/plain", - "itemEncoding:\n first:\n contentType: text/plain", + "itemEncoding:\n contentType: text/plain", + "prefixEncoding:\n - contentType: text/plain", + "prefixEncoding:\n - contentType: text/plain\n - contentType: text/plain", + "prefixEncoding:\n - contentType: text/plain\n - contentType: image/png", + "prefixEncoding:\n - contentType: image/png\n - contentType: text/plain", "examples:\n first:\n value: 1", "examples:\n second:\n value: 1", ) @@ -80,6 +84,9 @@ func TestHash_FieldsAndKeysDoNotCollide(t *testing.T) { assertHashesDiffer[Encoding](t, "contentType: form", "style: form", + "encoding:\n first:\n contentType: text/plain", + "prefixEncoding:\n - contentType: text/plain", + "itemEncoding:\n contentType: text/plain", ) }) diff --git a/datamodel/low/v3/media_type.go b/datamodel/low/v3/media_type.go index f93397b0..7bb84346 100644 --- a/datamodel/low/v3/media_type.go +++ b/datamodel/low/v3/media_type.go @@ -21,19 +21,20 @@ import ( // Each Media Type Object provides schema and examples for the media type identified by its key. // - https://spec.openapis.org/oas/v3.1.0#media-type-object type MediaType struct { - Schema low.NodeReference[*base.SchemaProxy] - ItemSchema low.NodeReference[*base.SchemaProxy] - Example low.NodeReference[*yaml.Node] - Examples low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*base.Example]]] - Encoding low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Encoding]]] - ItemEncoding low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Encoding]]] - Extensions *orderedmap.Map[low.KeyReference[string], low.ValueReference[*yaml.Node]] - KeyNode *yaml.Node - RootNode *yaml.Node - index *index.SpecIndex - context context.Context - nodeStore low.NodeLines - reference low.Reference + Schema low.NodeReference[*base.SchemaProxy] + ItemSchema low.NodeReference[*base.SchemaProxy] + Example low.NodeReference[*yaml.Node] + Examples low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*base.Example]]] + Encoding low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Encoding]]] + PrefixEncoding low.NodeReference[[]low.ValueReference[*Encoding]] // OpenAPI 3.2+ + ItemEncoding low.NodeReference[*Encoding] // OpenAPI 3.2+ + Extensions *orderedmap.Map[low.KeyReference[string], low.ValueReference[*yaml.Node]] + KeyNode *yaml.Node + RootNode *yaml.Node + index *index.SpecIndex + context context.Context + nodeStore low.NodeLines + reference low.Reference *low.Reference low.NodeMap } @@ -138,21 +139,9 @@ func (mt *MediaType) Build(ctx context.Context, keyNode, root *yaml.Node, idx *i } - // handle encoding - encs, encsL, encsN, encErr := low.ExtractMap[*Encoding](ctx, EncodingLabel, root, idx) - if encErr != nil { - return encErr - } - if encs != nil { - mt.Encoding = low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Encoding]]]{ - Value: encs, - KeyNode: encsL, - ValueNode: encsN, - } - mt.Nodes.Store(encsL.Line, encsL) - for k, v := range encs.FromOldest() { - v.Value.Nodes.Store(k.KeyNode.Line, k.KeyNode) - } + // handle encoding, prefixEncoding and itemEncoding + if err := extractEncodingFields(ctx, root, idx, mt.Nodes, &mt.Encoding, &mt.PrefixEncoding, &mt.ItemEncoding); err != nil { + return err } // handle itemSchema @@ -168,23 +157,6 @@ func (mt *MediaType) Build(ctx context.Context, keyNode, root *yaml.Node, idx *i mt.Nodes.Store(itemSchLabel.Line, itemSchLabel) } - // handle itemEncoding - itemEncs, itemEncsL, itemEncsN, itemEncErr := low.ExtractMap[*Encoding](ctx, ItemEncodingLabel, root, idx) - if itemEncErr != nil { - return itemEncErr - } - if itemEncs != nil { - mt.ItemEncoding = low.NodeReference[*orderedmap.Map[low.KeyReference[string], low.ValueReference[*Encoding]]]{ - Value: itemEncs, - KeyNode: itemEncsL, - ValueNode: itemEncsN, - } - mt.Nodes.Store(itemEncsL.Line, itemEncsL) - for k, v := range itemEncs.FromOldest() { - v.Value.Nodes.Store(k.KeyNode.Line, k.KeyNode) - } - } - return nil } @@ -202,7 +174,7 @@ func (mt *MediaType) Hash() uint64 { } low.HashMap(h, "examples", mt.Examples.Value) low.HashMap(h, "encoding", mt.Encoding.Value) - low.HashMap(h, "itemEncoding", mt.ItemEncoding.Value) + hashEncodingFields(h, mt.PrefixEncoding, mt.ItemEncoding.Value) for _, ext := range low.HashExtensions(mt.Extensions) { h.WriteString(ext) h.WriteByte(low.HASH_PIPE) diff --git a/datamodel/low/v3/media_type_itemschema_test.go b/datamodel/low/v3/media_type_itemschema_test.go index dd1dba9b..57173df3 100644 --- a/datamodel/low/v3/media_type_itemschema_test.go +++ b/datamodel/low/v3/media_type_itemschema_test.go @@ -62,14 +62,11 @@ itemSchema: metadata: type: object itemEncoding: - file: - contentType: image/jpeg - headers: - X-Custom: - schema: - type: string - metadata: - contentType: application/json` + contentType: image/jpeg + headers: + X-Custom: + schema: + type: string` var idxNode yaml.Node _ = yaml.Unmarshal([]byte(yml), &idxNode) @@ -82,25 +79,10 @@ itemEncoding: err = n.Build(context.Background(), nil, idxNode.Content[0], idx) assert.NoError(t, err) - // Check itemEncoding + // itemEncoding is a single Encoding Object (OpenAPI 3.2) assert.NotNil(t, n.ItemEncoding.Value) - assert.Equal(t, 2, n.ItemEncoding.Value.Len()) - - // Check file encoding - var foundFile, foundMeta bool - for k, v := range n.ItemEncoding.Value.FromOldest() { - if k.Value == "file" { - foundFile = true - assert.Equal(t, "image/jpeg", v.Value.ContentType.Value) - assert.NotNil(t, v.Value.Headers.Value) - } - if k.Value == "metadata" { - foundMeta = true - assert.Equal(t, "application/json", v.Value.ContentType.Value) - } - } - assert.True(t, foundFile, "file encoding should be present") - assert.True(t, foundMeta, "metadata encoding should be present") + assert.Equal(t, "image/jpeg", n.ItemEncoding.Value.ContentType.Value) + assert.Equal(t, 1, n.ItemEncoding.Value.Headers.Value.Len()) } func TestMediaType_Build_ItemSchema_Bad(t *testing.T) { @@ -147,8 +129,7 @@ itemSchema: data: type: object itemEncoding: - data: - contentType: application/json + contentType: application/json encoding: mainField: style: form @@ -173,7 +154,7 @@ example: '{"timestamp":"2025-01-01T00:00:00Z","event":"test","data":{"key":"valu assert.NotNil(t, n.Encoding.Value) assert.NotNil(t, n.ItemEncoding.Value) assert.Equal(t, 1, n.Encoding.Value.Len()) - assert.Equal(t, 1, n.ItemEncoding.Value.Len()) + assert.Equal(t, "application/json", n.ItemEncoding.Value.ContentType.Value) } func TestMediaType_Hash_WithItemSchema(t *testing.T) { @@ -213,14 +194,12 @@ func TestMediaType_Hash_WithItemEncoding(t *testing.T) { yml1 := `schema: type: array itemEncoding: - file: - contentType: image/jpeg` + contentType: image/jpeg` yml2 := `schema: type: array itemEncoding: - file: - contentType: image/png` + contentType: image/png` var idxNode1, idxNode2 yaml.Node _ = yaml.Unmarshal([]byte(yml1), &idxNode1) diff --git a/datamodel/low/v3/media_type_test.go b/datamodel/low/v3/media_type_test.go index 98c27b59..0660b21c 100644 --- a/datamodel/low/v3/media_type_test.go +++ b/datamodel/low/v3/media_type_test.go @@ -115,8 +115,23 @@ func TestMediaType_Build_Fail_Encoding(t *testing.T) { func TestMediaType_Build_Fail_ItemEncoding(t *testing.T) { yml := `itemEncoding: - wiff: - $ref: #bork` + $ref: '#/bork'` + + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var n MediaType + err := low.BuildModel(&idxNode, &n) + assert.NoError(t, err) + + err = n.Build(context.Background(), nil, idxNode.Content[0], idx) + assert.Error(t, err) +} + +func TestMediaType_Build_Fail_PrefixEncoding(t *testing.T) { + yml := `prefixEncoding: + - $ref: '#/bork'` var idxNode yaml.Node _ = yaml.Unmarshal([]byte(yml), &idxNode) @@ -223,3 +238,67 @@ func TestMediaType_Examples_NotFromSchema(t *testing.T) { assert.Equal(t, 0, orderedmap.Len(n.Examples.Value)) } + +// TestMediaType_Build_EncodingFields_DirectKeysOnly checks that encoding, prefixEncoding and itemEncoding are read +// only from the Media Type's own keys, not from inside itemEncoding or an example. +func TestMediaType_Build_EncodingFields_DirectKeysOnly(t *testing.T) { + for name, tc := range map[string]struct { + yml string + itemEncoding bool + }{ + "nested in itemEncoding": {yml: `itemEncoding: + contentType: multipart/form-data + encoding: + photo: + contentType: image/png`, itemEncoding: true}, + "inside example": {yml: `example: + encoding: + photo: + contentType: image/png + itemEncoding: + contentType: text/plain`}, + } { + t.Run(name, func(t *testing.T) { + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(tc.yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var n MediaType + _ = low.BuildModel(idxNode.Content[0], &n) + assert.NoError(t, n.Build(context.Background(), nil, idxNode.Content[0], idx)) + + assert.True(t, n.Encoding.IsEmpty()) + assert.Nil(t, n.FindPropertyEncoding("photo")) + assert.Equal(t, tc.itemEncoding, !n.ItemEncoding.IsEmpty()) + if tc.itemEncoding { + assert.Equal(t, "image/png", n.ItemEncoding.Value.FindEncoding("photo").Value.ContentType.Value) + } else { + // no Encoding is allocated when the media type has no itemEncoding key + assert.Nil(t, n.ItemEncoding.Value) + } + }) + } +} + +// TestMediaType_Build_Encoding_ExtensionPrefixedProperty checks that an encoding entry for a schema property +// whose name starts with x- is kept. +func TestMediaType_Build_Encoding_ExtensionPrefixedProperty(t *testing.T) { + yml := `encoding: + photo: + contentType: image/png + x-file: + contentType: application/pdf +x-custom: true` + + var idxNode yaml.Node + _ = yaml.Unmarshal([]byte(yml), &idxNode) + idx := index.NewSpecIndex(&idxNode) + + var n MediaType + _ = low.BuildModel(idxNode.Content[0], &n) + assert.NoError(t, n.Build(context.Background(), nil, idxNode.Content[0], idx)) + + assert.Equal(t, 2, orderedmap.Len(n.Encoding.Value)) + assert.Equal(t, "application/pdf", n.FindPropertyEncoding("x-file").Value.ContentType.Value) + assert.NotNil(t, n.FindExtension("x-custom")) +} diff --git a/what-changed/model/breaking_rules.go b/what-changed/model/breaking_rules.go index bc5f673a..e126d5e2 100644 --- a/what-changed/model/breaking_rules.go +++ b/what-changed/model/breaking_rules.go @@ -257,18 +257,22 @@ func buildDefaultRules() *BreakingRulesConfig { }, MediaType: &MediaTypeRules{ - Example: rule(false, false, false), - Examples: rule(false, false, false), - Schema: rule(true, false, true), - ItemSchema: rule(true, false, true), - ItemEncoding: rule(false, false, true), + Example: rule(false, false, false), + Examples: rule(false, false, false), + Schema: rule(true, false, true), + ItemSchema: rule(true, false, true), + ItemEncoding: rule(false, false, true), + PrefixEncoding: rule(false, false, true), }, Encoding: &EncodingRules{ - ContentType: rule(true, true, true), - Style: rule(true, true, true), - Explode: rule(true, true, true), - AllowReserved: rule(false, false, false), + ContentType: rule(true, true, true), + Style: rule(true, true, true), + Explode: rule(true, true, true), + AllowReserved: rule(false, false, false), + Encoding: rule(false, false, true), + PrefixEncoding: rule(false, false, true), + ItemEncoding: rule(false, false, true), }, Header: &HeaderRules{ diff --git a/what-changed/model/breaking_rules_config_test.go b/what-changed/model/breaking_rules_config_test.go index e97ee25a..9b22f12a 100644 --- a/what-changed/model/breaking_rules_config_test.go +++ b/what-changed/model/breaking_rules_config_test.go @@ -27,6 +27,24 @@ xml: assert.Nil(t, result, "Valid config should return nil") } +// The Encoding Object has a property named encoding, so encoding.encoding is a rule, not a nested component. +func TestValidateBreakingRulesConfigYAML_EncodingProperties(t *testing.T) { + yaml := ` +mediaType: + prefixEncoding: + removed: false +encoding: + encoding: + removed: false + prefixEncoding: + added: true + itemEncoding: + modified: true +` + result := ValidateBreakingRulesConfigYAML([]byte(yaml)) + assert.Nil(t, result, "Valid config should return nil") +} + func TestValidateBreakingRulesConfigYAML_NestedDiscriminator(t *testing.T) { // Nest 'discriminator' under 'response' where it's NOT a valid property // (discriminator IS valid under schema, so we use response instead) diff --git a/what-changed/model/breaking_rules_constants.go b/what-changed/model/breaking_rules_constants.go index 36544361..c442870e 100644 --- a/what-changed/model/breaking_rules_constants.go +++ b/what-changed/model/breaking_rules_constants.go @@ -107,6 +107,8 @@ const ( PropIn = "in" PropItems = "items" PropItemEncoding = "itemEncoding" + PropPrefixEncoding = "prefixEncoding" + PropEncoding = "encoding" PropItemSchema = "itemSchema" PropKind = "kind" PropLicense = "license" diff --git a/what-changed/model/breaking_rules_model.go b/what-changed/model/breaking_rules_model.go index f2cf52d7..48d8787c 100644 --- a/what-changed/model/breaking_rules_model.go +++ b/what-changed/model/breaking_rules_model.go @@ -114,19 +114,23 @@ type ResponseRules struct { // MediaTypeRules defines breaking rules for the Media Type object properties. type MediaTypeRules struct { - Example *BreakingChangeRule `json:"example,omitempty" yaml:"example,omitempty"` - Examples *BreakingChangeRule `json:"examples,omitempty" yaml:"examples,omitempty"` - Schema *BreakingChangeRule `json:"schema,omitempty" yaml:"schema,omitempty"` - ItemSchema *BreakingChangeRule `json:"itemSchema,omitempty" yaml:"itemSchema,omitempty"` - ItemEncoding *BreakingChangeRule `json:"itemEncoding,omitempty" yaml:"itemEncoding,omitempty"` + Example *BreakingChangeRule `json:"example,omitempty" yaml:"example,omitempty"` + Examples *BreakingChangeRule `json:"examples,omitempty" yaml:"examples,omitempty"` + Schema *BreakingChangeRule `json:"schema,omitempty" yaml:"schema,omitempty"` + ItemSchema *BreakingChangeRule `json:"itemSchema,omitempty" yaml:"itemSchema,omitempty"` + ItemEncoding *BreakingChangeRule `json:"itemEncoding,omitempty" yaml:"itemEncoding,omitempty"` + PrefixEncoding *BreakingChangeRule `json:"prefixEncoding,omitempty" yaml:"prefixEncoding,omitempty"` } // EncodingRules defines breaking rules for the Encoding object properties. type EncodingRules struct { - ContentType *BreakingChangeRule `json:"contentType,omitempty" yaml:"contentType,omitempty"` - Style *BreakingChangeRule `json:"style,omitempty" yaml:"style,omitempty"` - Explode *BreakingChangeRule `json:"explode,omitempty" yaml:"explode,omitempty"` - AllowReserved *BreakingChangeRule `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"` + ContentType *BreakingChangeRule `json:"contentType,omitempty" yaml:"contentType,omitempty"` + Style *BreakingChangeRule `json:"style,omitempty" yaml:"style,omitempty"` + Explode *BreakingChangeRule `json:"explode,omitempty" yaml:"explode,omitempty"` + AllowReserved *BreakingChangeRule `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"` + Encoding *BreakingChangeRule `json:"encoding,omitempty" yaml:"encoding,omitempty"` + PrefixEncoding *BreakingChangeRule `json:"prefixEncoding,omitempty" yaml:"prefixEncoding,omitempty"` + ItemEncoding *BreakingChangeRule `json:"itemEncoding,omitempty" yaml:"itemEncoding,omitempty"` } // HeaderRules defines breaking rules for the Header object properties. diff --git a/what-changed/model/breaking_rules_test.go b/what-changed/model/breaking_rules_test.go index 40be200d..152f0ffd 100644 --- a/what-changed/model/breaking_rules_test.go +++ b/what-changed/model/breaking_rules_test.go @@ -305,7 +305,12 @@ func TestGetRule_AllComponents(t *testing.T) { {"response", "description"}, {"mediaType", "schema"}, {"mediaType", "examples"}, + {"mediaType", "itemEncoding"}, + {"mediaType", "prefixEncoding"}, {"encoding", "contentType"}, + {"encoding", "encoding"}, + {"encoding", "prefixEncoding"}, + {"encoding", "itemEncoding"}, {"header", "required"}, {"header", "examples"}, {"schema", "type"}, diff --git a/what-changed/model/encoding.go b/what-changed/model/encoding.go index f4252016..b335e27b 100644 --- a/what-changed/model/encoding.go +++ b/what-changed/model/encoding.go @@ -4,13 +4,23 @@ package model import ( + "github.com/pb33f/libopenapi/datamodel/low" v3 "github.com/pb33f/libopenapi/datamodel/low/v3" + "github.com/pb33f/libopenapi/orderedmap" ) // EncodingChanges represent all the changes made to an Encoding object type EncodingChanges struct { *PropertyChanges - HeaderChanges map[string]*HeaderChanges `json:"headers,omitempty" yaml:"headers,omitempty"` + HeaderChanges map[string]*HeaderChanges `json:"headers,omitempty" yaml:"headers,omitempty"` + EncodingChanges map[string]*EncodingChanges `json:"encoding,omitempty" yaml:"encoding,omitempty"` + PrefixEncodingChanges []*EncodingChanges `json:"prefixEncoding,omitempty" yaml:"prefixEncoding,omitempty"` + ItemEncodingChanges *EncodingChanges `json:"itemEncoding,omitempty" yaml:"itemEncoding,omitempty"` + ExtensionChanges *ExtensionChanges `json:"extensions,omitempty" yaml:"extensions,omitempty"` + + // Index is the position in the prefixEncoding array of the part these changes belong to. It is set only for + // entries of PrefixEncodingChanges, which list changed parts only. + Index *int `json:"index,omitempty" yaml:"index,omitempty"` } // GetAllChanges returns a slice of all changes made between Encoding objects @@ -23,6 +33,14 @@ func (e *EncodingChanges) GetAllChanges() []*Change { for k := range e.HeaderChanges { changes = append(changes, e.HeaderChanges[k].GetAllChanges()...) } + for k := range e.EncodingChanges { + changes = append(changes, e.EncodingChanges[k].GetAllChanges()...) + } + for k := range e.PrefixEncodingChanges { + changes = append(changes, e.PrefixEncodingChanges[k].GetAllChanges()...) + } + changes = append(changes, e.ItemEncodingChanges.GetAllChanges()...) + changes = append(changes, e.ExtensionChanges.GetAllChanges()...) return changes } @@ -37,17 +55,35 @@ func (e *EncodingChanges) TotalChanges() int { c += e.HeaderChanges[i].TotalChanges() } } + for k := range e.EncodingChanges { + c += e.EncodingChanges[k].TotalChanges() + } + for k := range e.PrefixEncodingChanges { + c += e.PrefixEncodingChanges[k].TotalChanges() + } + c += e.ItemEncodingChanges.TotalChanges() + c += e.ExtensionChanges.TotalChanges() return c } // TotalBreakingChanges returns the number of changes made between two Encoding objects that were breaking. func (e *EncodingChanges) TotalBreakingChanges() int { + if e == nil { + return 0 + } c := e.PropertyChanges.TotalBreakingChanges() if e.HeaderChanges != nil { for i := range e.HeaderChanges { c += e.HeaderChanges[i].TotalBreakingChanges() } } + for k := range e.EncodingChanges { + c += e.EncodingChanges[k].TotalBreakingChanges() + } + for k := range e.PrefixEncodingChanges { + c += e.PrefixEncodingChanges[k].TotalBreakingChanges() + } + c += e.ItemEncodingChanges.TotalBreakingChanges() return c } @@ -78,9 +114,82 @@ func CompareEncoding(l, r *v3.Encoding) *EncodingChanges { // headers ec.HeaderChanges = CheckMapForChanges(l.Headers.Value, r.Headers.Value, &changes, v3.HeadersLabel, CompareHeadersV3) + + // nested encoding, prefixEncoding, itemEncoding (OpenAPI 3.2+) + ec.EncodingChanges, ec.PrefixEncodingChanges, ec.ItemEncodingChanges = compareEncodingFields( + CompEncoding, l.Encoding.Value, r.Encoding.Value, l.PrefixEncoding, r.PrefixEncoding, + l.ItemEncoding, r.ItemEncoding, &changes, true) + ec.ExtensionChanges = CompareExtensions(l.Extensions, r.Extensions) ec.PropertyChanges = NewPropertyChanges(changes) if ec.TotalChanges() <= 0 { return nil } return ec } + +// compareEncodingFields compares the encoding, prefixEncoding and itemEncoding fields shared by the Media Type +// Object and the Encoding Object. prefixEncoding entries are compared by position, because each one applies to the +// part at its position. The encoding map uses the component's breaking rules only when withEncodingRule is set. +// The Media Type Object's encoding map predates the rules system and keeps its hardcoded behavior. +func compareEncodingFields(component string, + lEnc, rEnc *orderedmap.Map[low.KeyReference[string], low.ValueReference[*v3.Encoding]], + lPrefix, rPrefix low.NodeReference[[]low.ValueReference[*v3.Encoding]], + lItem, rItem low.NodeReference[*v3.Encoding], + changes *[]*Change, withEncodingRule bool, +) (map[string]*EncodingChanges, []*EncodingChanges, *EncodingChanges) { + var encChanges map[string]*EncodingChanges + if withEncodingRule { + encChanges = CheckMapForChangesWithRules(lEnc, rEnc, changes, v3.EncodingLabel, CompareEncoding, + component, PropEncoding) + } else { + encChanges = CheckMapForChanges(lEnc, rEnc, changes, v3.EncodingLabel, CompareEncoding) + } + + // each changed, added or removed part gets its own entry, carrying its array position in Index. + var prefixChanges []*EncodingChanges + lp, rp := lPrefix.Value, rPrefix.Value + for i := 0; i < len(lp) || i < len(rp); i++ { + var ch *EncodingChanges + switch { + case i >= len(rp): + var partChanges []*Change + CreateChange(&partChanges, ObjectRemoved, v3.PrefixEncodingLabel, lp[i].ValueNode, nil, + BreakingRemoved(component, PropPrefixEncoding), lp[i].Value, nil) + ch = &EncodingChanges{PropertyChanges: NewPropertyChanges(partChanges)} + case i >= len(lp): + var partChanges []*Change + CreateChange(&partChanges, ObjectAdded, v3.PrefixEncodingLabel, nil, rp[i].ValueNode, + BreakingAdded(component, PropPrefixEncoding), nil, rp[i].Value) + ch = &EncodingChanges{PropertyChanges: NewPropertyChanges(partChanges)} + default: + ch = CompareEncoding(lp[i].Value, rp[i].Value) + } + if ch != nil { + ch.Index = &i + prefixChanges = append(prefixChanges, ch) + } + } + + // an empty prefixEncoding has no parts to report, so adding or removing one is reported on the field itself. + switch { + case !lPrefix.IsEmpty() && rPrefix.IsEmpty() && len(lp) == 0: + CreateChange(changes, PropertyRemoved, v3.PrefixEncodingLabel, lPrefix.ValueNode, nil, + BreakingRemoved(component, PropPrefixEncoding), lp, nil) + case lPrefix.IsEmpty() && !rPrefix.IsEmpty() && len(rp) == 0: + CreateChange(changes, PropertyAdded, v3.PrefixEncodingLabel, nil, rPrefix.ValueNode, + BreakingAdded(component, PropPrefixEncoding), nil, rp) + } + + var itemChanges *EncodingChanges + switch { + case !lItem.IsEmpty() && !rItem.IsEmpty(): + itemChanges = CompareEncoding(lItem.Value, rItem.Value) + case !lItem.IsEmpty(): + CreateChange(changes, ObjectRemoved, v3.ItemEncodingLabel, lItem.ValueNode, nil, + BreakingRemoved(component, PropItemEncoding), lItem.Value, nil) + case !rItem.IsEmpty(): + CreateChange(changes, ObjectAdded, v3.ItemEncodingLabel, nil, rItem.ValueNode, + BreakingAdded(component, PropItemEncoding), nil, rItem.Value) + } + return encChanges, prefixChanges, itemChanges +} diff --git a/what-changed/model/media_type.go b/what-changed/model/media_type.go index 3ab54277..3c78c036 100644 --- a/what-changed/model/media_type.go +++ b/what-changed/model/media_type.go @@ -11,12 +11,13 @@ import ( // MediaTypeChanges represent changes made between two OpenAPI MediaType instances. type MediaTypeChanges struct { *PropertyChanges - SchemaChanges *SchemaChanges `json:"schemas,omitempty" yaml:"schemas,omitempty"` - ItemSchemaChanges *SchemaChanges `json:"itemSchemas,omitempty" yaml:"itemSchemas,omitempty"` - ExtensionChanges *ExtensionChanges `json:"extensions,omitempty" yaml:"extensions,omitempty"` - ExampleChanges map[string]*ExampleChanges `json:"examples,omitempty" yaml:"examples,omitempty"` - EncodingChanges map[string]*EncodingChanges `json:"encoding,omitempty" yaml:"encoding,omitempty"` - ItemEncodingChanges map[string]*EncodingChanges `json:"itemEncoding,omitempty" yaml:"itemEncoding,omitempty"` + SchemaChanges *SchemaChanges `json:"schemas,omitempty" yaml:"schemas,omitempty"` + ItemSchemaChanges *SchemaChanges `json:"itemSchemas,omitempty" yaml:"itemSchemas,omitempty"` + ExtensionChanges *ExtensionChanges `json:"extensions,omitempty" yaml:"extensions,omitempty"` + ExampleChanges map[string]*ExampleChanges `json:"examples,omitempty" yaml:"examples,omitempty"` + EncodingChanges map[string]*EncodingChanges `json:"encoding,omitempty" yaml:"encoding,omitempty"` + PrefixEncodingChanges []*EncodingChanges `json:"prefixEncoding,omitempty" yaml:"prefixEncoding,omitempty"` + ItemEncodingChanges *EncodingChanges `json:"itemEncoding,omitempty" yaml:"itemEncoding,omitempty"` } // GetAllChanges returns a slice of all changes made between MediaType objects @@ -38,9 +39,10 @@ func (m *MediaTypeChanges) GetAllChanges() []*Change { for k := range m.EncodingChanges { changes = append(changes, m.EncodingChanges[k].GetAllChanges()...) } - for k := range m.ItemEncodingChanges { - changes = append(changes, m.ItemEncodingChanges[k].GetAllChanges()...) + for k := range m.PrefixEncodingChanges { + changes = append(changes, m.PrefixEncodingChanges[k].GetAllChanges()...) } + changes = append(changes, m.ItemEncodingChanges.GetAllChanges()...) if m.ExtensionChanges != nil { changes = append(changes, m.ExtensionChanges.GetAllChanges()...) } @@ -67,11 +69,10 @@ func (m *MediaTypeChanges) TotalChanges() int { c += m.EncodingChanges[i].TotalChanges() } } - if len(m.ItemEncodingChanges) > 0 { - for i := range m.ItemEncodingChanges { - c += m.ItemEncodingChanges[i].TotalChanges() - } + for i := range m.PrefixEncodingChanges { + c += m.PrefixEncodingChanges[i].TotalChanges() } + c += m.ItemEncodingChanges.TotalChanges() if m.ExtensionChanges != nil { c += m.ExtensionChanges.TotalChanges() } @@ -95,11 +96,10 @@ func (m *MediaTypeChanges) TotalBreakingChanges() int { c += m.EncodingChanges[i].TotalBreakingChanges() } } - if len(m.ItemEncodingChanges) > 0 { - for i := range m.ItemEncodingChanges { - c += m.ItemEncodingChanges[i].TotalBreakingChanges() - } + for i := range m.PrefixEncodingChanges { + c += m.PrefixEncodingChanges[i].TotalBreakingChanges() } + c += m.ItemEncodingChanges.TotalBreakingChanges() return c } @@ -143,9 +143,10 @@ func CompareMediaTypes(l, r *v3.MediaType) *MediaTypeChanges { mc.ExampleChanges = CheckExampleMapForChangesWithNilSupportAndRules(l.Examples.Value, r.Examples.Value, &changes, v3.ExamplesLabel, CompMediaType, PropExamples) - // encoding - mc.EncodingChanges = CheckMapForChanges(l.Encoding.Value, r.Encoding.Value, - &changes, v3.EncodingLabel, CompareEncoding) + // encoding, prefixEncoding, itemEncoding + mc.EncodingChanges, mc.PrefixEncodingChanges, mc.ItemEncodingChanges = compareEncodingFields( + CompMediaType, l.Encoding.Value, r.Encoding.Value, l.PrefixEncoding, r.PrefixEncoding, + l.ItemEncoding, r.ItemEncoding, &changes, false) // itemSchema if !l.ItemSchema.IsEmpty() && !r.ItemSchema.IsEmpty() { @@ -160,10 +161,6 @@ func CompareMediaTypes(l, r *v3.MediaType) *MediaTypeChanges { r.ItemSchema.ValueNode, BreakingAdded(CompMediaType, PropItemSchema), nil, r.ItemSchema.Value) } - // itemEncoding - mc.ItemEncodingChanges = CheckMapForChanges(l.ItemEncoding.Value, r.ItemEncoding.Value, - &changes, v3.ItemEncodingLabel, CompareEncoding) - mc.ExtensionChanges = CompareExtensions(l.Extensions, r.Extensions) mc.PropertyChanges = NewPropertyChanges(changes) return mc diff --git a/what-changed/model/media_type_test.go b/what-changed/model/media_type_test.go index 0858e526..b16d62ad 100644 --- a/what-changed/model/media_type_test.go +++ b/what-changed/model/media_type_test.go @@ -5,6 +5,7 @@ package model import ( "context" + "encoding/json" "testing" "github.com/pb33f/go-yaml" @@ -67,7 +68,7 @@ encoding: itemSchema: type: string itemEncoding: - - contentType: application/json` + contentType: application/json` right := `schema: type: string @@ -99,7 +100,8 @@ itemEncoding: assert.NotNil(t, extChanges) assert.Equal(t, 3, extChanges.TotalChanges()) assert.Len(t, extChanges.GetAllChanges(), 3) - assert.Equal(t, 1, extChanges.TotalBreakingChanges()) + // itemSchema type and itemEncoding contentType are both breaking modifications + assert.Equal(t, 2, extChanges.TotalBreakingChanges()) assert.Equal(t, Modified, extChanges.Changes[0].ChangeType) assert.Equal(t, v3.ExampleLabel, extChanges.Changes[0].Property) } @@ -365,8 +367,7 @@ examples: exampleOne: value: yummy coffee itemEncoding: - cupOfTea: - contentType: milk/hotwater + contentType: milk/hotwater encoding: something: contentType: application/json @@ -379,8 +380,7 @@ examples: exampleOne: value: yummy coffee is great! itemEncoding: - cupOfTea: - contentType: milk/hotwater/sugar + contentType: milk/hotwater/sugar encoding: something: contentType: application/xml @@ -547,9 +547,8 @@ func TestCompareMediaTypes_ItemEncodingAdded(t *testing.T) { right := `schema: type: array itemEncoding: - file: - contentType: image/jpeg - allowReserved: true` + contentType: image/jpeg + allowReserved: true` var lNode, rNode yaml.Node _ = yaml.Unmarshal([]byte(left), &lNode) @@ -583,16 +582,14 @@ func TestCompareMediaTypes_ItemEncodingModified(t *testing.T) { left := `schema: type: array itemEncoding: - file: - contentType: image/jpeg - allowReserved: true` + contentType: image/jpeg + allowReserved: true` right := `schema: type: array itemEncoding: - file: - contentType: image/png - allowReserved: false` + contentType: image/png + allowReserved: false` var lNode, rNode yaml.Node _ = yaml.Unmarshal([]byte(left), &lNode) @@ -611,7 +608,7 @@ itemEncoding: assert.NotNil(t, changes) assert.NotNil(t, changes.ItemEncodingChanges) - assert.Equal(t, 1, len(changes.ItemEncodingChanges)) + assert.Equal(t, 2, changes.ItemEncodingChanges.TotalChanges()) assert.Greater(t, changes.TotalChanges(), 0) } @@ -625,8 +622,7 @@ encoding: field1: contentType: text/plain itemEncoding: - stream1: - contentType: application/json` + contentType: application/json` right := `schema: type: object @@ -634,8 +630,7 @@ encoding: field1: contentType: text/html itemEncoding: - stream1: - contentType: application/xml` + contentType: application/xml` var lNode, rNode yaml.Node _ = yaml.Unmarshal([]byte(left), &lNode) @@ -656,7 +651,7 @@ itemEncoding: assert.NotNil(t, changes.EncodingChanges) assert.NotNil(t, changes.ItemEncodingChanges) assert.Equal(t, 1, len(changes.EncodingChanges)) - assert.Equal(t, 1, len(changes.ItemEncodingChanges)) + assert.Equal(t, 1, changes.ItemEncodingChanges.TotalChanges()) assert.Greater(t, changes.TotalChanges(), 1) // At least 2 changes } @@ -672,8 +667,7 @@ itemSchema: id: type: string itemEncoding: - id: - contentType: text/plain` + contentType: text/plain` var lNode, rNode yaml.Node _ = yaml.Unmarshal([]byte(yml), &lNode) @@ -705,8 +699,7 @@ func TestMediaTypeChanges_GetAllChanges_WithItemFields(t *testing.T) { itemSchema: type: object itemEncoding: - field: - contentType: application/json` + contentType: application/json` var lNode, rNode yaml.Node _ = yaml.Unmarshal([]byte(left), &lNode) @@ -866,3 +859,349 @@ examples: assert.Equal(t, 1, changes.ExampleChanges["oldExample"].TotalChanges()) assert.Equal(t, ObjectRemoved, changes.ExampleChanges["oldExample"].Changes[0].ChangeType) } + +func compareMediaTypeYAML(t *testing.T, left, right string) *MediaTypeChanges { + t.Helper() + var lNode, rNode yaml.Node + _ = yaml.Unmarshal([]byte(left), &lNode) + _ = yaml.Unmarshal([]byte(right), &rNode) + var lMt, rMt v3.MediaType + _ = low.BuildModel(&lNode, &lMt) + _ = low.BuildModel(&rNode, &rMt) + assert.NoError(t, lMt.Build(context.Background(), nil, lNode.Content[0], index.NewSpecIndex(&lNode))) + assert.NoError(t, rMt.Build(context.Background(), nil, rNode.Content[0], index.NewSpecIndex(&rNode))) + return CompareMediaTypes(&lMt, &rMt) +} + +func TestCompareMediaTypes_PrefixEncoding(t *testing.T) { + low.ClearHashCache() + ResetActiveBreakingRulesConfig() + + left := `prefixEncoding: + - contentType: application/json + - contentType: image/png` + + // modified by position + changes := compareMediaTypeYAML(t, left, `prefixEncoding: + - contentType: application/json + - contentType: image/gif`) + assert.NotNil(t, changes) + assert.Len(t, changes.PrefixEncodingChanges, 1) + assert.Equal(t, 1, changes.TotalChanges()) + assert.Equal(t, 1, changes.TotalBreakingChanges()) + assert.Len(t, changes.GetAllChanges(), 1) + + // removing a positional entry is breaking + changes = compareMediaTypeYAML(t, left, `prefixEncoding: + - contentType: application/json`) + assert.NotNil(t, changes) + assert.Equal(t, 1, changes.TotalChanges()) + assert.Equal(t, 1, changes.TotalBreakingChanges()) + assert.Equal(t, v3.PrefixEncodingLabel, changes.GetAllChanges()[0].Property) + + // adding one is not + changes = compareMediaTypeYAML(t, left, left+` + - contentType: text/plain`) + assert.NotNil(t, changes) + assert.Equal(t, 1, changes.TotalChanges()) + assert.Equal(t, 0, changes.TotalBreakingChanges()) + + // reordering changes the entry at both positions + changes = compareMediaTypeYAML(t, left, `prefixEncoding: + - contentType: image/png + - contentType: application/json`) + assert.NotNil(t, changes) + assert.Len(t, changes.PrefixEncodingChanges, 2) +} + +func TestCompareMediaTypes_ItemEncodingRemovedIsBreaking(t *testing.T) { + low.ClearHashCache() + ResetActiveBreakingRulesConfig() + + changes := compareMediaTypeYAML(t, `schema: + type: array +itemEncoding: + contentType: image/png`, `schema: + type: array`) + assert.NotNil(t, changes) + assert.Equal(t, 1, changes.TotalBreakingChanges()) +} + +func TestCompareMediaTypes_NestedEncoding(t *testing.T) { + low.ClearHashCache() + ResetActiveBreakingRulesConfig() + + changes := compareMediaTypeYAML(t, `encoding: + batch: + contentType: multipart/mixed + prefixEncoding: + - contentType: application/json + itemEncoding: + contentType: image/png + encoding: + inner: + contentType: text/plain`, `encoding: + batch: + contentType: multipart/mixed + prefixEncoding: + - contentType: application/xml + itemEncoding: + contentType: image/gif`) + assert.NotNil(t, changes) + batch := changes.EncodingChanges["batch"] + assert.NotNil(t, batch) + assert.Len(t, batch.PrefixEncodingChanges, 1) + assert.NotNil(t, batch.ItemEncodingChanges) + // prefixEncoding[0].contentType, itemEncoding.contentType, encoding.inner removed + assert.Equal(t, 3, changes.TotalChanges()) + assert.Equal(t, 3, changes.TotalBreakingChanges()) +} + +func TestCompareMediaTypes_NestedEncoding_Modified(t *testing.T) { + low.ClearHashCache() + ResetActiveBreakingRulesConfig() + + changes := compareMediaTypeYAML(t, `encoding: + batch: + encoding: + inner: + contentType: text/plain + prefixEncoding: + - itemEncoding: + contentType: image/png`, `encoding: + batch: + encoding: + inner: + contentType: text/csv + prefixEncoding: + - itemEncoding: + contentType: image/gif`) + assert.NotNil(t, changes) + batch := changes.EncodingChanges["batch"] + assert.NotNil(t, batch) + assert.NotNil(t, batch.EncodingChanges["inner"]) + assert.NotNil(t, batch.PrefixEncodingChanges[0].ItemEncodingChanges) + // encoding.inner.contentType and prefixEncoding[0].itemEncoding.contentType + assert.Equal(t, 2, changes.TotalChanges()) + assert.Equal(t, 2, changes.TotalBreakingChanges()) + assert.Len(t, changes.GetAllChanges(), 2) +} + +func TestCompareMediaTypes_EncodingRulesConfigurable(t *testing.T) { + low.ClearHashCache() + // the cached defaults are merged into below, so they are rebuilt afterwards. + defer ResetDefaultBreakingRules() + defer ResetActiveBreakingRulesConfig() + + config := GenerateDefaultBreakingRules() + config.Merge(&BreakingRulesConfig{ + MediaType: &MediaTypeRules{PrefixEncoding: rule(false, false, false)}, + Encoding: &EncodingRules{ItemEncoding: rule(false, false, false)}, + }) + SetActiveBreakingRulesConfig(config) + + changes := compareMediaTypeYAML(t, `prefixEncoding: + - contentType: application/json +encoding: + batch: + itemEncoding: + contentType: image/png`, `encoding: + batch: {}`) + assert.NotNil(t, changes) + assert.Equal(t, 2, changes.TotalChanges()) + assert.Equal(t, 0, changes.TotalBreakingChanges()) +} + +func TestCompareMediaTypes_EncodingExtensions(t *testing.T) { + low.ClearHashCache() + ResetActiveBreakingRulesConfig() + + changes := compareMediaTypeYAML(t, `encoding: + photo: + contentType: image/png + x-vendor: abc + x-file: + contentType: application/pdf +prefixEncoding: + - contentType: application/json + x-part: first +itemEncoding: + contentType: image/png + x-item: abc`, `encoding: + photo: + contentType: image/png + x-vendor: xyz + x-file: + contentType: application/pdf +prefixEncoding: + - contentType: application/json + x-part: second +itemEncoding: + contentType: image/png`) + if !assert.NotNil(t, changes) { + return + } + assert.Nil(t, changes.ExtensionChanges) + + extensionChange := func(ec *EncodingChanges) *Change { + if assert.NotNil(t, ec) && assert.NotNil(t, ec.ExtensionChanges) && assert.Len(t, ec.ExtensionChanges.Changes, 1) { + return ec.ExtensionChanges.Changes[0] + } + return &Change{} + } + photo := extensionChange(changes.EncodingChanges["photo"]) + assert.Equal(t, Modified, photo.ChangeType) + assert.Equal(t, "x-vendor", photo.Property) + if assert.Len(t, changes.PrefixEncodingChanges, 1) { + assert.Equal(t, Modified, extensionChange(changes.PrefixEncodingChanges[0]).ChangeType) + } + item := extensionChange(changes.ItemEncodingChanges) + assert.Equal(t, ObjectRemoved, item.ChangeType) + assert.Equal(t, "x-item", item.Property) + + assert.Equal(t, 3, changes.TotalChanges()) + assert.Len(t, changes.GetAllChanges(), 3) + assert.Equal(t, 0, changes.TotalBreakingChanges()) +} + +func TestCompareMediaTypes_EncodingExplodeAdded(t *testing.T) { + for name, yml := range map[string][2]string{ + "top level": {"encoding:\n photo:\n style: form", + "encoding:\n photo:\n style: form\n explode: false"}, + "nested under itemEncoding": {"itemEncoding:\n encoding:\n photo:\n style: form", + "itemEncoding:\n encoding:\n photo:\n style: form\n explode: false"}, + } { + t.Run(name, func(t *testing.T) { + low.ClearHashCache() + ResetActiveBreakingRulesConfig() + + changes := compareMediaTypeYAML(t, yml[0], yml[1]) + assert.NotNil(t, changes) + all := changes.GetAllChanges() + if assert.Len(t, all, 1) { + assert.Equal(t, PropertyAdded, all[0].ChangeType) + assert.Equal(t, v3.ExplodeLabel, all[0].Property) + } + + assert.Nil(t, compareMediaTypeYAML(t, yml[1], yml[1])) + }) + } +} + +func TestCompareMediaTypes_EmptyPrefixEncodingPresence(t *testing.T) { + low.ClearHashCache() + ResetActiveBreakingRulesConfig() + + absent := "schema:\n type: array" + empty := "schema:\n type: array\nprefixEncoding: []" + + // removing an empty prefixEncoding is classified like removing an entry: breaking. + changes := compareMediaTypeYAML(t, empty, absent) + if assert.NotNil(t, changes) && assert.Len(t, changes.Changes, 1) { + assert.Equal(t, PropertyRemoved, changes.Changes[0].ChangeType) + assert.Equal(t, v3.PrefixEncodingLabel, changes.Changes[0].Property) + assert.True(t, changes.Changes[0].Breaking) + assert.Equal(t, 1, changes.TotalBreakingChanges()) + } + + // adding one is not breaking. + changes = compareMediaTypeYAML(t, absent, empty) + if assert.NotNil(t, changes) && assert.Len(t, changes.Changes, 1) { + assert.Equal(t, PropertyAdded, changes.Changes[0].ChangeType) + assert.False(t, changes.Changes[0].Breaking) + assert.Equal(t, 0, changes.TotalBreakingChanges()) + } + + assert.Nil(t, compareMediaTypeYAML(t, empty, empty)) + + // the same on a nested encoding entry. + nested := compareMediaTypeYAML(t, "encoding:\n batch:\n prefixEncoding: []", "encoding:\n batch: {}") + if assert.NotNil(t, nested) && assert.NotNil(t, nested.EncodingChanges["batch"]) { + batch := nested.EncodingChanges["batch"] + if assert.Len(t, batch.Changes, 1) { + assert.Equal(t, PropertyRemoved, batch.Changes[0].ChangeType) + assert.Equal(t, v3.PrefixEncodingLabel, batch.Changes[0].Property) + } + assert.Equal(t, 1, nested.TotalBreakingChanges()) + } + nested = compareMediaTypeYAML(t, "itemEncoding:\n contentType: multipart/mixed", + "itemEncoding:\n contentType: multipart/mixed\n prefixEncoding: []") + if assert.NotNil(t, nested) && assert.NotNil(t, nested.ItemEncodingChanges) { + assert.Equal(t, 1, nested.TotalChanges()) + assert.Equal(t, PropertyAdded, nested.ItemEncodingChanges.Changes[0].ChangeType) + } +} + +// prefixIndex returns the Index of a prefixEncoding entry, or -1 when it is not set. +func prefixIndex(ch *EncodingChanges) int { + if ch.Index == nil { + return -1 + } + return *ch.Index +} + +func TestCompareMediaTypes_PrefixEncodingIndex(t *testing.T) { + low.ClearHashCache() + ResetActiveBreakingRulesConfig() + + left := `prefixEncoding: + - contentType: a/a + - contentType: b/b + - contentType: c/c` + + // only the second part changes, so the one entry carries index 1. + changes := compareMediaTypeYAML(t, left, `prefixEncoding: + - contentType: a/a + - contentType: x/x + - contentType: c/c`) + if assert.NotNil(t, changes) && assert.Len(t, changes.PrefixEncodingChanges, 1) { + assert.Equal(t, 1, prefixIndex(changes.PrefixEncodingChanges[0])) + out, err := json.Marshal(changes) + assert.NoError(t, err) + assert.Contains(t, string(out), `"index":1`) + } + + // the first and third parts change, the second is unchanged and skipped. + changes = compareMediaTypeYAML(t, left, `prefixEncoding: + - contentType: x/x + - contentType: b/b + - contentType: y/y`) + if assert.NotNil(t, changes) && assert.Len(t, changes.PrefixEncodingChanges, 2) { + assert.Equal(t, 0, prefixIndex(changes.PrefixEncodingChanges[0])) + assert.Equal(t, 2, prefixIndex(changes.PrefixEncodingChanges[1])) + assert.Equal(t, "y/y", changes.PrefixEncodingChanges[1].Changes[0].New) + out, err := json.Marshal(changes) + assert.NoError(t, err) + assert.Contains(t, string(out), `"index":0`) + } + + // a removed part carries its index, and is breaking. + changes = compareMediaTypeYAML(t, left, `prefixEncoding: + - contentType: a/a + - contentType: b/b`) + if assert.NotNil(t, changes) && assert.Len(t, changes.PrefixEncodingChanges, 1) { + removed := changes.PrefixEncodingChanges[0] + assert.Equal(t, 2, prefixIndex(removed)) + assert.Equal(t, ObjectRemoved, removed.Changes[0].ChangeType) + assert.Equal(t, v3.PrefixEncodingLabel, removed.Changes[0].Property) + assert.Equal(t, 1, changes.TotalBreakingChanges()) + } + + // an added part carries its index, and is not breaking. + changes = compareMediaTypeYAML(t, left, left+` + - contentType: d/d`) + if assert.NotNil(t, changes) && assert.Len(t, changes.PrefixEncodingChanges, 1) { + added := changes.PrefixEncodingChanges[0] + assert.Equal(t, 3, prefixIndex(added)) + assert.Equal(t, ObjectAdded, added.Changes[0].ChangeType) + assert.Equal(t, 0, changes.TotalBreakingChanges()) + } + + // nested prefixEncoding entries carry their index too. + changes = compareMediaTypeYAML(t, "encoding:\n batch:\n prefixEncoding:\n - contentType: a/a\n - contentType: b/b", + "encoding:\n batch:\n prefixEncoding:\n - contentType: a/a\n - contentType: x/x") + if assert.NotNil(t, changes) && assert.NotNil(t, changes.EncodingChanges["batch"]) && + assert.Len(t, changes.EncodingChanges["batch"].PrefixEncodingChanges, 1) { + assert.Equal(t, 1, prefixIndex(changes.EncodingChanges["batch"].PrefixEncodingChanges[0])) + } +}