chore: fix inconsistent handling of embedded maps and validation of 3.0 schemas to be forward compatible

TristanSpeakEasy · TristanSpeakEasy · commit 885ea5cd90d5 · 2025-10-03T12:45:09.000+10:00
diff --git a/extensions/extensions.go b/extensions/extensions.go
@@ -56,6 +56,15 @@ func (e *Extensions) Init() {
 	e.Map = sequencedmap.New[string, Extension]()
 }
 
+// Len returns the number of elements in the extensions map. nil safe.
+func (e *Extensions) Len() int {
+	if e == nil || e.Map == nil {
+		return 0
+	}
+
+	return e.Map.Len()
+}
+
 func (e *Extensions) SetCore(core any) {
 	c, ok := core.(*sequencedmap.Map[string, marshaller.Node[*yaml.Node]])
 	if !ok {
diff --git a/hashing/hashing_test.go b/hashing/hashing_test.go
@@ -134,7 +134,7 @@ func TestHash(t *testing.T) {
 		{
 			name: "model with embedded map",
 			v: &tests.TestEmbeddedMapWithFieldsHighModel{
-				Map: *sequencedmap.New(sequencedmap.NewElem("hello", &tests.TestPrimitiveHighModel{
+				Map: sequencedmap.New(sequencedmap.NewElem("hello", &tests.TestPrimitiveHighModel{
 					StringField: "world",
 				})),
 				NameField: "some name",
diff --git a/jsonpointer/map_index_key_test.go b/jsonpointer/map_index_key_test.go
@@ -184,7 +184,7 @@ func TestEmbeddedMapModel_Success(t *testing.T) {
 	embeddedMap.Set("data", "some data")
 
 	model := &tests.TestEmbeddedMapHighModel{
-		Map: *embeddedMap,
+		Map: embeddedMap,
 	}
 
 	tests := []struct {
diff --git a/jsonpointer/models_test.go b/jsonpointer/models_test.go
@@ -169,7 +169,7 @@ func TestNavigateModel_EmbeddedMap(t *testing.T) {
 		t.Parallel()
 		// Create a simple embedded map model
 		embeddedMap := &tests.TestEmbeddedMapHighModel{}
-		embeddedMap.Map = *sequencedmap.New[string, string]()
+		embeddedMap.Map = sequencedmap.New[string, string]()
 		embeddedMap.Set("key1", "value1")
 		embeddedMap.Set("key2", "value2")
 
@@ -199,7 +199,7 @@ func TestNavigateModel_EmbeddedMap(t *testing.T) {
 		embeddedMapWithFields := &tests.TestEmbeddedMapWithFieldsHighModel{
 			NameField: "test name",
 		}
-		embeddedMapWithFields.Map = *sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
+		embeddedMapWithFields.Map = sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
 		embeddedMapWithFields.Set("model1", nestedModel1)
 		embeddedMapWithFields.Set("model2", nestedModel2)
 
@@ -230,7 +230,7 @@ func TestNavigateModel_EmbeddedMap(t *testing.T) {
 	t.Run("EmbeddedMapNotFound", func(t *testing.T) {
 		t.Parallel()
 		embeddedMap := &tests.TestEmbeddedMapHighModel{}
-		embeddedMap.Map = *sequencedmap.New[string, string]()
+		embeddedMap.Map = sequencedmap.New[string, string]()
 		embeddedMap.Set("existing", "value")
 
 		// Test navigating to non-existent key in embedded map
@@ -248,7 +248,7 @@ func TestNavigateModel_EmbeddedMapEscapedKeys(t *testing.T) {
 		// Create a test that mimics OpenAPI paths structure
 		// This reproduces the issue with escaped JSON pointer paths like /paths/~1users~1{userId}
 		embeddedMap := &tests.TestEmbeddedMapHighModel{}
-		embeddedMap.Map = *sequencedmap.New[string, string]()
+		embeddedMap.Map = sequencedmap.New[string, string]()
 
 		// Set keys that contain special characters like OpenAPI paths
 		embeddedMap.Set("/users/{userId}", "path-item-1")
@@ -298,7 +298,7 @@ func TestNavigateModel_EmbeddedMapComparison_PointerVsValue(t *testing.T) {
 		t.Parallel()
 		// Create a model with value embedded map
 		model := &tests.TestEmbeddedMapHighModel{}
-		model.Map = *sequencedmap.New[string, string]()
+		model.Map = sequencedmap.New[string, string]()
 		model.Set("valKey1", "value value1")
 		model.Set("valKey2", "value value2")
 
@@ -320,7 +320,7 @@ func TestNavigateModel_EmbeddedMapComparison_PointerVsValue(t *testing.T) {
 		ptrModel.Set("sharedKey", "shared value")
 
 		valueModel := &tests.TestEmbeddedMapHighModel{}
-		valueModel.Map = *sequencedmap.New[string, string]()
+		valueModel.Map = sequencedmap.New[string, string]()
 		valueModel.Set("sharedKey", "shared value")
 
 		// Both should navigate to the same result
@@ -353,7 +353,7 @@ func TestNavigateModel_EmbeddedMapComparison_PointerVsValue(t *testing.T) {
 		valueModel := &tests.TestEmbeddedMapWithFieldsHighModel{
 			NameField: "value test name",
 		}
-		valueModel.Map = *sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
+		valueModel.Map = sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
 		valueModel.Set("nested", nestedModel)
 
 		// Test navigating to regular fields
diff --git a/jsonschema/oas3/schema30.json b/jsonschema/oas3/schema30.json
@@ -129,6 +129,9 @@
       "type": "string"
     },
     "default": {},
+    "const": {
+      "description": "Speakeasy addition to 3.0 schema to allow forward compatibility with OpenAPI 3.1"
+    },
     "nullable": {
       "type": "boolean",
       "default": false
diff --git a/marshaller/empty_map_marshal_test.go b/marshaller/empty_map_marshal_test.go
@@ -33,7 +33,7 @@ func TestMarshal_TestEmbeddedMapModel_Empty_Success(t *testing.T) {
 			name: "initialized empty embedded map should render as empty object",
 			setup: func() *tests.TestEmbeddedMapHighModel {
 				model := &tests.TestEmbeddedMapHighModel{}
-				model.Map = *sequencedmap.New[string, string]()
+				model.Map = sequencedmap.New[string, string]()
 				return model
 			},
 			expected: "{}\n",
@@ -42,7 +42,7 @@ func TestMarshal_TestEmbeddedMapModel_Empty_Success(t *testing.T) {
 			name: "embedded map with content should render normally",
 			setup: func() *tests.TestEmbeddedMapHighModel {
 				model := &tests.TestEmbeddedMapHighModel{}
-				model.Map = *sequencedmap.New[string, string]()
+				model.Map = sequencedmap.New[string, string]()
 				model.Set("key1", "value1")
 				return model
 			},
@@ -87,7 +87,7 @@ func TestMarshal_TestEmbeddedMapWithFieldsModel_Empty_Success(t *testing.T) {
 			name: "initialized empty embedded map with fields should render fields only",
 			setup: func() *tests.TestEmbeddedMapWithFieldsHighModel {
 				model := &tests.TestEmbeddedMapWithFieldsHighModel{}
-				model.Map = *sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
+				model.Map = sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
 				model.NameField = "test name"
 				return model
 			},
@@ -97,7 +97,7 @@ func TestMarshal_TestEmbeddedMapWithFieldsModel_Empty_Success(t *testing.T) {
 			name: "embedded map with content and fields should render both",
 			setup: func() *tests.TestEmbeddedMapWithFieldsHighModel {
 				model := &tests.TestEmbeddedMapWithFieldsHighModel{}
-				model.Map = *sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
+				model.Map = sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
 				model.NameField = "test name"
 				model.Set("key1", &tests.TestPrimitiveHighModel{
 					StringField: "value1",
diff --git a/marshaller/sequencedmap.go b/marshaller/sequencedmap.go
@@ -122,21 +122,24 @@ func populateSequencedMap(source any, target interfaces.SequencedMapInterface, p
 	var sm interfaces.SequencedMapInterface
 	var ok bool
 
-	// Handle both pointer and non-pointer cases
-	switch {
-	case sourceValue.Kind() == reflect.Ptr:
-		// Source is already a pointer
-		sm, ok = source.(interfaces.SequencedMapInterface)
-	case sourceValue.CanAddr():
-		// Source is addressable, get a pointer to it
+	// Handle pointer embeds: dereference until we get to the actual map
+	for sourceValue.Kind() == reflect.Ptr {
+		if sourceValue.IsNil() {
+			return nil
+		}
+		sourceValue = sourceValue.Elem()
+	}
+
+	// Now try to get the SequencedMapInterface
+	if sourceValue.CanAddr() {
 		sm, ok = sourceValue.Addr().Interface().(interfaces.SequencedMapInterface)
-	default:
-		// Source is neither a pointer nor addressable
-		return fmt.Errorf("expected source to be addressable or a pointer to SequencedMap, got %s", sourceValue.Type())
+	} else {
+		// Try direct interface conversion as fallback
+		sm, ok = sourceValue.Interface().(interfaces.SequencedMapInterface)
 	}
 
 	if !ok {
-		return fmt.Errorf("expected source to be SequencedMap, got %s", sourceValue.Type())
+		return fmt.Errorf("expected source to be SequencedMap, got %s", reflect.TypeOf(source))
 	}
 
 	target.Init()
diff --git a/marshaller/syncing_test.go b/marshaller/syncing_test.go
@@ -327,7 +327,7 @@ func TestSync_EmbeddedMapWithFields_Success(t *testing.T) {
 	}
 
 	// Initialize the embedded map
-	highModel.Map = *sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
+	highModel.Map = sequencedmap.New[string, *tests.TestPrimitiveHighModel]()
 	highModel.Set("syncKey1", dynamicVal1)
 	highModel.Set("syncKey2", dynamicVal2)
 
@@ -389,7 +389,7 @@ func TestSync_EmbeddedMap_Success(t *testing.T) {
 	highModel := tests.TestEmbeddedMapHighModel{}
 
 	// Initialize the embedded map
-	highModel.Map = *sequencedmap.New[string, string]()
+	highModel.Map = sequencedmap.New[string, string]()
 	highModel.Set("syncKey1", "synced value1")
 	highModel.Set("syncKey2", "synced value2")
 	highModel.Set("syncKey3", "synced value3")
@@ -704,7 +704,7 @@ func TestSync_TypeConversionModel_Success(t *testing.T) {
 	}
 
 	// Initialize the embedded map with HTTPMethod keys
-	highModel.Map = *sequencedmap.New[tests.HTTPMethod, *tests.TestPrimitiveHighModel]()
+	highModel.Map = sequencedmap.New[tests.HTTPMethod, *tests.TestPrimitiveHighModel]()
 	highModel.Set(tests.HTTPMethodPost, postOp)
 	highModel.Set(tests.HTTPMethodGet, getOp)
 	highModel.Set(tests.HTTPMethodPut, putOp)
@@ -1097,7 +1097,7 @@ func TestSync_EmbeddedMapComparison_PointerVsValue_Success(t *testing.T) {
 		t.Parallel()
 		// Test value embedded map
 		valueModel := tests.TestEmbeddedMapHighModel{}
-		valueModel.Map = *sequencedmap.New[string, string]()
+		valueModel.Map = sequencedmap.New[string, string]()
 		valueModel.Set("key1", "val_value1")
 		valueModel.Set("key2", "val_value2")
 
@@ -1122,7 +1122,7 @@ func TestSync_EmbeddedMapComparison_PointerVsValue_Success(t *testing.T) {
 		ptrModel.Set("shared_key", "shared_value")
 
 		valueModel := tests.TestEmbeddedMapHighModel{}
-		valueModel.Map = *sequencedmap.New[string, string]()
+		valueModel.Map = sequencedmap.New[string, string]()
 		valueModel.Set("shared_key", "shared_value")
 
 		// Sync both models
diff --git a/marshaller/tests/core/models.go b/marshaller/tests/core/models.go
@@ -59,13 +59,13 @@ type TestComplexModel struct {
 type TestEmbeddedMapModel struct {
 	marshaller.CoreModel `model:"testEmbeddedMapModel"`
 
-	sequencedmap.Map[string, marshaller.Node[string]]
+	*sequencedmap.Map[string, marshaller.Node[string]]
 }
 
 // TestEmbeddedMapWithFieldsModel covers embedded sequenced map with additional fields
 type TestEmbeddedMapWithFieldsModel struct {
 	marshaller.CoreModel `model:"testEmbeddedMapWithFieldsModel"`
-	sequencedmap.Map[string, marshaller.Node[*TestPrimitiveModel]]
+	*sequencedmap.Map[string, marshaller.Node[*TestPrimitiveModel]]
 
 	NameField  marshaller.Node[string] `key:"name"`
 	Extensions core.Extensions         `key:"extensions"`
@@ -74,7 +74,7 @@ type TestEmbeddedMapWithFieldsModel struct {
 // TestEmbeddedMapWithExtensionsModel covers embedded sequenced map with extensions only
 type TestEmbeddedMapWithExtensionsModel struct {
 	marshaller.CoreModel `model:"testEmbeddedMapWithExtensionsModel"`
-	sequencedmap.Map[string, marshaller.Node[string]]
+	*sequencedmap.Map[string, marshaller.Node[string]]
 
 	Extensions core.Extensions `key:"extensions"`
 }
@@ -179,7 +179,7 @@ type TestRequiredNilableModel struct {
 type TestTypeConversionCoreModel struct {
 	marshaller.CoreModel `model:"testTypeConversionCoreModel"`
 
-	sequencedmap.Map[string, marshaller.Node[*TestPrimitiveModel]]
+	*sequencedmap.Map[string, marshaller.Node[*TestPrimitiveModel]]
 	HTTPMethodField marshaller.Node[*string] `key:"httpMethodField"`
 	Extensions      core.Extensions          `key:"extensions"`
 }
diff --git a/marshaller/tests/models.go b/marshaller/tests/models.go
@@ -44,12 +44,12 @@ type TestComplexHighModel struct {
 
 type TestEmbeddedMapHighModel struct {
 	marshaller.Model[core.TestEmbeddedMapModel]
-	sequencedmap.Map[string, string]
+	*sequencedmap.Map[string, string]
 }
 
 type TestEmbeddedMapWithFieldsHighModel struct {
 	marshaller.Model[core.TestEmbeddedMapWithFieldsModel]
-	sequencedmap.Map[string, *TestPrimitiveHighModel]
+	*sequencedmap.Map[string, *TestPrimitiveHighModel]
 	NameField  string
 	Extensions *extensions.Extensions
 }
@@ -108,7 +108,7 @@ const (
 // This reproduces the issue where high-level model expects HTTPMethod keys but core provides string keys
 type TestTypeConversionHighModel struct {
 	marshaller.Model[core.TestTypeConversionCoreModel]
-	sequencedmap.Map[HTTPMethod, *TestPrimitiveHighModel]
+	*sequencedmap.Map[HTTPMethod, *TestPrimitiveHighModel]
 	HTTPMethodField *HTTPMethod
 	Extensions      *extensions.Extensions
 }
diff --git a/openapi/callbacks.go b/openapi/callbacks.go
@@ -17,7 +17,7 @@ import (
 // Callback embeds sequencedmap.Map[string, *ReferencedPathItem] so all map operations are supported.
 type Callback struct {
 	marshaller.Model[core.Callback]
-	sequencedmap.Map[expression.Expression, *ReferencedPathItem]
+	*sequencedmap.Map[expression.Expression, *ReferencedPathItem]
 
 	// Extensions provides a list of extensions to the Callback object.
 	Extensions *extensions.Extensions
@@ -28,10 +28,18 @@ var _ interfaces.Model[core.Callback] = (*Callback)(nil)
 // NewCallback creates a new Callback object with the embedded map initialized.
 func NewCallback() *Callback {
 	return &Callback{
-		Map: *sequencedmap.New[expression.Expression, *ReferencedPathItem](),
+		Map: sequencedmap.New[expression.Expression, *ReferencedPathItem](),
 	}
 }
 
+// Len returns the number of elements in the callback map. nil safe.
+func (c *Callback) Len() int {
+	if c == nil || c.Map == nil {
+		return 0
+	}
+	return c.Map.Len()
+}
+
 // GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.
 func (c *Callback) GetExtensions() *extensions.Extensions {
 	if c == nil || c.Extensions == nil {
diff --git a/openapi/core/paths.go b/openapi/core/paths.go
@@ -8,20 +8,20 @@ import (
 
 type Paths struct {
 	marshaller.CoreModel `model:"paths"`
-	sequencedmap.Map[string, *Reference[*PathItem]]
+	*sequencedmap.Map[string, *Reference[*PathItem]]
 
 	Extensions core.Extensions `key:"extensions"`
 }
 
 func NewPaths() *Paths {
 	return &Paths{
-		Map: *sequencedmap.New[string, *Reference[*PathItem]](),
+		Map: sequencedmap.New[string, *Reference[*PathItem]](),
 	}
 }
 
 type PathItem struct {
 	marshaller.CoreModel `model:"pathItem"`
-	sequencedmap.Map[string, *Operation]
+	*sequencedmap.Map[string, *Operation]
 
 	Summary     marshaller.Node[*string] `key:"summary"`
 	Description marshaller.Node[*string] `key:"description"`
@@ -34,6 +34,6 @@ type PathItem struct {
 
 func NewPathItem() *PathItem {
 	return &PathItem{
-		Map: *sequencedmap.New[string, *Operation](),
+		Map: sequencedmap.New[string, *Operation](),
 	}
 }
diff --git a/openapi/paths.go b/openapi/paths.go
@@ -16,7 +16,7 @@ import (
 // Paths embeds sequencedmap.Map[string, *ReferencedPathItem] so all map operations are supported.
 type Paths struct {
 	marshaller.Model[core.Paths]
-	sequencedmap.Map[string, *ReferencedPathItem]
+	*sequencedmap.Map[string, *ReferencedPathItem]
 
 	// Extensions provides a list of extensions to the Paths object.
 	Extensions *extensions.Extensions
@@ -27,10 +27,18 @@ var _ interfaces.Model[core.Paths] = (*Paths)(nil)
 // NewPaths creates a new Paths object with the embedded map initialized.
 func NewPaths() *Paths {
 	return &Paths{
-		Map: *sequencedmap.New[string, *ReferencedPathItem](),
+		Map: sequencedmap.New[string, *ReferencedPathItem](),
 	}
 }
 
+// Len returns the number of elements in the paths map. nil safe.
+func (p *Paths) Len() int {
+	if p == nil || p.Map == nil {
+		return 0
+	}
+	return p.Map.Len()
+}
+
 // GetExtensions returns the value of the Extensions field. Returns an empty extensions map if not set.
 func (p *Paths) GetExtensions() *extensions.Extensions {
 	if p == nil || p.Extensions == nil {
@@ -82,7 +90,7 @@ func (m HTTPMethod) Is(method string) bool {
 // PathItem embeds sequencedmap.Map[HTTPMethod, *Operation] so all map operations are supported for working with HTTP methods.
 type PathItem struct {
 	marshaller.Model[core.PathItem]
-	sequencedmap.Map[HTTPMethod, *Operation]
+	*sequencedmap.Map[HTTPMethod, *Operation]
 
 	// Summary is a short summary of the path and its operations.
 	Summary *string
@@ -103,8 +111,16 @@ var _ interfaces.Model[core.PathItem] = (*PathItem)(nil)
 // NewPathItem creates a new PathItem object with the embedded map initialized.
 func NewPathItem() *PathItem {
 	return &PathItem{
-		Map: *sequencedmap.New[HTTPMethod, *Operation](),
+		Map: sequencedmap.New[HTTPMethod, *Operation](),
+	}
+}
+
+// Len returns the number of operations in the path item. nil safe.
+func (p *PathItem) Len() int {
+	if p == nil || p.Map == nil {
+		return 0
 	}
+	return p.Map.Len()
 }
 
 // GetOperation returns the operation for the specified HTTP method.
diff --git a/openapi/responses.go b/openapi/responses.go
diff --git a/references/resolution.go b/references/resolution.go
diff --git a/walk/set_test.go b/walk/set_test.go

Original file line number	Diff line number	Diff line change
`@@ -134,7 +134,7 @@ func TestHash(t *testing.T) {`
`134`	`134`	`{`
`135`	`135`	`name: "model with embedded map",`
`136`	`136`	`v: &tests.TestEmbeddedMapWithFieldsHighModel{`
`137`		`- Map: *sequencedmap.New(sequencedmap.NewElem("hello", &tests.TestPrimitiveHighModel{`
	`137`	`+ Map: sequencedmap.New(sequencedmap.NewElem("hello", &tests.TestPrimitiveHighModel{`
`138`	`138`	`StringField: "world",`
`139`	`139`	`})),`
`140`	`140`	`NameField: "some name",`
Original file line number	Diff line number	Diff line change
`@@ -184,7 +184,7 @@ func TestEmbeddedMapModel_Success(t *testing.T) {`
`184`	`184`	`embeddedMap.Set("data", "some data")`
`185`	`185`
`186`	`186`	`model := &tests.TestEmbeddedMapHighModel{`
`187`		`- Map: *embeddedMap,`
	`187`	`+ Map: embeddedMap,`
`188`	`188`	`}`
`189`	`189`
`190`	`190`	`tests := []struct {`