I try to add examples to an Avro schema.
Is there a way to add example values to an Avro schema?
Here is what I’m trying to do: I want to add some example values for the field name. I added the key examples to show that a name value can be John Smith.
However, I found nothing in the specification that would explain how to add examples. This code is just exemplary, inspired by JSON Schema.
{
"namespace": "example.avro",
"type": "record",
"name": "User",
"fields": [
{
"name": "name",
"type": "string",
"examples": ["John Smith"]
}
]
}
Is there a proper way to add examples according to the spec? The only thing I saw is the doc field, which, however, is a single JSON string.
Short version: use the “doc” attribute, like Javadoc, Python docstrings, Rust doc comments, etc.
Longer version:
Examples in an Avro schema are tricky: the schema is in a different format than the data, which means that examples for, for example, arrays, records, or logical types like timestamps cannot be represented ‘natively’. This makes literal examples, such as with an “examples” attribute, impossible.
Your best bet is to use the text in the “doc” attribute to describe functional examples. The translation to literal examples is then left as an exercise for the reader.
{
"type": "record",
"name": "details",
"fields": [
{
"name": "firstname",
"type": [
"null",
"string"
]
},
{
"name": "lastname",
"type": [
"null",
"string"
]
},
{
"name": "addressline1",
"type": [
"null",
"string"
]
},
{
"name": "addressline2",
"type": [
"null",
"string"
]
},
{
"name": "city",
"type": [
"null",
"string"
]
},
{
"name": "state",
"type": [
"null",
"string"
]
},
{
"name": "zipcode",
"type": [
"null",
"int"
]
},
{
"name": "country",
"type": [
"null",
"string"
]
},
{
"name": "hobbies",
"type": [
"null",
{
"type": "array",
"items": {
"name": "hobbies",
"type": "record",
"fields": [
{
"name": "hobby",
"type": [
"null",
"string"
]
},
{
"name": "SpentHours",
"type": [
"null",
"int"
]
}
]
}
}
]
}
]
}
1