fix: resolve nil reference errors and improve resolution interface

json/json.go

@@ -27,6 +27,10 @@ func YAMLToJSON(node *yaml.Node, indentation int, buffer io.Writer) error {
 }
 
 func handleYAMLNode(node *yaml.Node) (any, error) {
+	if node == nil {
+		return nil, nil
+	}
+
 	switch node.Kind {
 	case yaml.DocumentNode:
 		return handleYAMLNode(node.Content[0])

jsonschema/oas3/jsonschema.go

@@ -40,6 +40,8 @@ type JSONSchema[T Referenceable | Concrete] struct {
 	topLevelParent *JSONSchema[Referenceable] // Top-level parent (root of the reference chain)
 }
 
+var _ references.Resolvable[JSONSchema[Concrete]] = (*JSONSchema[Referenceable])(nil)
+
 func NewJSONSchemaFromSchema[T Referenceable | Concrete](value *Schema) *JSONSchema[T] {
 	return &JSONSchema[T]{
 		EitherValue: values.EitherValue[Schema, core.Schema, bool, bool]{

jsonschema/oas3/resolution.go

@@ -74,7 +74,18 @@ func (s *JSONSchema[Referenceable]) Resolve(ctx context.Context, opts ResolveOpt
 	}, []string{})
 }
 
+// GetResolvedObject will return either this schema or the referenced schema if previously resolved.
+// This methods is identical to GetResolvedSchema but was added to support the Resolvable interface
+func (s *JSONSchema[Referenceable]) GetResolvedObject() *JSONSchema[Concrete] {
+	if s == nil {
+		return nil
+	}
+
+	return s.GetResolvedSchema()
+}
+
 // GetResolvedSchema will return either this schema or the referenced schema if previously resolved.
+// This methods is identical to GetResolvedObject but was kept for backwards compatibility
 func (s *JSONSchema[Referenceable]) GetResolvedSchema() *JSONSchema[Concrete] {
 	if s == nil || !s.IsResolved() {
 		return nil

openapi/reference.go

@@ -205,6 +205,8 @@ type Reference[T any, V interfaces.Validator[T], C marshaller.CoreModeler] struc
 	topLevelParent *Reference[T, V, C] // Top-level parent (root of the reference chain)
 }
 
+var _ references.Resolvable[Info] = (*Reference[Info, *Info, *core.Info])(nil)
+
 var _ interfaces.Model[core.Reference[*core.Info]] = (*Reference[Info, *Info, *core.Info])(nil)
 
 // ResolveOptions represent the options available when resolving a reference.
@@ -265,7 +267,18 @@ func (r *Reference[T, V, C]) GetReference() references.Reference {
 	return *r.Reference
 }
 
+// GetResolvedObject will return the referenced object. If this is a reference and its unresolved, this will return nil.
+// This methods is identical to GetObject but was added to support the Resolvable interface
+func (r *Reference[T, V, C]) GetResolvedObject() *T {
+	if r == nil {
+		return nil
+	}
+
+	return r.GetObject()
+}
+
 // GetObject returns the referenced object. If this is a reference and its unresolved, this will return nil.
+// This methods is identical to GetResolvedObject but was kept for backwards compatibility
 func (r *Reference[T, V, C]) GetObject() *T {
 	if r == nil {
 		return nil

references/resolution.go

@@ -24,6 +24,11 @@ type ResolutionTarget interface {
 	StoreReferenceDocumentInCache(key string, doc []byte)
 }
 
+type Resolvable[T any] interface {
+	Resolve(ctx context.Context, opts ResolveOptions) ([]error, error)
+	GetResolvedObject() *T
+}
+
 // AbsoluteReferenceResult contains the result of resolving an absolute reference
 type AbsoluteReferenceResult struct {
 	// AbsoluteReference is the resolved absolute reference string