feat: add support to display examples

tests/schemas/Person-1.8.2.avsc

@@ -2,7 +2,7 @@
   "name": "Person",
   "type": "record",
   "fields": [
-    {"name": "name", "type": "string"},
+    {"name": "name", "type": "string", example: "Donkey"},
     {"name": "age", "type": ["null", "int"], "default": null},
     {
       "name": "favoriteProgrammingLanguage",
@@ -13,7 +13,7 @@
       "type": {
         "name": "Address",
         "type": "record",
-        "fields": [{"name": "zipcode", "type": "int"}]
+        "fields": [{"name": "zipcode", "type": "int", example: "53003"}]
       }
     }
   ]

tests/schemas/Person-1.9.0.avsc

@@ -2,8 +2,8 @@
   "name": "Person",
   "type": "record",
   "fields": [
-    {"name": "name", "type": "string"},
-    {"name": "age", "type": ["null", "int"], "default": null},
+    {"name": "name", "type": "string", example: "Donkey"},
+    {"name": "age", "type": ["null", "int"], "default": null, example: "123"},
     {
       "name": "favoriteProgrammingLanguage",
       "type": {"name": "ProgrammingLanguage", "type": "enum", "symbols": ["JS", "Java", "Go", "Rust", "C"], "default": "JS"}
@@ -13,7 +13,7 @@
       "type": {
         "name": "Address",
         "type": "record",
-        "fields": [{"name": "zipcode", "type": "int"}]
+        "fields": [{"name": "zipcode", "type": "int", example: "53003"}]
       }
     },
     {"name": "someid", "type": "uuid"}

tests/to-json-schema.test.js

@@ -59,7 +59,7 @@ describe('avroToJsonSchema()', function () {
 
   it('transforms union values', async function () {
     const result = await avroToJsonSchema(['null', 'int']);
-    expect(result).toEqual({ oneOf: [{ type: 'null' }, { type: 'integer', minimum: INT_MIN, maximum: INT_MAX }] });
+    expect(result).toEqual({ oneOf: [{ type: 'integer', minimum: INT_MIN, maximum: INT_MAX }, { type: 'null' }] });
   });
 
   it('transforms map values', async function () {

to-json-schema.js

@@ -21,17 +21,52 @@ const typeMappings = {
   uuid: 'string',
 };
 
+const commonAttributesMapping = (avroDefinition, jsonSchema) => {
+  if (avroDefinition.doc) jsonSchema.description = avroDefinition.doc;
+  if (avroDefinition.default !== undefined) jsonSchema.default = avroDefinition.default;
+};
+
+const exampleAttributeMapping = (typeInput, example, jsonSchemaInput) => {
+  let type = typeInput;
+  let jsonSchema = jsonSchemaInput;
+
+  // Map example to first non-null type
+  if (Array.isArray(typeInput) && typeInput.length > 0) {
+    const pickSecondType = typeInput.length > 1 && typeInput[0] === 'null';
+    type = typeInput[+pickSecondType];
+    jsonSchema = jsonSchema.oneOf[0];
+  }
+
+  if (example === undefined || jsonSchema.examples || Array.isArray(type)) return;
+
+  switch (type) {
+  case 'boolean':
+    jsonSchema.examples = [example === 'true'];
+    break;
+  case 'int':
+    jsonSchema.examples = [parseInt(example, 10)];
+    break;
+  default:
+    jsonSchema.examples = [example];
+  }
+};
+
 module.exports.avroToJsonSchema = async function avroToJsonSchema(avroDefinition) {
   const jsonSchema = {};
   const isUnion = Array.isArray(avroDefinition);
 
   if (isUnion) {
     jsonSchema.oneOf = [];
+    let nullDef = null;
     for (const avroDef of avroDefinition) {
       const def = await avroToJsonSchema(avroDef);
-      jsonSchema.oneOf.push(def);
+      const defType = avroDef.type || avroDef;
+      // To prefer non-null values in the examples put null as the last element
+      if (defType === 'null') nullDef = def; else jsonSchema.oneOf.push(def);
     }
 
+    if (nullDef) jsonSchema.oneOf.push(nullDef);
+
     return jsonSchema;
   }
 
@@ -70,16 +105,18 @@ module.exports.avroToJsonSchema = async function avroToJsonSchema(avroDefinition
     const propsMap = new Map();
     for (const field of avroDefinition.fields) {
       const def = await avroToJsonSchema(field.type);
-      if (field.doc) def.description = field.doc;
-      if (field.default) def.default = field.default;
+
+      commonAttributesMapping(field, def);
+      exampleAttributeMapping(field.type, field.example, def);
+
       propsMap.set(field.name, def);
     }
     jsonSchema.properties = Object.fromEntries(propsMap.entries());
     break;
   }
 
-  if (avroDefinition.doc) jsonSchema.description = avroDefinition.doc;
-  if (avroDefinition.default !== undefined) jsonSchema.default = avroDefinition.default;
+  commonAttributesMapping(avroDefinition, jsonSchema);
+  exampleAttributeMapping(type, avroDefinition.example, jsonSchema);
 
   return jsonSchema;
 };