openapi: update JSON Schema to draft 2020-12 (goadesign#3838)

Update JSON Schema from draft-04 to draft 2020-12:
- Change 'definitions' to '$defs' (draft 2020-12 format)
- Update schema reference to draft 2020-12 meta-schema
- Update all reference paths from #/definitions/ to #/$defs/
- Add conversion functions in v2/builder.go to convert references
  back to Swagger 2.0 format (#/definitions/) for backward compatibility

Author: raphael

http/codegen/openapi/json_schema.go

@@ -20,7 +20,7 @@ type (
 		Type         Type               `json:"type,omitempty" yaml:"type,omitempty"`
 		Items        *Schema            `json:"items,omitempty" yaml:"items,omitempty"`
 		Properties   map[string]*Schema `json:"properties,omitempty" yaml:"properties,omitempty"`
-		Definitions  map[string]*Schema `json:"definitions,omitempty" yaml:"definitions,omitempty"`
+		Defs         map[string]*Schema `json:"$defs,omitempty" yaml:"$defs,omitempty"`
 		Description  string             `json:"description,omitempty" yaml:"description,omitempty"`
 		DefaultValue any                `json:"default,omitempty" yaml:"default,omitempty"`
 		Example      any                `json:"example,omitempty" yaml:"example,omitempty"`
@@ -99,8 +99,8 @@ const (
 	File = "file"
 )
 
-// SchemaRef is the JSON Hyper-schema standard href.
-const SchemaRef = "http://json-schema.org/draft-04/hyper-schema"
+// SchemaRef is the JSON Schema draft 2020-12 meta-schema identifier.
+const SchemaRef = "https://json-schema.org/draft/2020-12/schema"
 
 var (
 	// Definitions contains the generated JSON schema definitions
@@ -115,8 +115,8 @@ func init() {
 // NewSchema instantiates a new JSON schema.
 func NewSchema() *Schema {
 	js := Schema{
-		Properties:  make(map[string]*Schema),
-		Definitions: make(map[string]*Schema),
+		Properties: make(map[string]*Schema),
+		Defs:       make(map[string]*Schema),
 	}
 	return &js
 }
@@ -156,8 +156,8 @@ func APISchema(api *expr.APIExpr, r *expr.RootExpr) *Schema {
 		Title:       api.Title,
 		Description: api.Description,
 		Type:        Object,
-		Definitions: Definitions,
-		Properties:  propertiesFromDefs(Definitions, "#/definitions/"),
+		Defs:        Definitions,
+		Properties:  propertiesFromDefs(Definitions, "#/$defs/"),
 		Links:       links,
 	}
 	return &s
@@ -250,7 +250,7 @@ func ResultTypeRefWithPrefix(api *expr.APIExpr, mt *expr.ResultTypeExpr, view, p
 		}
 		GenerateResultTypeDefinition(api, projected, expr.DefaultView)
 	}
-	return fmt.Sprintf("#/definitions/%s", projected.TypeName)
+	return fmt.Sprintf("#/$defs/%s", projected.TypeName)
 }
 
 // TypeRef produces the JSON reference to the type definition.
@@ -271,7 +271,7 @@ func TypeRefWithPrefix(api *expr.APIExpr, ut *expr.UserTypeExpr, prefix string)
 	if _, ok := Definitions[typeName]; !ok {
 		GenerateTypeDefinitionWithName(api, ut, typeName)
 	}
-	return fmt.Sprintf("#/definitions/%s", typeName)
+	return fmt.Sprintf("#/$defs/%s", typeName)
 }
 
 // GenerateResultTypeDefinition produces the JSON schema corresponding to the
@@ -469,8 +469,8 @@ func (s *Schema) Dup() *Schema {
 	if s.Items != nil {
 		js.Items = s.Items.Dup()
 	}
-	for n, d := range s.Definitions {
-		js.Definitions[n] = d.Dup()
+	for n, d := range s.Defs {
+		js.Defs[n] = d.Dup()
 	}
 	return &js
 }

http/codegen/openapi/merge.go

@@ -26,9 +26,9 @@ func (s *Schema) Merge(other *Schema) {
 		}
 	}
 
-	for n, d := range other.Definitions {
-		if _, ok := s.Definitions[n]; !ok {
-			s.Definitions[n] = d
+	for n, d := range other.Defs {
+		if _, ok := s.Defs[n]; !ok {
+			s.Defs[n] = d
 		}
 	}
 

http/codegen/openapi/v2/builder.go

@@ -93,6 +93,8 @@ func NewV2(root *expr.RootExpr, h *expr.HostExpr) (*V2, error) {
 			s.Definitions[n] = d
 		}
 	}
+	// Convert OpenAPI 3.0 references (#/$defs/) to Swagger 2.0 format (#/definitions/)
+	convertRefsToV2(s)
 	return s, nil
 }
 
@@ -814,3 +816,78 @@ func initValidations(attr *expr.AttributeExpr, def any) {
 		initMaxLengthValidation(def, expr.IsArray(attr.Type), val.MaxLength)
 	}
 }
+
+// convertRefsToV2 converts all OpenAPI 3.0 references (#/$defs/) to Swagger 2.0
+// format (#/definitions/) in all schemas throughout the V2 specification.
+func convertRefsToV2(s *V2) {
+	// Convert references in definitions
+	for _, def := range s.Definitions {
+		convertSchemaRefs(def)
+	}
+	// Convert references in paths
+	for _, pathVal := range s.Paths {
+		if path, ok := pathVal.(*Path); ok {
+			convertPathRefs(path)
+		}
+	}
+	// Convert references in parameters
+	for _, param := range s.Parameters {
+		if param.Schema != nil {
+			convertSchemaRefs(param.Schema)
+		}
+	}
+}
+
+// convertPathRefs converts references in all operations of a path.
+func convertPathRefs(path *Path) {
+	ops := []*Operation{path.Get, path.Put, path.Post, path.Delete, path.Options, path.Head, path.Patch}
+	for _, op := range ops {
+		if op == nil {
+			continue
+		}
+		// Convert references in parameters
+		for _, param := range op.Parameters {
+			if param.Schema != nil {
+				convertSchemaRefs(param.Schema)
+			}
+		}
+		// Convert references in responses
+		for _, resp := range op.Responses {
+			if resp.Schema != nil {
+				convertSchemaRefs(resp.Schema)
+			}
+		}
+	}
+}
+
+// convertSchemaRefs recursively converts all #/$defs/ references to #/definitions/
+// in a schema and all nested schemas.
+func convertSchemaRefs(schema *openapi.Schema) {
+	if schema == nil {
+		return
+	}
+	// Convert the reference itself
+	if strings.HasPrefix(schema.Ref, "#/$defs/") {
+		schema.Ref = strings.Replace(schema.Ref, "#/$defs/", "#/definitions/", 1)
+	}
+	// Convert references in items
+	if schema.Items != nil {
+		convertSchemaRefs(schema.Items)
+	}
+	// Convert references in properties
+	for _, prop := range schema.Properties {
+		convertSchemaRefs(prop)
+	}
+	// Convert references in anyOf
+	for _, anyOfSchema := range schema.AnyOf {
+		convertSchemaRefs(anyOfSchema)
+	}
+	// Convert references in additionalProperties when it's a schema
+	if apSchema, ok := schema.AdditionalProperties.(*openapi.Schema); ok {
+		convertSchemaRefs(apSchema)
+	}
+	// Convert references in $defs (though these shouldn't exist in Swagger 2.0)
+	for _, def := range schema.Defs {
+		convertSchemaRefs(def)
+	}
+}