feat: enable differentiating members declared by super types (#415)

* feat: register schema target type

* chore(example): add example for basic inheritance support

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### Changed
 - include new `Option.STANDARD_FORMATS` in `OptionPreset.PLAIN_JSON` by default
+- extended parameters for creation of `FieldScope`/`MethodScope` through the `TypeContext` to include type for which a schema is being generated
 
 #### Fixed
 - when using `Option.FIELDS_DERIVED_FROM_ARGUMENTFREE_METHODS` on a method where the second character of the derived field name is in uppercase, don't capitalise the first character

jsonschema-examples/src/main/java/com/github/victools/jsonschema/examples/InheritanceRefExample.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2023 VicTools.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.github.victools.jsonschema.examples;
+
+import com.fasterxml.classmate.ResolvedType;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.github.victools.jsonschema.generator.CustomDefinition;
+import com.github.victools.jsonschema.generator.CustomDefinitionProviderV2;
+import com.github.victools.jsonschema.generator.Option;
+import com.github.victools.jsonschema.generator.OptionPreset;
+import com.github.victools.jsonschema.generator.SchemaGenerationContext;
+import com.github.victools.jsonschema.generator.SchemaGenerator;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfig;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
+import com.github.victools.jsonschema.generator.SchemaKeyword;
+import com.github.victools.jsonschema.generator.SchemaVersion;
+import java.time.LocalDate;
+
+/**
+ * Example created in response to <a href="https://github.com/victools/jsonschema-generator/issues/407">#407</a>.
+ * <br>
+ * Reference separate definitions for common super types. Show-casing capabilities; but not recommended due to risk of infinite loop.
+ */
+public class InheritanceRefExample implements SchemaGenerationExampleInterface {
+
+    @Override
+    public ObjectNode generateSchema() {
+        SchemaGeneratorConfigBuilder configBuilder = new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON)
+                .with(Option.DEFINITIONS_FOR_ALL_OBJECTS);
+        // ignore all fields declared in super types
+        configBuilder.forFields()
+                .withIgnoreCheck(field -> !field.getDeclaringType().equals(field.getDeclarationDetails().getSchemaTargetType()));
+        // reference super types explicitly
+        configBuilder.forTypesInGeneral()
+                // including SubtypeResolver would result in a StackOverflowError as the super reference is again replaced with it subtypes
+                //.withSubtypeResolver(new SubtypeLookUpExample.ClassGraphSubtypeResolver())
+                .withCustomDefinitionProvider(new ParentReferenceDefinitionProvider());
+        SchemaGeneratorConfig config = configBuilder.build();
+        return new SchemaGenerator(config).generateSchema(TestType.class);
+    }
+
+    static class ParentReferenceDefinitionProvider implements CustomDefinitionProviderV2 {
+        @Override
+        public CustomDefinition provideCustomSchemaDefinition(ResolvedType javaType, SchemaGenerationContext context) {
+            if (javaType.getErasedType().getSuperclass() == null || javaType.getErasedType().getSuperclass() == Object.class) {
+                return null;
+            }
+            ResolvedType superType = context.getTypeContext().resolve(javaType.getErasedType().getSuperclass());
+            // two options here:
+            // 1. providing "null" as second parameter = multiple hierarchy levels are respected
+            // 2. providing "this" as second parameter = only one hierarchy level is respected
+            ObjectNode superTypeReference = context.createStandardDefinitionReference(superType, null);
+            ObjectNode definition = context.createStandardDefinition(javaType, this);
+            definition.withArray(context.getKeyword(SchemaKeyword.TAG_ALLOF))
+                    .add(superTypeReference);
+            return new CustomDefinition(definition, CustomDefinition.DefinitionType.STANDARD, CustomDefinition.AttributeInclusion.YES);
+        }
+    }
+
+    static class TestType {
+        public Book favoriteBook;
+        public Poster favoritePoster;
+    }
+
+    static class Book extends PrintPublication {
+        public int pageCount;
+    }
+
+    static class Poster extends PrintPublication {
+        public boolean forMovie;
+    }
+
+    static class PrintPublication extends Publication {
+        public String author;
+        public String publisher;
+    }
+
+    static class Publication {
+        public LocalDate published;
+        public String title;
+    }
+}

jsonschema-examples/src/test/java/com/github/victools/jsonschema/examples/ExampleTest.java

@@ -36,6 +36,7 @@ public class ExampleTest {
             ExternalRefAnnotationExample.class,
             ExternalRefPackageExample.class,
             IfThenElseExample.class,
+            InheritanceRefExample.class,
             JacksonDescriptionAsTitleExample.class,
             JacksonSubtypeDefinitionExample.class,
             StrictTypeInfoExample.class,

jsonschema-examples/src/test/resources/com/github/victools/jsonschema/examples/InheritanceRefExample-result.json

@@ -0,0 +1,56 @@
+{
+    "$schema" : "https://json-schema.org/draft/2020-12/schema",
+    "$defs" : {
+        "Book" : {
+            "type" : "object",
+            "properties" : {
+                "pageCount" : {
+                    "type" : "integer"
+                }
+            },
+            "$ref" : "#/$defs/PrintPublication"
+        },
+        "Poster" : {
+            "type" : "object",
+            "properties" : {
+                "forMovie" : {
+                    "type" : "boolean"
+                }
+            },
+            "$ref" : "#/$defs/PrintPublication"
+        },
+        "PrintPublication" : {
+            "type" : "object",
+            "properties" : {
+                "author" : {
+                    "type" : "string"
+                },
+                "publisher" : {
+                    "type" : "string"
+                }
+            },
+            "$ref" : "#/$defs/Publication"
+        },
+        "Publication" : {
+            "type" : "object",
+            "properties" : {
+                "published" : {
+                    "type" : "string",
+                    "format" : "date"
+                },
+                "title" : {
+                    "type" : "string"
+                }
+            }
+        }
+    },
+    "type" : "object",
+    "properties" : {
+        "favoriteBook" : {
+            "$ref" : "#/$defs/Book"
+        },
+        "favoritePoster" : {
+            "$ref" : "#/$defs/Poster"
+        }
+    }
+}

jsonschema-generator/src/main/java/com/github/victools/jsonschema/generator/FieldScope.java

@@ -40,38 +40,24 @@ public class FieldScope extends MemberScope<ResolvedField, Field> {
      * Constructor.
      *
      * @param field targeted field
-     * @param declaringTypeMembers collection of the declaring type's (other) fields and methods
+     * @param declarationDetails basic details regarding the declaration context
+     * @param overrideDetails augmenting details (e.g., overridden type, name, or container item index)
      * @param context the overall type resolution context
      */
-    protected FieldScope(ResolvedField field, ResolvedTypeWithMembers declaringTypeMembers, TypeContext context) {
-        this(field, null, null, declaringTypeMembers, null, context);
-    }
-
-    /**
-     * Constructor.
-     *
-     * @param field targeted field
-     * @param overriddenType alternative type for this field
-     * @param overriddenName alternative name for this field
-     * @param declaringTypeMembers collection of the declaring type's (other) fields and methods
-     * @param fakeContainerItemIndex index of the container item on the generic field/method scope's declared type (e.g., in case of a List, it is 0)
-     * @param context the overall type resolution context
-     */
-    protected FieldScope(ResolvedField field, ResolvedType overriddenType, String overriddenName,
-            ResolvedTypeWithMembers declaringTypeMembers, Integer fakeContainerItemIndex, TypeContext context) {
-        super(field, overriddenType, overriddenName, declaringTypeMembers, fakeContainerItemIndex, context);
+    protected FieldScope(ResolvedField field, DeclarationDetails declarationDetails, OverrideDetails overrideDetails, TypeContext context) {
+        super(field, declarationDetails, overrideDetails, context);
     }
 
     @Override
     public FieldScope withOverriddenType(ResolvedType overriddenType) {
-        return new FieldScope(this.getMember(), overriddenType, this.getOverriddenName(), this.getDeclaringTypeMembers(),
-                this.getFakeContainerItemIndex(), this.getContext());
+        OverrideDetails overrideDetails = new OverrideDetails(overriddenType, this.getOverriddenName(), this.getFakeContainerItemIndex());
+        return new FieldScope(this.getMember(), this.getDeclarationDetails(), overrideDetails, this.getContext());
     }
 
     @Override
     public FieldScope withOverriddenName(String overriddenName) {
-        return new FieldScope(this.getMember(), this.getOverriddenType(), overriddenName, this.getDeclaringTypeMembers(),
-                this.getFakeContainerItemIndex(), this.getContext());
+        OverrideDetails overrideDetails = new OverrideDetails(this.getOverriddenType(), overriddenName, this.getFakeContainerItemIndex());
+        return new FieldScope(this.getMember(), this.getDeclarationDetails(), overrideDetails, this.getContext());
     }
 
     @Override
@@ -135,7 +121,7 @@ private MethodScope doFindGetter() {
                 .filter(method -> method.isPublic() && method.getRawMember().getParameterCount() == 0)
                 .filter(method -> possibleGetterNames.contains(method.getName()))
                 .findFirst()
-                .map(method -> this.getContext().createMethodScope(method, this.getDeclaringTypeMembers()))
+                .map(method -> this.getContext().createMethodScope(method, this.getDeclarationDetails()))
                 .orElse(null);
     }
 

jsonschema-generator/src/main/java/com/github/victools/jsonschema/generator/MemberScope.java

@@ -37,30 +37,27 @@
 public abstract class MemberScope<M extends ResolvedMember<T>, T extends Member> extends TypeScope {
 
     private final M member;
+    private final DeclarationDetails declarationDetails;
     private final ResolvedType overriddenType;
     private final String overriddenName;
-    private final ResolvedTypeWithMembers declaringTypeMembers;
     private Integer fakeContainerItemIndex;
     private final LazyValue<String> schemaPropertyName = new LazyValue<>(this::doGetSchemaPropertyName);
 
     /**
      * Constructor.
      *
      * @param member targeted field or method
-     * @param overriddenType alternative type for this field or method's return value
-     * @param overriddenName alternative name for this field or method
-     * @param declaringTypeMembers collection of the declaring type's (other) fields and methods
-     * @param fakeContainerItemIndex index of the container item on the generic field/method scope's declared type (e.g., in case of a List, it is 0)
+     * @param declarationDetails basic details regarding the declaration context
+     * @param overrideDetails augmenting details (e.g., overridden type, name, or container item index)
      * @param context the overall type resolution context
      */
-    protected MemberScope(M member, ResolvedType overriddenType, String overriddenName,
-            ResolvedTypeWithMembers declaringTypeMembers, Integer fakeContainerItemIndex, TypeContext context) {
-        super(Optional.ofNullable(overriddenType).orElseGet(member::getType), context);
+    protected MemberScope(M member, DeclarationDetails declarationDetails, OverrideDetails overrideDetails, TypeContext context) {
+        super(Optional.ofNullable(OverrideDetails.getOverriddenType(overrideDetails)).orElseGet(member::getType), context);
         this.member = member;
-        this.overriddenType = overriddenType;
-        this.overriddenName = overriddenName;
-        this.declaringTypeMembers = declaringTypeMembers;
-        this.fakeContainerItemIndex = fakeContainerItemIndex;
+        this.declarationDetails = declarationDetails;
+        this.overriddenType = OverrideDetails.getOverriddenType(overrideDetails);
+        this.overriddenName = OverrideDetails.getOverriddenName(overrideDetails);
+        this.fakeContainerItemIndex = OverrideDetails.getFakeContainerItemIndex(overrideDetails);
     }
 
     /**
@@ -135,13 +132,22 @@ public M getMember() {
         return this.member;
     }
 
+    /**
+     * Getter for additional declaration context information.
+     *
+     * @return wrapper for the schema target type and declaring type's field and methods
+     */
+    public DeclarationDetails getDeclarationDetails() {
+        return this.declarationDetails;
+    }
+
     /**
      * Getter for the collection of the member's declaring type's (other) fields and methods.
      *
      * @return declaring type's fields and methods
      */
     public ResolvedTypeWithMembers getDeclaringTypeMembers() {
-        return this.declaringTypeMembers;
+        return this.declarationDetails.getDeclaringTypeMembers();
     }
 
     /**
@@ -475,4 +481,64 @@ public String getSchemaPropertyName() {
     public String toString() {
         return this.getSimpleTypeDescription() + " " + this.getSchemaPropertyName();
     }
+
+    public static class DeclarationDetails {
+        private final ResolvedType schemaTargetType;
+        private final ResolvedTypeWithMembers declaringTypeMembers;
+
+        public DeclarationDetails(ResolvedType schemaTargetType, ResolvedTypeWithMembers declaringTypeMembers) {
+            this.schemaTargetType = schemaTargetType;
+            this.declaringTypeMembers = declaringTypeMembers;
+        }
+
+        /**
+         * Getter for the specific type for which a schema is being generated, that includes this field/method. This can differ from the wrapped
+         * member's declaring type, if that declaring type is an implemented interface or super type of the targeted one.
+         *
+         * @return target type for which a schema is being generated including this field/method
+         */
+        public ResolvedType getSchemaTargetType() {
+            return this.schemaTargetType;
+        }
+
+        /**
+         * Getter for the collection of the member's declaring type's (other) fields and methods.
+         *
+         * @return declaring type's fields and methods
+         */
+        public ResolvedTypeWithMembers getDeclaringTypeMembers() {
+            return this.declaringTypeMembers;
+        }
+    }
+
+    static class OverrideDetails {
+        private final ResolvedType overriddenType;
+        private final String overriddenName;
+        private final Integer fakeContainerItemIndex;
+
+        /**
+         * Constructor.
+         *
+         * @param overriddenType alternative type for this field or method's return value
+         * @param overriddenName alternative name for this field or method
+         * @param fakeContainerItemIndex index of the container item on the generic field/method's declared type (e.g., in case of a List, it is 0)
+         */
+        OverrideDetails(ResolvedType overriddenType, String overriddenName, Integer fakeContainerItemIndex) {
+            this.overriddenType = overriddenType;
+            this.overriddenName = overriddenName;
+            this.fakeContainerItemIndex = fakeContainerItemIndex;
+        }
+
+        private static ResolvedType getOverriddenType(OverrideDetails details) {
+            return details == null ? null : details.overriddenType;
+        }
+
+        private static String getOverriddenName(OverrideDetails details) {
+            return details == null ? null : details.overriddenName;
+        }
+
+        private static Integer getFakeContainerItemIndex(OverrideDetails details) {
+            return details == null ? null : details.fakeContainerItemIndex;
+        }
+    }
 }