Fix issue with self-recursive traits and add validation (#78)

* docs: Remove incomplete comment in jsonschemaconv.go

* fix: Fix self-recursive traits resolution and traits validation

Author: yury-palyanitsa

.gitignore

@@ -6,3 +6,4 @@ cover.html
 cover.out
 .build
 /.idea
+test_output/

fixtures/library_invalid_recursive_trait.raml

@@ -0,0 +1,10 @@
+#%RAML 1.0 Library
+
+types:
+  SelfRecursiveTrait:
+    type: object
+    facets:
+      my_trait:
+        type: SelfRecursiveTrait
+    properties:
+      attr1: string

fixtures/library_invalid_trait_example.raml

@@ -0,0 +1,9 @@
+#%RAML 1.0 Library
+
+types:
+  Trait:
+    type: object
+    facets:
+      my_trait:
+        type: string
+        example: 1

fixtures/library_recursive_trait.raml

@@ -0,0 +1,26 @@
+#%RAML 1.0 Library
+
+types:
+  SelfRecursiveTraitAlias:
+    type: object
+    facets:
+      my_trait: SelfRecursiveTraitAlias
+    properties:
+      attr1: string
+
+  SelfRecursiveTraitNestedAlias:
+    type: object
+    facets:
+      test_trait:
+        properties:
+          my_trait: SelfRecursiveTraitNestedAlias
+    properties:
+      attr1: string
+
+  SelfRecursiveTraitInheritedOptional:
+    type: object
+    facets:
+      my_trait?:
+        type: SelfRecursiveTraitInheritedOptional
+    properties:
+      attr1: string

jsonschemaconv.go

@@ -337,7 +337,7 @@ func (c *JSONSchemaConverter[T]) VisitRecursiveShape(s *RecursiveShape) T {
 	// Ref ignores all other keywords defined within the schema per JSON Schema spec.
 
 	// NOTE: We create empty schema because all base RAML types are allowed to have
-	// custom facets which can be recursive. RAML-JSON Schema wrapper
+	// custom facets which can be recursive.
 	// The use of `makeSchemaFromBaseShape` will lead to infinite recursion.
 	node := c.makeEmptySchema()
 	schema := node.Generic()

parse_test.go

@@ -3,6 +3,7 @@ package raml
 import (
 	"container/list"
 	"context"
+	"encoding/json"
 	"errors"
 	"io"
 	"os"
@@ -14,12 +15,38 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+func writeToDiskHelper(t *testing.T, tt struct {
+	name string
+	typeName string
+	outSchema *JSONSchemaRAML
+}) {
+	outputDir := "./test_output"
+	if err := os.MkdirAll(outputDir, os.ModePerm); err != nil {
+		t.Errorf("Failed to create output directory: %v", err)
+	}
+	outputPath := filepath.Join(outputDir, tt.name+"_"+tt.typeName+".json")
+	var jsonData []byte
+	jsonData, err := json.MarshalIndent(tt.outSchema, "", "  ")
+	if err != nil {
+		t.Errorf("Failed to marshal JSON Schema: %v", err)
+	}
+	if err := os.WriteFile(outputPath, jsonData, 0644); err != nil {
+		t.Errorf("Failed to write JSON Schema to file: %v", err)
+	}
+	t.Logf("Successfully wrote JSON Schema to %s", outputPath)
+}
+
+
 func Test_ParseFixturesIntegration(t *testing.T) {
 	// Define test cases for valid fixtures that should parse successfully
 	validTests := []struct {
 		name string
 		path string
 	}{
+		{
+			name: "library_recursive_trait.raml",
+			path: "./fixtures/library_recursive_trait.raml",
+		},
 		{
 			name: "library.raml",
 			path: "./fixtures/library.raml",
@@ -78,19 +105,25 @@ func Test_ParseFixturesIntegration(t *testing.T) {
 				case *Library:
 					for pair := f.AnnotationTypes.Oldest(); pair != nil; pair = pair.Next() {
 						s := pair.Value
-						_, errConv := conv.Convert(s.Shape)
-						require.NoError(t, errConv, "Failed to convert annotation type shape in %s: %v", tt.path, errConv)
+						typeName := pair.Key
+						outSchema, err := conv.Convert(s.Shape)
+						writeToDiskHelper(t, struct{name string; typeName string; outSchema *JSONSchemaRAML}{name: tt.name, typeName: typeName, outSchema: outSchema})
+						require.NoError(t, err, "Failed to convert annotation type shape in %s: %v", tt.path, err)
 						convertedCount++
 					}
 					for pair := f.Types.Oldest(); pair != nil; pair = pair.Next() {
 						s := pair.Value
-						_, errConv := conv.Convert(s.Shape)
-						require.NoError(t, errConv, "Failed to convert type shape in %s: %v", tt.path, errConv)
+						typeName := pair.Key
+						outSchema, err := conv.Convert(s.Shape)
+						writeToDiskHelper(t, struct{name string; typeName string; outSchema *JSONSchemaRAML}{name: tt.name, typeName: typeName, outSchema: outSchema})
+						require.NoError(t, err, "Failed to convert type shape in %s: %v", tt.path, err)
 						convertedCount++
 					}
 				case *DataType:
-					_, errConv := conv.Convert(f.Shape.Shape)
-					require.NoError(t, errConv, "Failed to convert data type shape in %s: %v", tt.path, errConv)
+					typeName := f.Shape.Name
+					outSchema, err := conv.Convert(f.Shape.Shape)
+					writeToDiskHelper(t, struct{name string; typeName string; outSchema *JSONSchemaRAML}{name: tt.name, typeName: typeName, outSchema: outSchema})
+					require.NoError(t, err, "Failed to convert data type shape in %s: %v", tt.path, err)
 					convertedCount++
 				}
 			}
@@ -136,8 +169,12 @@ func Test_ParseFixturesIntegration(t *testing.T) {
 			path: "./fixtures/library_invalid_unwrap.raml",
 		},
 		{
-			name: "named_example_invalid_decode.raml",
-			path: "./fixtures/named_example_invalid_decode.raml",
+			name: "library_invalid_recursive_trait.raml",
+			path: "./fixtures/library_invalid_inherited_recursive_trait.raml",
+		},
+		{
+			name: "library_invalid_trait_example.raml",
+			path: "./fixtures/library_invalid_trait_example.raml",
 		},
 	}
 

shape.go

@@ -528,7 +528,8 @@ func (r *RAML) MakeRecursiveShape(headBase *BaseShape) *BaseShape {
 	recursiveBase.Description = headBase.Description
 	recursiveBase.CustomDomainProperties = headBase.CustomDomainProperties
 	recursiveBase.CustomShapeFacets = headBase.CustomShapeFacets
-	recursiveBase.CustomShapeFacetDefinitions = headBase.CustomShapeFacetDefinitions
+	// Recursive shapes must not provide facet definitions,
+	// they are provided by the head shape.
 	s := &RecursiveShape{BaseShape: recursiveBase, Head: headBase}
 	recursiveBase.SetShape(s)
 	return recursiveBase

unwrap.go

@@ -199,12 +199,16 @@ func (r *RAML) FindAndMarkRecursion(base *BaseShape) (*BaseShape, error) {
 		return nil, err
 	}
 
+	// Reset the context to avoid generating recursive shape
+	// for trait that points to the same type that defines this trait.
+	// This is OK because traits cannot have nested traits and
+	// cannot be used as a source for inheritance.
+	base.ShapeVisited = false
 	err = r.findAndMarkRecursionInCustomShapeFacetDefinitions(base)
 	if err != nil {
 		return nil, err
 	}
 
-	base.ShapeVisited = false
 	return nil, ErrNil
 }
 
@@ -435,6 +439,8 @@ func (r *RAML) UnwrapShape(base *BaseShape) (*BaseShape, error) {
 			return nil, StacktraceNewWrapped("custom shape facet definition unwrap", errUnwrap, base.Location,
 				stacktrace.WithPosition(&base.Position), stacktrace.WithType(StacktraceTypeUnwrapping))
 		}
+		// Reset custom shape facet definitions since traits cannot have nested traits.
+		us.CustomShapeFacetDefinitions = orderedmap.New[string, Property]()
 		prop.Base = us
 		base.CustomShapeFacetDefinitions.Set(pair.Key, prop)
 	}

validate.go

@@ -285,6 +285,16 @@ func (r *RAML) validateShapeCommons(s *BaseShape) error {
 			}
 		}
 	}
+
+	// Validate trait definition shapes
+	for pair := s.CustomShapeFacetDefinitions.Oldest(); pair != nil; pair = pair.Next() {
+		facetDef := pair.Value
+		if err := r.validateShapeCommons(facetDef.Base); err != nil {
+			return StacktraceNewWrapped("validate custom facet definition", err, facetDef.Base.Location,
+				stacktrace.WithPosition(&facetDef.Base.Position), stacktrace.WithInfo("facet", pair.Key))
+		}
+	}
+
 	return nil
 }