Adding a title in items, for array of ex Strings or Integers

[CathKilroy]

Hi

I want to add a title in items for array types. In my example below, I want to add a title in items. My array is an array of Strings.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "languageCodes": {
      "title": "Booking Engine Language Codes",
      "description": "Language Codes allowed in the Booking Engine.",
      "uniqueItems": true,
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "title": "Booking Engine Language Codes Properties Schema",
  "description": "",
  "additionalProperties": false
}

Br Casper

[CarstenWickner]

Hi @CathKilroy,

This is certainly possible. The question is mainly: where is that title supposed to be looked up from?

I've created a working example utilising the Swagger 2 annotations:

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.github.victools.jsonschema.generator.Option;
import com.github.victools.jsonschema.generator.OptionPreset;
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.SchemaVersion;
import com.github.victools.jsonschema.module.swagger2.Swagger2Module;
import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.media.Schema;
import java.util.List;

public class ArrayItemTitleExample {

    public static void main(String[] args) throws JsonProcessingException {
        SchemaGeneratorConfigBuilder configBuilder = new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_7, OptionPreset.PLAIN_JSON);
        configBuilder.with(Option.FORBIDDEN_ADDITIONAL_PROPERTIES_BY_DEFAULT);
        configBuilder.with(new Swagger2Module());
        SchemaGeneratorConfig config = configBuilder.build();
        SchemaGenerator generator = new SchemaGenerator(config);
        JsonNode jsonSchema = generator.generateSchema(TestType.class);
        System.out.println(jsonSchema.toPrettyString());
    }

    @Schema(title = "Booking Engine Language Codes Properties Schema")
    static class TestType {

        @ArraySchema(uniqueItems = true,
                arraySchema = @Schema(title = "Booking Engine Language Codes", description = "Language Codes allowed in the Booking Engine."),
                schema = @Schema(title = "Booking Engine Language Code", description = "two-digit ISO code"))
        List<String> languageCodes;
    }
}

The above produces the following output:

{
  "$schema" : "http://json-schema.org/draft-07/schema#",
  "type" : "object",
  "properties" : {
    "languageCodes" : {
      "title" : "Booking Engine Language Codes",
      "description" : "Language Codes allowed in the Booking Engine.",
      "uniqueItems" : true,
      "type" : "array",
      "items" : {
        "type" : "string",
        "title" : "Booking Engine Language Code",
        "description" : "two-digit ISO code"
      }
    }
  },
  "title" : "Booking Engine Language Codes Properties Schema",
  "additionalProperties" : false
}

Internally, the array item's "title" is being determined with something like this:

configBuilder.forFields().withTitleResolver(field -> {
    if (field.isFakeContainerItemScope()) {
        return Optional.ofNullable(field.getAnnotationConsideringFieldAndGetter(ArraySchema.class))
                .map(ArraySchema::schema)
                .map(Schema::title)
                .filter(title -> !title.isEmpty())
                .orElse(null);
    }
    return null;
});

It's important to note that a field/method with a container type (e.g. List, Set) will be handled twice.

1. On the first iteration, the given FieldScope will have the name "languageCodes" and be of type List<String>, with the isFakeContainerItemScope() method returning false.
2. The second time around, the given FieldScope will have the name "languageCodes" but the type String, while the isFakeContainerItemScope() method returns true.

I.e., it's worth considering the isFakeContainerItemScope() in your configPart.withTitleResolver() configuration.