avro-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Scott Carey <scottca...@apache.org>
Subject Re: Best practice for versioning IDLs?
Date Tue, 29 Nov 2011 18:22:32 GMT
I don't think there are yet best practices for what you are trying to do.

However, I suggest you first consider embedding the version as metadata in
the schema, rather than data.  If you put it in a Record, it will be data
serialized with every record.  If you put it as schema metadata, it will
only exist in the schemas and not the data.

In raw JSON schema form, the metadata can be added to any named type:
Record, Fixed, Enum, Protocol.   The "doc" field is a special named
metadata field, you can use it or add your own:

  "namespace": "com.acme",
  "protocol": "HelloWorld",
  "doc": "Protocol Greetings",
  "acme.version": "1.22.3",

  "types": [
    {"name": "Greeting", "type": "record", "fields": [
      {"name": "message", "type": "string"}]},
    {"name": "Curse", "type": "error", "fields": [
      {"name": "message", "type": "string"}]}

  "messages": {
    "hello": {
      "doc": "Say hello.",
      "request": [{"name": "greeting", "type": "Greeting" }],
      "response": "Greeting",
      "errors": ["Curse"]


For IDL, it should be possible to add a property using the
@propname("propval") annotation on the protocol.

I have not tried this myself however.

If I had the setup to test it now, I would try to see if the below AvroIDL
creates an empty protocol with the "acme.version" property set:

protocol HelloWorld {


On 11/29/11 9:20 AM, "George Fletcher" <gffletch@aol.com> wrote:

>    Hi,
>      I'd like to incorporate a semver.org style versioning structure
>      for the IDL files we are using. The IDLs represent interfaces of
>      services (ala SOA).
>      We currently manage our IDL files separately from the
>      implementation as multiple services might use the same IDL. This
>      makes it critical to have the IDL's understand their version. I'd
>      like to see our build process be able to inject into the IDL the
>      version from the build environment (currently maven). Another
>      option would be to define the version within the IDL. However, the
>      only way I can think of to do this, is to create a "Version"
>      Record within each IDL and then maybe have the Record contains 3
>      string fields (major, minor, patch).
>      Just wondering if there are any best practices already established
>      for this kind of IDL versioning.
>      Thanks,
>      George

View raw message