Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 80 additions & 0 deletions MIGRATING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
27 changes: 26 additions & 1 deletion datamodel/high/v3/encoding.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
}

Expand Down Expand Up @@ -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

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 1f5ea31. Whether the field is present is now carried all the way through:

  • extractEncodingSlice takes the NodeReference. An absent field gives nil and prefixEncoding: [] gives an empty slice, so Render() writes it back out.
  • The low hash records whether prefixEncoding is present, not just its entries.
  • CompareEncoding / CompareMediaTypes report adding or removing an empty array as PropertyAdded / PropertyRemoved, under the existing prefixEncoding breaking rules.

Tests: TestEncoding_Hash_EmptyPrefixEncodingPresence, TestMediaType_OAS32Encoding_EmptyPrefixEncodingBuiltByCaller and TestCompareMediaTypes_EmptyPrefixEncodingPresence. Between them they cover an empty array against an omitted field, at both the media type and itemEncoding level.

}
extracted := make([]*Encoding, 0, len(prefix.Value))
for i := range prefix.Value {
extracted = append(extracted, NewEncoding(prefix.Value[i].Value))
}
return extracted
}
20 changes: 11 additions & 9 deletions datamodel/high/v3/media_type.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 1f5ea31. The low Encoding now reads extensions in Build and exposes FindExtension / GetExtensions. They're included in Hash(). The high Encoding has an Extensions map, so they render back out, and CompareEncoding reports them through ExtensionChanges.

Tests: TestEncoding_Build_Extensions, TestEncoding_Hash_Extensions, TestMediaType_OAS32Encoding_Extensions (extensions directly on an itemEncoding and on a prefixEncoding entry, checked through a round trip) and TestCompareMediaTypes_EncodingExtensions.

}
return m
}
Expand Down
Loading
Loading