fix: support boolean form for unevaluatedProperties and unevaluatedItems

JSON Schema 2020-12 allows unevaluatedProperties and unevaluatedItems
to be either a boolean or a schema object (e.g. `unevaluatedProperties: false`).
The fields were typed as *SchemaRef, which caused an unmarshal error
when encountering the boolean form.

Introduce BoolSchema, a type that handles both boolean and schema forms
(same pattern as AdditionalProperties), and use it for all three fields.
AdditionalProperties becomes a type alias for BoolSchema so existing
code continues to compile unchanged.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: reuvenharrison

openapi3/loader.go

@@ -1058,12 +1058,12 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat
 			return err
 		}
 	}
-	if v := value.UnevaluatedItems; v != nil {
+	if v := value.UnevaluatedItems.Schema; v != nil {
 		if err := loader.resolveSchemaRef(doc, v, documentPath, visited); err != nil {
 			return err
 		}
 	}
-	if v := value.UnevaluatedProperties; v != nil {
+	if v := value.UnevaluatedProperties.Schema; v != nil {
 		if err := loader.resolveSchemaRef(doc, v, documentPath, visited); err != nil {
 			return err
 		}

openapi3/loader_31_schema_refs_test.go

@@ -88,14 +88,16 @@ func TestResolveSchemaRefsIn31Fields(t *testing.T) {
 	// unevaluatedItems ref should be resolved
 	unItems := schemas["ArrayWithUnevaluatedItems"].Value
 	require.NotNil(t, unItems)
-	require.Equal(t, "#/components/schemas/StringType", unItems.UnevaluatedItems.Ref)
-	require.NotNil(t, unItems.UnevaluatedItems.Value, "unevaluatedItems $ref should be resolved")
+	require.NotNil(t, unItems.UnevaluatedItems.Schema)
+	require.Equal(t, "#/components/schemas/StringType", unItems.UnevaluatedItems.Schema.Ref)
+	require.NotNil(t, unItems.UnevaluatedItems.Schema.Value, "unevaluatedItems $ref should be resolved")
 
 	// unevaluatedProperties ref should be resolved
 	unProps := schemas["ObjectWithUnevaluatedProperties"].Value
 	require.NotNil(t, unProps)
-	require.Equal(t, "#/components/schemas/StringType", unProps.UnevaluatedProperties.Ref)
-	require.NotNil(t, unProps.UnevaluatedProperties.Value, "unevaluatedProperties $ref should be resolved")
+	require.NotNil(t, unProps.UnevaluatedProperties.Schema)
+	require.Equal(t, "#/components/schemas/StringType", unProps.UnevaluatedProperties.Schema.Ref)
+	require.NotNil(t, unProps.UnevaluatedProperties.Schema.Value, "unevaluatedProperties $ref should be resolved")
 
 	// if/then/else refs should be resolved
 	ifThenElse := schemas["ObjectWithIfThenElse"].Value

openapi3/origin.go

@@ -179,7 +179,7 @@ func applyOriginsToStruct(val reflect.Value, ptr reflect.Value, tree *yaml.Origi
 
 	// Handle wrapper types whose inner struct has no json tag:
 	// - *Ref types (e.g. SchemaRef, ResponseRef) have a "Value" field
-	// - AdditionalProperties has a "Schema" field
+	// - BoolSchema (AdditionalProperties, UnevaluatedProperties, UnevaluatedItems) has a "Schema" field
 	// The origin tree data applies to the inner struct, not a sub-key.
 	for _, fieldName := range []string{"Value", "Schema"} {
 		vf := val.FieldByName(fieldName)

openapi3/schema.go

@@ -145,8 +145,8 @@ type Schema struct {
 	PatternProperties     Schemas    `json:"patternProperties,omitempty" yaml:"patternProperties,omitempty"`
 	DependentSchemas      Schemas    `json:"dependentSchemas,omitempty" yaml:"dependentSchemas,omitempty"`
 	PropertyNames         *SchemaRef `json:"propertyNames,omitempty" yaml:"propertyNames,omitempty"`
-	UnevaluatedItems      *SchemaRef `json:"unevaluatedItems,omitempty" yaml:"unevaluatedItems,omitempty"`
-	UnevaluatedProperties *SchemaRef `json:"unevaluatedProperties,omitempty" yaml:"unevaluatedProperties,omitempty"`
+	UnevaluatedItems      BoolSchema `json:"unevaluatedItems,omitempty" yaml:"unevaluatedItems,omitempty"`
+	UnevaluatedProperties BoolSchema `json:"unevaluatedProperties,omitempty" yaml:"unevaluatedProperties,omitempty"`
 
 	// JSON Schema 2020-12 conditional keywords
 	If   *SchemaRef `json:"if,omitempty" yaml:"if,omitempty"`
@@ -357,56 +357,61 @@ func (types *Types) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
-type AdditionalProperties struct {
+// BoolSchema represents a JSON Schema keyword that can be either a boolean or a schema object.
+// Used for additionalProperties, unevaluatedProperties, and unevaluatedItems.
+type BoolSchema struct {
 	Has    *bool
 	Schema *SchemaRef
 }
 
-// MarshalYAML returns the YAML encoding of AdditionalProperties.
-func (addProps AdditionalProperties) MarshalYAML() (any, error) {
-	if x := addProps.Has; x != nil {
+// AdditionalProperties is a type alias for BoolSchema, kept for backward compatibility.
+type AdditionalProperties = BoolSchema
+
+// MarshalYAML returns the YAML encoding of BoolSchema.
+func (bs BoolSchema) MarshalYAML() (any, error) {
+	if x := bs.Has; x != nil {
 		if *x {
 			return true, nil
 		}
 		return false, nil
 	}
-	if x := addProps.Schema; x != nil {
+	if x := bs.Schema; x != nil {
 		return x.MarshalYAML()
 	}
 	return nil, nil
 }
 
-// MarshalJSON returns the JSON encoding of AdditionalProperties.
-func (addProps AdditionalProperties) MarshalJSON() ([]byte, error) {
-	x, err := addProps.MarshalYAML()
+// MarshalJSON returns the JSON encoding of BoolSchema.
+func (bs BoolSchema) MarshalJSON() ([]byte, error) {
+	x, err := bs.MarshalYAML()
 	if err != nil {
 		return nil, err
 	}
 	return json.Marshal(x)
 }
 
-// UnmarshalJSON sets AdditionalProperties to a copy of data.
-func (addProps *AdditionalProperties) UnmarshalJSON(data []byte) error {
+// UnmarshalJSON sets BoolSchema to a copy of data.
+func (bs *BoolSchema) UnmarshalJSON(data []byte) error {
 	var x any
 	if err := json.Unmarshal(data, &x); err != nil {
 		return unmarshalError(err)
 	}
 	switch y := x.(type) {
 	case nil:
 	case bool:
-		addProps.Has = &y
+		bs.Has = &y
 	case map[string]any:
 		if len(y) == 0 {
-			addProps.Schema = &SchemaRef{Value: &Schema{}}
+			bs.Schema = &SchemaRef{Value: &Schema{}}
 		} else {
 			buf := new(bytes.Buffer)
 			_ = json.NewEncoder(buf).Encode(y)
-			if err := json.NewDecoder(buf).Decode(&addProps.Schema); err != nil {
+			if err := json.NewDecoder(buf).Decode(&bs.Schema); err != nil {
 				return err
 			}
 		}
 	default:
-		return errors.New("cannot unmarshal additionalProperties: value must be either a schema object or a boolean")
+		return errors.New("cannot unmarshal: value must be either a schema object or a boolean")
 	}
 	return nil
 }
@@ -647,11 +652,11 @@ func (schema Schema) MarshalYAML() (any, error) {
 	if x := schema.PropertyNames; x != nil {
 		m["propertyNames"] = x
 	}
-	if x := schema.UnevaluatedItems; x != nil {
-		m["unevaluatedItems"] = x
+	if x := schema.UnevaluatedItems; x.Has != nil || x.Schema != nil {
+		m["unevaluatedItems"] = &x
 	}
-	if x := schema.UnevaluatedProperties; x != nil {
-		m["unevaluatedProperties"] = x
+	if x := schema.UnevaluatedProperties; x.Has != nil || x.Schema != nil {
+		m["unevaluatedProperties"] = &x
 	}
 	if x := schema.If; x != nil {
 		m["if"] = x
@@ -923,18 +928,24 @@ func (schema Schema) JSONLookup(token string) (any, error) {
 			return schema.PropertyNames.Value, nil
 		}
 	case "unevaluatedItems":
-		if schema.UnevaluatedItems != nil {
-			if schema.UnevaluatedItems.Ref != "" {
-				return &Ref{Ref: schema.UnevaluatedItems.Ref}, nil
+		if ui := schema.UnevaluatedItems.Has; ui != nil {
+			return *ui, nil
+		}
+		if ui := schema.UnevaluatedItems.Schema; ui != nil {
+			if ui.Ref != "" {
+				return &Ref{Ref: ui.Ref}, nil
 			}
-			return schema.UnevaluatedItems.Value, nil
+			return ui.Value, nil
 		}
 	case "unevaluatedProperties":
-		if schema.UnevaluatedProperties != nil {
-			if schema.UnevaluatedProperties.Ref != "" {
-				return &Ref{Ref: schema.UnevaluatedProperties.Ref}, nil
+		if up := schema.UnevaluatedProperties.Has; up != nil {
+			return *up, nil
+		}
+		if up := schema.UnevaluatedProperties.Schema; up != nil {
+			if up.Ref != "" {
+				return &Ref{Ref: up.Ref}, nil
 			}
-			return schema.UnevaluatedProperties.Value, nil
+			return up.Value, nil
 		}
 	case "if":
 		if schema.If != nil {
@@ -1340,10 +1351,16 @@ func (schema *Schema) IsEmpty() bool {
 	if pn := schema.PropertyNames; pn != nil && pn.Value != nil && !pn.Value.IsEmpty() {
 		return false
 	}
-	if ui := schema.UnevaluatedItems; ui != nil && ui.Value != nil && !ui.Value.IsEmpty() {
+	if ui := schema.UnevaluatedItems.Schema; ui != nil && ui.Value != nil && !ui.Value.IsEmpty() {
+		return false
+	}
+	if uih := schema.UnevaluatedItems.Has; uih != nil && !*uih {
 		return false
 	}
-	if up := schema.UnevaluatedProperties; up != nil && up.Value != nil && !up.Value.IsEmpty() {
+	if up := schema.UnevaluatedProperties.Schema; up != nil && up.Value != nil && !up.Value.IsEmpty() {
+		return false
+	}
+	if uph := schema.UnevaluatedProperties.Has; uph != nil && !*uph {
 		return false
 	}
 	if len(schema.Examples) != 0 {
@@ -1676,7 +1693,10 @@ func (schema *Schema) validate(ctx context.Context, stack []*Schema) ([]*Schema,
 			return stack, err
 		}
 	}
-	if ref := schema.UnevaluatedItems; ref != nil {
+	if schema.UnevaluatedItems.Has != nil && schema.UnevaluatedItems.Schema != nil {
+		return stack, errors.New("unevaluatedItems is set to both boolean and schema")
+	}
+	if ref := schema.UnevaluatedItems.Schema; ref != nil {
 		v := ref.Value
 		if v == nil {
 			return stack, foundUnresolvedRef(ref.Ref)
@@ -1687,7 +1707,10 @@ func (schema *Schema) validate(ctx context.Context, stack []*Schema) ([]*Schema,
 			return stack, err
 		}
 	}
-	if ref := schema.UnevaluatedProperties; ref != nil {
+	if schema.UnevaluatedProperties.Has != nil && schema.UnevaluatedProperties.Schema != nil {
+		return stack, errors.New("unevaluatedProperties is set to both boolean and schema")
+	}
+	if ref := schema.UnevaluatedProperties.Schema; ref != nil {
 		v := ref.Value
 		if v == nil {
 			return stack, foundUnresolvedRef(ref.Ref)

openapi3/schema_jsonschema_validator_test.go

@@ -344,10 +344,10 @@ func TestJSONSchema2020Validator_TransformRecursesInto31Fields(t *testing.T) {
 			PrefixItems: SchemaRefs{
 				&SchemaRef{Value: &Schema{Type: &Types{"integer"}}},
 			},
-			UnevaluatedItems: &SchemaRef{Value: &Schema{
+			UnevaluatedItems: BoolSchema{Schema: &SchemaRef{Value: &Schema{
 				Type:     &Types{"string"},
 				Nullable: true,
-			}},
+			}}},
 		}
 
 		err := schema.VisitJSON([]any{1, nil}, EnableJSONSchema2020())
@@ -360,10 +360,10 @@ func TestJSONSchema2020Validator_TransformRecursesInto31Fields(t *testing.T) {
 			Properties: Schemas{
 				"name": &SchemaRef{Value: &Schema{Type: &Types{"string"}}},
 			},
-			UnevaluatedProperties: &SchemaRef{Value: &Schema{
+			UnevaluatedProperties: BoolSchema{Schema: &SchemaRef{Value: &Schema{
 				Type:     &Types{"string"},
 				Nullable: true,
-			}},
+			}}},
 		}
 
 		err := schema.VisitJSON(map[string]any{"name": "foo", "extra": nil}, EnableJSONSchema2020())

openapi3/schema_validate_31_test.go

@@ -70,7 +70,7 @@ func TestSchemaValidate31SubSchemas(t *testing.T) {
 	t.Run("unevaluatedItems with invalid sub-schema", func(t *testing.T) {
 		schema := &Schema{
 			Type:             &Types{"array"},
-			UnevaluatedItems: &SchemaRef{Value: invalidSchema},
+			UnevaluatedItems: BoolSchema{Schema: &SchemaRef{Value: invalidSchema}},
 		}
 		err := schema.Validate(ctx)
 		require.Error(t, err, "should detect invalid sub-schema in unevaluatedItems")
@@ -79,7 +79,7 @@ func TestSchemaValidate31SubSchemas(t *testing.T) {
 	t.Run("unevaluatedProperties with invalid sub-schema", func(t *testing.T) {
 		schema := &Schema{
 			Type:                  &Types{"object"},
-			UnevaluatedProperties: &SchemaRef{Value: invalidSchema},
+			UnevaluatedProperties: BoolSchema{Schema: &SchemaRef{Value: invalidSchema}},
 		}
 		err := schema.Validate(ctx)
 		require.Error(t, err, "should detect invalid sub-schema in unevaluatedProperties")
@@ -104,7 +104,7 @@ func TestSchemaValidate31SubSchemas(t *testing.T) {
 				{Value: validSubSchema},
 			},
 			Contains:         &SchemaRef{Value: validSubSchema},
-			UnevaluatedItems: &SchemaRef{Value: validSubSchema},
+			UnevaluatedItems: BoolSchema{Schema: &SchemaRef{Value: validSubSchema}},
 		}
 		err := schema.Validate(ctx)
 		require.NoError(t, err, "valid sub-schemas should pass validation")