How to programmatically generate JsonSchema representing binary content in Java

[lzemskov]

We have a Rest API which allows clients to GET back some binary content (e.g. Image) We are using JsonSchema to help describe the API in question so I want to built out a JsonSchema representing that content.

Looking through json-schema.org's recommendation called out HERE

The relevant JsonSchema can be represented as the following String Schema:

{
  "type": "string",
  "contentEncoding": "base64",
  "contentMediaType": "image/png"
}

• Searching around i found a similar question with solution but it's related to C# and relevant implementation of the underlying SchemaGenerator called out HERE So inspired by that I also tried looking through the com.fasterxml.jackson.module.jsonSchema.JsonSchemaGenerator but also was not able to figure out how to built the relevant schema using that either.

• I also tried creating a com.fasterxml.jackson.module.jsonSchema.types.StringSchema directly but was also not able to figure out how to set either contentEncoding or contentMediaType keywords for the generated StringSchema.

So was wondering if I may be missing something obvious and if anyone else happened to have any pointers on what can be done in this situation in order to generate the JsonSchema we desire?

[CarstenWickner]

Hi @lzemskov,

Some context might be helpful here. Is your API just returning binary content directly?

• If yes, then just taking the static schema should be good enough.
• If not, then I'm assuming you have a class, containing some property that represents the file contents, such as per this example:

public class BinarySchemaExample {

    public static void main(String[] args) throws JsonProcessingException {
        SchemaGeneratorConfigBuilder config = new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON);
        config.forTypesInGeneral().withCustomDefinitionProvider(new CustomBinaryDefinitionProvider());
        SchemaGenerator generator = new SchemaGenerator(config.build());
        JsonNode jsonSchema = generator.generateSchema(Foo.class);
        System.out.println(jsonSchema.toPrettyString());
    }

    static class Foo {
        String name;
        Bar content;
    }

    static class Bar {
        byte[] binaryData;
    }

    static class CustomBinaryDefinitionProvider implements CustomDefinitionProviderV2 {
        @Override
        public CustomDefinition provideCustomSchemaDefinition(ResolvedType javaType, SchemaGenerationContext context) {
            if (!javaType.isInstanceOf(Bar.class)) {
                return null;
            }
            ObjectNode subschema = context.getGeneratorConfig().createObjectNode()
                    .put(context.getKeyword(SchemaKeyword.TAG_TYPE), context.getKeyword(SchemaKeyword.TAG_TYPE_STRING))
                    .put("contentEncoding", "base64")
                    .put("contentMediaType", "image/png");
            return new CustomDefinition(subschema, CustomDefinition.DefinitionType.STANDARD, CustomDefinition.AttributeInclusion.NO);
        }
    }
}

The generated schema looks like this then:

{
  "$schema" : "https://json-schema.org/draft/2020-12/schema",
  "type" : "object",
  "properties" : {
    "content" : {
      "type" : "string",
      "contentEncoding" : "base64",
      "contentMediaType" : "image/png"
    },
    "name" : {
      "type" : "string"
    }
  }
}

You might want to be a bit smarter about where the "contentMediaType" value is coming from, but that should point you in the right direction, I hope. 😄

[lzemskov]

Thanks a lot for the response @CarstenWickner, in our case we do have a class which has several properties and one of those properties is an interface which represents the content, however the API client does not get JSON representation back with properties but rather a binary content directly.

I think you suggestion above around creating a new provider would work for our case as well and it was exactly what I was looking for.

But wanted to clarify on what you meant by:

If yes, then just taking the static schema should be good enough.

What do we mean by static schema, and how could we generate it?

[CarstenWickner]

This generator library provides the schema as JsonNode (or more specifically: ObjectNode).
If you are just returning the binary content directly, you might as well create the ObjectNode directly and don't bother using the schema generator in that case.

It's basically part of the CustomDefinitionProviderV2 example given above:

ObjectMapper objectMapper = new ObjectMapper();
ObjectNode binarySchema = objectMapper.createObjectNode()
        .put("type", "string")
        .put("contentEncoding", "base64")
        .put("contentMediaType", "image/png");