| <!doctype html><html lang=en class=no-js><head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1,shrink-to-fit=no"><meta name=generator content="Hugo 0.111.3"><link rel=alternate type=text/html href=/update-site/docs/++version++/idl-language/_print/><link rel=alternate type=application/rss+xml href=/update-site/docs/++version++/idl-language/index.xml><meta name=robots content="index, follow"><link rel=apple-touch-icon sizes=57x57 href=https://apache.org/favicons/apple-touch-icon-57x57.png><link rel=apple-touch-icon sizes=60x60 href=https://apache.org/favicons/apple-touch-icon-60x60.png><link rel=apple-touch-icon sizes=72x72 href=https://apache.org/favicons/apple-touch-icon-72x72.png><link rel=apple-touch-icon sizes=76x76 href=https://apache.org/favicons/apple-touch-icon-76x76.png><link rel=apple-touch-icon sizes=114x114 href=https://apache.org/favicons/apple-touch-icon-114x114.png><link rel=apple-touch-icon sizes=120x120 href=https://apache.org/favicons/apple-touch-icon-120x120.png><link rel=apple-touch-icon sizes=144x144 href=https://apache.org/favicons/apple-touch-icon-144x144.png><link rel=apple-touch-icon sizes=152x152 href=https://apache.org/favicons/apple-touch-icon-152x152.png><link rel=apple-touch-icon sizes=180x180 href=https://apache.org/favicons/apple-touch-icon-180x180.png><link rel=icon type=image/png href=https://apache.org/favicons/favicon-32x32.png sizes=32x32><link rel=icon type=image/png href=https://apache.org/favicons/favicon-194x194.png sizes=194x194><link rel=icon type=image/png href=https://apache.org/favicons/favicon-96x96.png sizes=96x96><link rel=icon type=image/png href=https://apache.org/favicons/android-chrome-192x192.png sizes=192x192><link rel=icon type=image/png href=https://apache.org/favicons/favicon-16x16.png sizes=16x16><link rel=manifest href=https://apache.org/favicons/manifest.json><link rel="shortcut icon" href=https://apache.org/favicons/favicon.ico><title>IDL Language | Apache Avro</title><meta name=description content><meta property="og:title" content="IDL Language"><meta property="og:description" content><meta property="og:type" content="website"><meta property="og:url" content="/update-site/docs/++version++/idl-language/"><meta property="og:site_name" content="Apache Avro"><meta itemprop=name content="IDL Language"><meta itemprop=description content><meta name=twitter:card content="summary"><meta name=twitter:title content="IDL Language"><meta name=twitter:description content><link rel=preload href=/update-site/scss/main.min.6deb8a211453721a965671b611280fb11af8ef2def6b7a2b0a34f6a94939360f.css as=style><link href=/update-site/scss/main.min.6deb8a211453721a965671b611280fb11af8ef2def6b7a2b0a34f6a94939360f.css rel=stylesheet integrity><script src=https://code.jquery.com/jquery-3.5.1.min.js integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0=" crossorigin=anonymous></script> |
| <link rel=stylesheet href=/css/prism.css></head><body class=td-section><header><nav class="js-navbar-scroll navbar navbar-expand navbar-dark flex-column flex-md-row td-navbar"><a class=navbar-brand href=/update-site/><span class=navbar-logo><img src=/docs/++version++/logo.svg width=100 height=30 style="margin:0 10px"></span><span class="text-uppercase font-weight-bold">Apache Avro</span></a><div class="td-navbar-nav-scroll ml-md-auto" id=main_navbar><ul class="navbar-nav mt-2 mt-lg-0"><li class="nav-item mr-4 mb-2 mb-lg-0"><a class=nav-link href=/update-site/project/><span>Project</span></a></li><li class="nav-item mr-4 mb-2 mb-lg-0"><a class=nav-link href=/update-site/blog/><span>Blog</span></a></li><li class="nav-item mr-4 mb-2 mb-lg-0"><a class=nav-link href=/update-site/community/><span>Community</span></a></li><li class="nav-item dropdown mr-4 d-none d-lg-block"><a class="nav-link dropdown-toggle" href=# id=navbarDropdown role=button data-toggle=dropdown aria-haspopup=true aria-expanded=false>Documentation</a><div class=dropdown-menu aria-labelledby=navbarDropdownMenuLink><a class=dropdown-item href=./docs/++version++/>++version++ (Current)</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.11.0/>1.11.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.10.2/>1.10.2</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.10.1/>1.10.1</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.10.0/>1.10.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.9.2/>1.9.2</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.9.1/>1.9.1</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.9.0/>1.9.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.8.2/>1.8.2</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.8.1/>1.8.1</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.8.0/>1.8.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.7.7/>1.7.7</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.7.6/>1.7.6</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.7.5/>1.7.5</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.7.4/>1.7.4</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.7.3/>1.7.3</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.7.2/>1.7.2</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.7.1/>1.7.1</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.7.0/>1.7.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.6.3/>1.6.3</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.6.2/>1.6.2</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.6.1/>1.6.1</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.6.0/>1.6.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.5.4/>1.5.4</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.5.3/>1.5.3</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.5.2/>1.5.2</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.5.1/>1.5.1</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.5.0/>1.5.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.4.1/>1.4.1</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.4.0/>1.4.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.3.3/>1.3.3</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.3.2/>1.3.2</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.3.1/>1.3.1</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.3.0/>1.3.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.2.0/>1.2.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.1.0/>1.1.0</a> |
| <a class=dropdown-item href=https://avro.apache.org/docs/1.0.0/>1.0.0</a></div></li><li class="nav-item dropdown mr-4 d-none d-lg-block"><a class="nav-link dropdown-toggle" href=# id=navbarDropdown role=button data-toggle=dropdown aria-haspopup=true aria-expanded=false>ASF links</a><div class=dropdown-menu aria-labelledby=navbarDropdownMenuLink><a class=dropdown-item href=http://www.apache.org/ target=_blank>ASF Web Site</a> |
| <a class=dropdown-item href=http://www.apache.org/licenses/ target=_blank>License</a> |
| <a class=dropdown-item href=http://www.apache.org/foundation/sponsorship.html target=_blank>Donate</a> |
| <a class=dropdown-item href=http://www.apache.org/foundation/thanks.html target=_blank>Thanks</a> |
| <a class=dropdown-item href=http://www.apache.org/security/ target=_blank>Security</a></div></li></ul></div><div class="navbar-nav d-none d-lg-block"></div></nav></header><div class="container-fluid td-outer"><div class=td-main><div class="row flex-xl-nowrap"><aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none"><div id=td-sidebar-menu class=td-sidebar__inner><div id=content-mobile><form class="td-sidebar__search d-flex align-items-center"><button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type=button data-toggle=collapse data-target=#td-section-nav aria-controls=td-docs-nav aria-expanded=false aria-label="Toggle section navigation"></button></form></div><div id=content-desktop></div><nav class="collapse td-sidebar-nav foldable-nav" id=td-section-nav><ul class="td-sidebar-nav__section pr-md-3 ul-0"><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child active-path" id=m-update-sitedocs-li><a href=/update-site/docs/ class="align-left pl-0 td-sidebar-link td-sidebar-link__section tree-root" id=m-update-sitedocs><span>Documentation</span></a><ul class=ul-1><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child active-path" id=m-update-sitedocsversion-li><input type=checkbox id=m-update-sitedocsversion-check checked> |
| <label for=m-update-sitedocsversion-check><a href=/update-site/docs/++version++/ title="Apache Avro™ ++version++ Documentation" class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id=m-update-sitedocsversion><span>++version++</span></a></label><ul class="ul-2 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversiongetting-started-java-li><input type=checkbox id=m-update-sitedocsversiongetting-started-java-check> |
| <label for=m-update-sitedocsversiongetting-started-java-check><a href=/update-site/docs/++version++/getting-started-java/ class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id=m-update-sitedocsversiongetting-started-java><span>Getting Started (Java)</span></a></label></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversiongetting-started-python-li><input type=checkbox id=m-update-sitedocsversiongetting-started-python-check> |
| <label for=m-update-sitedocsversiongetting-started-python-check><a href=/update-site/docs/++version++/getting-started-python/ class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id=m-update-sitedocsversiongetting-started-python><span>Getting Started (Python)</span></a></label></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversionspecification-li><input type=checkbox id=m-update-sitedocsversionspecification-check> |
| <label for=m-update-sitedocsversionspecification-check><a href=/update-site/docs/++version++/specification/ class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id=m-update-sitedocsversionspecification><span>Specification</span></a></label></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversionapi-java-li><input type=checkbox id=m-update-sitedocsversionapi-java-check> |
| <label for=m-update-sitedocsversionapi-java-check><a href=./api/java/ class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id=m-update-sitedocsversionapi-java><span>Java API</span></a></label></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversionapi-c-li><input type=checkbox id=m-update-sitedocsversionapi-c-check> |
| <label for=m-update-sitedocsversionapi-c-check><a href=./api/c/ class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id=m-update-sitedocsversionapi-c><span>C API</span></a></label></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversionapi-c-li><input type=checkbox id=m-update-sitedocsversionapi-c-check> |
| <label for=m-update-sitedocsversionapi-c-check><a href=./api/cpp/html/ class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id=m-update-sitedocsversionapi-c><span>C++ API</span></a></label></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversionapi-csharp-li><input type=checkbox id=m-update-sitedocsversionapi-csharp-check> |
| <label for=m-update-sitedocsversionapi-csharp-check><a href=./api/csharp/html/ class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id=m-update-sitedocsversionapi-csharp><span>C# API</span></a></label></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversionmapreduce-guide-li><input type=checkbox id=m-update-sitedocsversionmapreduce-guide-check> |
| <label for=m-update-sitedocsversionmapreduce-guide-check><a href=/update-site/docs/++version++/mapreduce-guide/ class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id=m-update-sitedocsversionmapreduce-guide><span>MapReduce guide</span></a></label></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversionidl-language-li><input type=checkbox id=m-update-sitedocsversionidl-language-check> |
| <label for=m-update-sitedocsversionidl-language-check><a href=/update-site/docs/++version++/idl-language/ class="align-left pl-0 active td-sidebar-link td-sidebar-link__section" id=m-update-sitedocsversionidl-language><span class=td-sidebar-nav-active-item>IDL Language</span></a></label></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-update-sitedocsversionsasl-profile-li><input type=checkbox id=m-update-sitedocsversionsasl-profile-check> |
| <label for=m-update-sitedocsversionsasl-profile-check><a href=/update-site/docs/++version++/sasl-profile/ class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id=m-update-sitedocsversionsasl-profile><span>SASL profile</span></a></label></li></ul></li></ul></li></ul></nav></div></aside><aside class="d-none d-xl-block col-xl-2 td-sidebar-toc d-print-none"><div class="td-page-meta ml-2 pb-1 pt-2 mb-0"><a href=https://github.com/apache/avro/tree/master/doc/content/en/docs/++version++/IDL%20Language/_index.md class=td-page-meta--view target=_blank rel=noopener><i class="fa fa-file-alt fa-fw"></i> View page source</a> |
| <a href=https://github.com/apache/avro/edit/master/doc/content/en/docs/++version++/IDL%20Language/_index.md class=td-page-meta--edit target=_blank rel=noopener><i class="fa fa-edit fa-fw"></i> Edit this page</a> |
| <a href="https://github.com/apache/avro/new/master/doc/content/en/docs/++version++/IDL%20Language/_index.md?filename=change-me.md&value=---%0Atitle%3A+%22Long+Page+Title%22%0AlinkTitle%3A+%22Short+Nav+Title%22%0Aweight%3A+100%0Adescription%3A+%3E-%0A+++++Page+description+for+heading+and+indexes.%0A---%0A%0A%23%23+Heading%0A%0AEdit+this+template+to+create+your+new+page.%0A%0A%2A+Give+it+a+good+name%2C+ending+in+%60.md%60+-+e.g.+%60getting-started.md%60%0A%2A+Edit+the+%22front+matter%22+section+at+the+top+of+the+page+%28weight+controls+how+its+ordered+amongst+other+pages+in+the+same+directory%3B+lowest+number+first%29.%0A%2A+Add+a+good+commit+message+at+the+bottom+of+the+page+%28%3C80+characters%3B+use+the+extended+description+field+for+more+detail%29.%0A%2A+Create+a+new+branch+so+you+can+preview+your+new+file+and+request+a+review+via+Pull+Request.%0A" class=td-page-meta--child target=_blank rel=noopener><i class="fa fa-edit fa-fw"></i> Create child page</a> |
| <a href="https://github.com/apache/avro/issues/new?title=IDL%20Language" class=td-page-meta--issue target=_blank rel=noopener><i class="fab fa-github fa-fw"></i> Create documentation issue</a> |
| <a href=https://github.com/apache/avro/issues/new class=td-page-meta--project-issue target=_blank rel=noopener><i class="fas fa-tasks fa-fw"></i> Create project issue</a> |
| <a id=print href=/update-site/docs/++version++/idl-language/_print/><i class="fa fa-print fa-fw"></i> Print entire section</a></div><div class=td-toc><nav id=TableOfContents><ul><li><a href=#introduction>Introduction</a></li><li><a href=#overview>Overview</a><ul><li><a href=#purpose>Purpose</a></li><li><a href=#usage>Usage</a></li></ul></li><li><a href=#defining-a-protocol-in-avro-idl>Defining a Protocol in Avro IDL</a></li><li><a href=#imports>Imports</a></li><li><a href=#defining-an-enumeration>Defining an Enumeration</a></li><li><a href=#defining-a-fixed-length-field>Defining a Fixed Length Field</a></li><li><a href=#defining-records-and-errors>Defining Records and Errors</a><ul><li><a href=#primitive-types>Primitive Types</a></li><li><a href=#logical-types>Logical Types</a></li><li><a href=#references-to-named-schemata>References to Named Schemata</a></li><li><a href=#default-values>Default Values</a></li><li><a href=#complex-types>Complex Types</a></li></ul></li><li><a href=#defining-rpc-messages>Defining RPC Messages</a></li><li><a href=#other-language-features>Other Language Features</a><ul><li><a href=#comments>Comments</a></li><li><a href=#escaping-identifiers>Escaping Identifiers</a></li><li><a href=#annotations-for-ordering-and-namespaces>Annotations for Ordering and Namespaces</a></li></ul></li><li><a href=#complete-example>Complete Example</a></li><li><a href=#ide-support>IDE support</a><ul><li><a href=#jetbrains>JetBrains</a></li><li><a href=#eclipse>Eclipse</a></li><li><a href=#visual-studio-code>Visual Studio Code</a></li><li><a href=#atomio>Atom.io</a></li><li><a href=#vim>Vim</a></li></ul></li></ul></nav></div><div class="taxonomy taxonomy-terms-cloud taxo-tags"><h5 class=taxonomy-title>Tag Cloud</h5><ul class=taxonomy-terms><li><a class=taxonomy-term href=/update-site/tags/java/ data-taxonomy-term=java><span class=taxonomy-label>java</span><span class=taxonomy-count>1</span></a></li><li><a class=taxonomy-term href=/update-site/tags/python/ data-taxonomy-term=python><span class=taxonomy-label>python</span><span class=taxonomy-count>1</span></a></li></ul></div></aside><main class="col-12 col-md-9 col-xl-8 pl-md-5" role=main><nav aria-label=breadcrumb class=td-breadcrumbs><ol class=breadcrumb><li class=breadcrumb-item><a href=/update-site/docs/>Documentation</a></li><li class=breadcrumb-item><a href=/update-site/docs/++version++/>++version++</a></li><li class="breadcrumb-item active" aria-current=page><a href=/update-site/docs/++version++/idl-language/>IDL Language</a></li></ol></nav><div class=td-content><h1>IDL Language</h1><header class=article-meta><p class=reading-time><i class="fa fa-clock" aria-hidden=true></i> 10 minute read </p></header><h2 id=introduction>Introduction</h2><p>This document defines Avro IDL, a higher-level language for authoring Avro schemata. Before reading this document, you should have familiarity with the concepts of schemata and protocols, as well as the various primitive and complex types available in Avro.</p><h2 id=overview>Overview</h2><h3 id=purpose>Purpose</h3><p>The aim of the Avro IDL language is to enable developers to author schemata in a way that feels more similar to common programming languages like Java, C++, or Python. Additionally, the Avro IDL language may feel more familiar for those users who have previously used the interface description languages (IDLs) in other frameworks like Thrift, Protocol Buffers, or CORBA.</p><h3 id=usage>Usage</h3><p>Each Avro IDL file defines a single Avro Protocol, and thus generates as its output a JSON-format Avro Protocol file with extension .avpr.</p><p>To convert a <em>.avdl</em> file into a <em>.avpr</em> file, it may be processed by the <code>idl</code> tool. For example:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-shell data-lang=shell><span style=display:flex><span>$ java -jar avro-tools.jar idl src/test/idl/input/namespaces.avdl /tmp/namespaces.avpr |
| </span></span><span style=display:flex><span>$ head /tmp/namespaces.avpr |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#4e9a06>"protocol"</span> : <span style=color:#4e9a06>"TestNamespace"</span>, |
| </span></span><span style=display:flex><span> <span style=color:#4e9a06>"namespace"</span> : <span style=color:#4e9a06>"avro.test.protocol"</span>, |
| </span></span></code></pre></div><p>The <code>idl</code> tool can also process input to and from <em>stdin</em> and <em>stdout</em>. See <code>idl --help</code> for full usage information.</p><p>A Maven plugin is also provided to compile .avdl files. To use it, add something like the following to your pom.xml:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-xml data-lang=xml><span style=display:flex><span><span style=color:#204a87;font-weight:700><build></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700><plugins></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700><plugin></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700><groupId></span>org.apache.avro<span style=color:#204a87;font-weight:700></groupId></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700><artifactId></span>avro-maven-plugin<span style=color:#204a87;font-weight:700></artifactId></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700><executions></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700><execution></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700><goals></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700><goal></span>idl-protocol<span style=color:#204a87;font-weight:700></goal></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700></goals></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700></execution></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700></executions></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700></plugin></span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700></plugins></span> |
| </span></span><span style=display:flex><span><span style=color:#204a87;font-weight:700></build></span> |
| </span></span></code></pre></div><h2 id=defining-a-protocol-in-avro-idl>Defining a Protocol in Avro IDL</h2><p>An Avro IDL file consists of exactly one protocol definition. The minimal protocol is defined by the following code:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>protocol</span> <span style=color:#000>MyProtocol</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>This is equivalent to (and generates) the following JSON protocol definition:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-json data-lang=json><span style=display:flex><span><span style=color:#000;font-weight:700>{</span> |
| </span></span><span style=display:flex><span><span style=color:#204a87;font-weight:700>"protocol"</span> <span style=color:#000;font-weight:700>:</span> <span style=color:#4e9a06>"MyProtocol"</span><span style=color:#000;font-weight:700>,</span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700>"types"</span> <span style=color:#000;font-weight:700>:</span> <span style=color:#000;font-weight:700>[</span> <span style=color:#000;font-weight:700>],</span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700>"messages"</span> <span style=color:#000;font-weight:700>:</span> <span style=color:#000;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000;font-weight:700>}</span> |
| </span></span><span style=display:flex><span><span style=color:#000;font-weight:700>}</span> |
| </span></span></code></pre></div><p>The namespace of the protocol may be changed using the @namespace annotation:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#5c35cc;font-weight:700>@namespace</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"mynamespace"</span><span style=color:#ce5c00;font-weight:700>)</span> |
| </span></span><span style=display:flex><span><span style=color:#000>protocol</span> <span style=color:#000>MyProtocol</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>This notation is used throughout Avro IDL as a way of specifying properties for the annotated element, as will be described later in this document.</p><p>Protocols in Avro IDL can contain the following items:</p><ul><li>Imports of external protocol and schema files.</li><li>Definitions of named schemata, including records, errors, enums, and fixeds.</li><li>Definitions of RPC messages</li></ul><h2 id=imports>Imports</h2><p>Files may be imported in one of three formats:</p><ul><li><p>An IDL file may be imported with a statement like:</p><p><code>import idl "foo.avdl";</code></p></li><li><p>A JSON protocol file may be imported with a statement like:</p><p><code>import protocol "foo.avpr";</code></p></li><li><p>A JSON schema file may be imported with a statement like:</p><p><code>import schema "foo.avsc";</code></p></li></ul><p>Messages and types in the imported file are added to this file’s protocol.</p><p>Imported file names are resolved relative to the current IDL file.</p><h2 id=defining-an-enumeration>Defining an Enumeration</h2><p>Enums are defined in Avro IDL using a syntax similar to C or Java. An Avro Enum supports optional default values. In the case that a reader schema is unable to recognize a symbol written by the writer, the reader will fall back to using the defined default value. This default is only used when an incompatible symbol is read. It is not used if the enum field is missing.</p><p>Example Writer Enum Definition</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#204a87;font-weight:700>enum</span> <span style=color:#000>Shapes</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>SQUARE</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#000>TRIANGLE</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#000>CIRCLE</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#000>OVAL</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>Example Reader Enum Definition</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#204a87;font-weight:700>enum</span> <span style=color:#000>Shapes</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>SQUARE</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#000>TRIANGLE</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#000>CIRCLE</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#000>CIRCLE</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span></code></pre></div><p>In the above example, the reader will use the default value of <code>CIRCLE</code> whenever reading data written with the <code>OVAL</code> symbol of the writer. Also note that, unlike the JSON format, anonymous enums cannot be defined.</p><h2 id=defining-a-fixed-length-field>Defining a Fixed Length Field</h2><p>Fixed fields are defined using the following syntax:</p><pre tabindex=0><code>fixed MD5(16); |
| </code></pre><p>This example defines a fixed-length type called MD5 which contains 16 bytes.</p><h2 id=defining-records-and-errors>Defining Records and Errors</h2><p>Records are defined in Avro IDL using a syntax similar to a struct definition in C:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>Employee</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#000>name</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700>boolean</span> <span style=color:#000>active</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#204a87;font-weight:700>true</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700>long</span> <span style=color:#000>salary</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>The above example defines a record with the name “Employee” with three fields.</p><p>To define an error, simply use the keyword <em>error</em> instead of <em>record</em>. For example:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>error</span> <span style=color:#000>Kaboom</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#000>explanation</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700>int</span> <span style=color:#000>result_code</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#ce5c00;font-weight:700>-</span><span style=color:#0000cf;font-weight:700>1</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>Each field in a record or error consists of a type and a name, optional property annotations and an optional default value.</p><p>A type reference in Avro IDL must be one of:</p><ul><li>A primitive type</li><li>A logical type</li><li>A named schema defined prior to this usage in the same Protocol</li><li>A complex type (array, map, or union)</li></ul><h3 id=primitive-types>Primitive Types</h3><p>The primitive types supported by Avro IDL are the same as those supported by Avro’s JSON format. This list includes <em>int</em>, <em>long</em>, <em>string</em>, <em>boolean</em>, <em>float</em>, <em>double</em>, <em>null</em>, and <em>bytes</em>.</p><h3 id=logical-types>Logical Types</h3><p>Some of the logical types supported by Avro’s JSON format are also supported by Avro IDL. The currently supported types are:</p><ul><li><em>decimal</em> (logical type <a href=/update-site/docs/++version++/specification/#decimal>decimal</a>)</li><li><em>date</em> (logical type <a href=/update-site/docs/++version++/specification/#date>date</a>)</li><li><em>time_ms</em> (logical type <a href=/update-site/docs/++version++/specification/#time-millisecond-precision>time-millis</a>)</li><li><em>timestamp_ms</em> (logical type <a href=/update-site/docs/++version++/specification/#timestamp-millisecond-precision>timestamp-millis</a>)</li><li><em>uuid</em> (logical type <a href=/update-site/docs/++version++/specification/#uuid>uuid</a>)</li></ul><p>For example:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>Job</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#000>jobid</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>date</span> <span style=color:#000>submitDate</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>time_ms</span> <span style=color:#000>submitTime</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>timestamp_ms</span> <span style=color:#000>finishTime</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>decimal</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#0000cf;font-weight:700>9</span><span style=color:#ce5c00;font-weight:700>,</span><span style=color:#0000cf;font-weight:700>2</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>finishRatio</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>uuid</span> <span style=color:#000>pk</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#4e9a06>"a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>Logical types can also be specified via an annotation, which is useful for logical types for which a keyword does not exist:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>Job</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#000>jobid</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#5c35cc;font-weight:700>@logicalType</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"timestamp-micros"</span><span style=color:#ce5c00;font-weight:700>)</span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700>long</span> <span style=color:#000>finishTime</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><h3 id=references-to-named-schemata>References to Named Schemata</h3><p>If a named schema has already been defined in the same Avro IDL file, it may be referenced by name as if it were a primitive type:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>Card</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>Suit</span> <span style=color:#000>suit</span><span style=color:#ce5c00;font-weight:700>;</span> <span style=color:#8f5902;font-style:italic>// refers to the enum Card defined above |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic></span> <span style=color:#204a87;font-weight:700>int</span> <span style=color:#000>number</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><h3 id=default-values>Default Values</h3><p>Default values for fields may be optionally specified by using an equals sign after the field name followed by a JSON expression indicating the default value. This JSON is interpreted as described in the <a href=/update-site/docs/++version++/specification/#schema-record>spec</a>.</p><h3 id=complex-types>Complex Types</h3><h4 id=arrays>Arrays</h4><p>Array types are written in a manner that will seem familiar to C++ or Java programmers. An array of any type t is denoted <code>array<t></code>. For example, an array of strings is denoted <code>array<string></code>, and a multidimensional array of Foo records would be <code>array<array<Foo>></code>.</p><h4 id=maps>Maps</h4><p>Map types are written similarly to array types. An array that contains values of type t is written <code>map<t></code>. As in the JSON schema format, all maps contain <code>string</code>-type keys.</p><h4 id=unions>Unions</h4><p>Union types are denoted as <code>union { typeA, typeB, typeC, ... }</code>. For example, this record contains a string field that is optional (unioned with null), and a field containing either a precise or a imprecise number:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>RecordWithUnion</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>union</span> <span style=color:#ce5c00;font-weight:700>{</span> <span style=color:#204a87;font-weight:700>null</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#000>string</span> <span style=color:#ce5c00;font-weight:700>}</span> <span style=color:#000>optionalString</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>union</span> <span style=color:#ce5c00;font-weight:700>{</span> <span style=color:#000>decimal</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#0000cf;font-weight:700>12</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#0000cf;font-weight:700>6</span><span style=color:#ce5c00;font-weight:700>),</span> <span style=color:#204a87;font-weight:700>float</span> <span style=color:#ce5c00;font-weight:700>}</span> <span style=color:#000>number</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>Note that the same restrictions apply to Avro IDL unions as apply to unions defined in the JSON format; namely, a record may not contain multiple elements of the same type. Also, fields/parameters that use the union type and have a default parameter must specify a default value of the same type as the <strong>first</strong> union type.</p><p>Because it occurs so often, there is a special shorthand to denote a union of <code>null</code> with another type. In the following snippet, the first three fields have identical types:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>RecordWithUnion</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>union</span> <span style=color:#ce5c00;font-weight:700>{</span> <span style=color:#204a87;font-weight:700>null</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#000>string</span> <span style=color:#ce5c00;font-weight:700>}</span> <span style=color:#000>optionalString1</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#204a87;font-weight:700>null</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span><span style=color:#ce5c00;font-weight:700>?</span> <span style=color:#000>optionalString2</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#204a87;font-weight:700>null</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span><span style=color:#ce5c00;font-weight:700>?</span> <span style=color:#000>optionalString3</span><span style=color:#ce5c00;font-weight:700>;</span> <span style=color:#8f5902;font-style:italic>// No default value |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic></span> <span style=color:#000>string</span><span style=color:#ce5c00;font-weight:700>?</span> <span style=color:#000>optionalString4</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#4e9a06>"something"</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>Note that unlike explicit unions, the position of the <code>null</code> type is fluid; it will be the first or last type depending on the default value (if any). So in the example above, all fields are valid.</p><h2 id=defining-rpc-messages>Defining RPC Messages</h2><p>The syntax to define an RPC message within a Avro IDL protocol is similar to the syntax for a method declaration within a C header file or a Java interface. To define an RPC message add which takes two arguments named <em>foo</em> and <em>bar</em>, returning an <em>int</em>, simply include the following definition within the protocol:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#204a87;font-weight:700>int</span> <span style=color:#000>add</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#204a87;font-weight:700>int</span> <span style=color:#000>foo</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#204a87;font-weight:700>int</span> <span style=color:#000>bar</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#0000cf;font-weight:700>0</span><span style=color:#ce5c00;font-weight:700>);</span> |
| </span></span></code></pre></div><p>Message arguments, like record fields, may specify default values.</p><p>To define a message with no response, you may use the alias <em>void</em>, equivalent to the Avro <em>null</em> type:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#204a87;font-weight:700>void</span> <span style=color:#000>logMessage</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#000>string</span> <span style=color:#000>message</span><span style=color:#ce5c00;font-weight:700>);</span> |
| </span></span></code></pre></div><p>If you have previously defined an error type within the same protocol, you may declare that a message can throw this error using the syntax:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#204a87;font-weight:700>void</span> <span style=color:#000>goKaboom</span><span style=color:#ce5c00;font-weight:700>()</span> <span style=color:#204a87;font-weight:700>throws</span> <span style=color:#000>Kaboom</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span></code></pre></div><p>To define a one-way message, use the keyword <code>oneway</code> after the parameter list, for example:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#204a87;font-weight:700>void</span> <span style=color:#000>fireAndForget</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#000>string</span> <span style=color:#000>message</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>oneway</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span></code></pre></div><h2 id=other-language-features>Other Language Features</h2><h3 id=comments>Comments</h3><p>All Java-style comments are supported within a Avro IDL file. Any text following <em>//</em> on a line is ignored, as is any text between <em>/*</em> and <em>*/</em>, possibly spanning multiple lines.</p><p>Comments that begin with <em>/**</em> are used as the documentation string for the type or field definition that follows the comment.</p><h3 id=escaping-identifiers>Escaping Identifiers</h3><p>Occasionally, one will need to use a reserved language keyword as an identifier. In order to do so, backticks (`) may be used to escape the identifier. For example, to define a message with the literal name error, you may write:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#204a87;font-weight:700>void</span> <span style=color:#a40000>`</span><span style=color:#000>error</span><span style=color:#a40000>`</span><span style=color:#ce5c00;font-weight:700>();</span> |
| </span></span></code></pre></div><p>This syntax is allowed anywhere an identifier is expected.</p><h3 id=annotations-for-ordering-and-namespaces>Annotations for Ordering and Namespaces</h3><p>Java-style annotations may be used to add additional properties to types and fields throughout Avro IDL.</p><p>For example, to specify the sort order of a field within a record, one may use the <code>@order</code> annotation before the field name as follows:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>MyRecord</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#5c35cc;font-weight:700>@order</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"ascending"</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>myAscendingSortField</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#5c35cc;font-weight:700>@order</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"descending"</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>myDescendingField</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#5c35cc;font-weight:700>@order</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"ignore"</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>myIgnoredField</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>A field’s type (with the exception of type references) may also be preceded by annotations, e.g.:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>MyRecord</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#5c35cc;font-weight:700>@java</span><span style=color:#ce5c00;font-weight:700>-</span><span style=color:#000>class</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"java.util.ArrayList"</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>array</span><span style=color:#ce5c00;font-weight:700><</span><span style=color:#000>string</span><span style=color:#ce5c00;font-weight:700>></span> <span style=color:#000>myStrings</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>This can be used to support java classes that can be serialized/deserialized via their <code>toString</code>/<code>String constructor</code>, e.g.:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>MyRecord</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#5c35cc;font-weight:700>@java</span><span style=color:#ce5c00;font-weight:700>-</span><span style=color:#000>class</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"java.math.BigDecimal"</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>string</span> <span style=color:#000>value</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#5c35cc;font-weight:700>@java</span><span style=color:#ce5c00;font-weight:700>-</span><span style=color:#000>key</span><span style=color:#ce5c00;font-weight:700>-</span><span style=color:#000>class</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"java.io.File"</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>map</span><span style=color:#ce5c00;font-weight:700><</span><span style=color:#000>string</span><span style=color:#ce5c00;font-weight:700>></span> <span style=color:#000>fileStates</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>array</span><span style=color:#ce5c00;font-weight:700><</span><span style=color:#5c35cc;font-weight:700>@java</span><span style=color:#ce5c00;font-weight:700>-</span><span style=color:#000>class</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"java.math.BigDecimal"</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>string</span><span style=color:#ce5c00;font-weight:700>></span> <span style=color:#000>weights</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>Similarly, a <code>@namespace</code> annotation may be used to modify the namespace when defining a named schema. For example:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#5c35cc;font-weight:700>@namespace</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"org.apache.avro.firstNamespace"</span><span style=color:#ce5c00;font-weight:700>)</span> |
| </span></span><span style=display:flex><span><span style=color:#000>protocol</span> <span style=color:#000>MyProto</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#5c35cc;font-weight:700>@namespace</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"org.apache.avro.someOtherNamespace"</span><span style=color:#ce5c00;font-weight:700>)</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>record</span> <span style=color:#000>Foo</span> <span style=color:#ce5c00;font-weight:700>{}</span> |
| </span></span><span style=display:flex><span> |
| </span></span><span style=display:flex><span> <span style=color:#000>record</span> <span style=color:#000>Bar</span> <span style=color:#ce5c00;font-weight:700>{}</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>will define a protocol in the <em>firstNamespace</em> namespace. The record <em>Foo</em> will be defined in <em>someOtherNamespace</em> and <em>Bar</em> will be defined in <em>firstNamespace</em> as it inherits its default from its container.</p><p>Type and field aliases are specified with the <code>@aliases</code> annotation as follows:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#5c35cc;font-weight:700>@aliases</span><span style=color:#ce5c00;font-weight:700>([</span><span style=color:#4e9a06>"org.old.OldRecord"</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#4e9a06>"org.ancient.AncientRecord"</span><span style=color:#ce5c00;font-weight:700>])</span> |
| </span></span><span style=display:flex><span><span style=color:#000>record</span> <span style=color:#000>MyRecord</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#5c35cc;font-weight:700>@aliases</span><span style=color:#ce5c00;font-weight:700>([</span><span style=color:#4e9a06>"oldField"</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#4e9a06>"ancientField"</span><span style=color:#ce5c00;font-weight:700>])</span> <span style=color:#000>myNewField</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>Some annotations like those listed above are handled specially. All other annotations are added as properties to the protocol, message, schema or field.</p><h2 id=complete-example>Complete Example</h2><p>The following is an example of an Avro IDL file that shows most of the above features:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#8f5902;font-style:italic>/* |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic>* Header with license information. |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic>*/</span> |
| </span></span><span style=display:flex><span> |
| </span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic>/** |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic> * An example protocol in Avro IDL |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic> */</span> |
| </span></span><span style=display:flex><span><span style=color:#5c35cc;font-weight:700>@namespace</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"org.apache.avro.test"</span><span style=color:#ce5c00;font-weight:700>)</span> |
| </span></span><span style=display:flex><span><span style=color:#000>protocol</span> <span style=color:#000>Simple</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#8f5902;font-style:italic>/** Documentation for the enum type Kind */</span> |
| </span></span><span style=display:flex><span> <span style=color:#5c35cc;font-weight:700>@aliases</span><span style=color:#ce5c00;font-weight:700>([</span><span style=color:#4e9a06>"org.foo.KindOf"</span><span style=color:#ce5c00;font-weight:700>])</span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700>enum</span> <span style=color:#000>Kind</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>FOO</span><span style=color:#ce5c00;font-weight:700>,</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>BAR</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#8f5902;font-style:italic>// the bar enum value |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic></span> <span style=color:#000>BAZ</span> |
| </span></span><span style=display:flex><span> <span style=color:#ce5c00;font-weight:700>}</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#000>FOO</span><span style=color:#ce5c00;font-weight:700>;</span> <span style=color:#8f5902;font-style:italic>// For schema evolution purposes, unmatched values do not throw an error, but are resolved to FOO. |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic></span> |
| </span></span><span style=display:flex><span> <span style=color:#8f5902;font-style:italic>/** MD5 hash; good enough to avoid most collisions, and smaller than (for example) SHA256. */</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>fixed</span> <span style=color:#000>MD5</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#0000cf;font-weight:700>16</span><span style=color:#ce5c00;font-weight:700>);</span> |
| </span></span><span style=display:flex><span> |
| </span></span><span style=display:flex><span> <span style=color:#000>record</span> <span style=color:#000>TestRecord</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#8f5902;font-style:italic>/** Record name; has no intrinsic order */</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#5c35cc;font-weight:700>@order</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"ignore"</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>name</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> |
| </span></span><span style=display:flex><span> <span style=color:#000>Kind</span> <span style=color:#5c35cc;font-weight:700>@order</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#4e9a06>"descending"</span><span style=color:#ce5c00;font-weight:700>)</span> <span style=color:#000>kind</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> |
| </span></span><span style=display:flex><span> <span style=color:#000>MD5</span> <span style=color:#000>hash</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> |
| </span></span><span style=display:flex><span> <span style=color:#8f5902;font-style:italic>/* |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic> Note that 'null' is the first union type. Just like .avsc / .avpr files, the default value must be of the first union type. |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic> */</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>union</span> <span style=color:#ce5c00;font-weight:700>{</span> <span style=color:#204a87;font-weight:700>null</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#000>MD5</span> <span style=color:#ce5c00;font-weight:700>}</span> <span style=color:#8f5902;font-style:italic>/** Optional field */</span> <span style=color:#5c35cc;font-weight:700>@aliases</span><span style=color:#ce5c00;font-weight:700>([</span><span style=color:#4e9a06>"hash"</span><span style=color:#ce5c00;font-weight:700>])</span> <span style=color:#000>nullableHash</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#204a87;font-weight:700>null</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> |
| </span></span><span style=display:flex><span> <span style=color:#000>array</span><span style=color:#ce5c00;font-weight:700><</span><span style=color:#204a87;font-weight:700>long</span><span style=color:#ce5c00;font-weight:700>></span> <span style=color:#000>arrayOfLongs</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span><span style=display:flex><span> |
| </span></span><span style=display:flex><span> <span style=color:#8f5902;font-style:italic>/** Errors are records that can be thrown from a method */</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>error</span> <span style=color:#000>TestError</span> <span style=color:#ce5c00;font-weight:700>{</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#000>message</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span><span style=display:flex><span> |
| </span></span><span style=display:flex><span> <span style=color:#000>string</span> <span style=color:#000>hello</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#000>string</span> <span style=color:#000>greeting</span><span style=color:#ce5c00;font-weight:700>);</span> |
| </span></span><span style=display:flex><span> <span style=color:#8f5902;font-style:italic>/** Return what was given. Demonstrates the use of backticks to name types/fields/messages/parameters after keywords */</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>TestRecord</span> <span style=color:#000>echo</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#000>TestRecord</span> <span style=color:#a40000>`</span><span style=color:#000>record</span><span style=color:#a40000>`</span><span style=color:#ce5c00;font-weight:700>);</span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700>int</span> <span style=color:#000>add</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#204a87;font-weight:700>int</span> <span style=color:#000>arg1</span><span style=color:#ce5c00;font-weight:700>,</span> <span style=color:#204a87;font-weight:700>int</span> <span style=color:#000>arg2</span><span style=color:#ce5c00;font-weight:700>);</span> |
| </span></span><span style=display:flex><span> <span style=color:#000>bytes</span> <span style=color:#000>echoBytes</span><span style=color:#ce5c00;font-weight:700>(</span><span style=color:#000>bytes</span> <span style=color:#000>data</span><span style=color:#ce5c00;font-weight:700>);</span> |
| </span></span><span style=display:flex><span> <span style=color:#204a87;font-weight:700>void</span> <span style=color:#a40000>`</span><span style=color:#000>error</span><span style=color:#a40000>`</span><span style=color:#ce5c00;font-weight:700>()</span> <span style=color:#204a87;font-weight:700>throws</span> <span style=color:#000>TestError</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span> <span style=color:#8f5902;font-style:italic>// The oneway keyword forces the method to return null. |
| </span></span></span><span style=display:flex><span><span style=color:#8f5902;font-style:italic></span> <span style=color:#204a87;font-weight:700>void</span> <span style=color:#000>ping</span><span style=color:#ce5c00;font-weight:700>()</span> <span style=color:#000>oneway</span><span style=color:#ce5c00;font-weight:700>;</span> |
| </span></span><span style=display:flex><span><span style=color:#ce5c00;font-weight:700>}</span> |
| </span></span></code></pre></div><p>Additional examples may be found in the Avro source tree under the <code>src/test/idl/input</code> directory.</p><h2 id=ide-support>IDE support</h2><p>There are several editors and IDEs that support Avro IDL files, usually via plugins.</p><h3 id=jetbrains>JetBrains</h3><p>Apache Avro IDL Schema Support 203.1.2 was released in 9 December 2021.</p><p>Features:</p><ul><li>Syntax Highlighting</li><li>Code Completion</li><li>Code Formatting</li><li>Error Highlighting</li><li>Inspections & quick fixes</li><li>JSON schemas for .avpr and .avsc files</li></ul><p>It’s available via the <a href=https://plugins.jetbrains.com/plugin/15728-apache-avro-idl-schema-support>JetBrains Marketplace</a> |
| and on <a href=https://github.com/opwvhk/avro-schema-support>GitHub</a>.</p><p>The plugin supports almost the all JetBrains products: IntelliJ IDEA, PyCharm, WebStorm, Android Studio, AppCode, GoLand, Rider, CLion, RubyMine, PhpStorm, DataGrip, DataSpell, MPS, Code With Me Guest and JetBrains Client.</p><p>Only JetBrains Gateway does not support this plugin directly. But the backend (JetBrains) IDE that it connects to does.</p><h3 id=eclipse>Eclipse</h3><p>Avroclipse 0.0.11 was released on 4 December 2019.</p><p>Features:</p><ul><li>Syntax Highlighting</li><li>Error Highlighting</li><li>Code Completion</li></ul><p>It is available on the <a href=https://marketplace.eclipse.org/content/avroclipse>Eclipse Marketplace</a> |
| and <a href=https://github.com/dvdkruk/avroclipse>GitHub</a>.</p><h3 id=visual-studio-code>Visual Studio Code</h3><p>avro-idl 0.5.0 was released on 16 June 2021. It provides syntax highlighting.</p><p>It is available on the <a href="https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.avro">VisualStudio Marketplace</a> |
| and <a href=https://github.com/Jason3S/vscode-avro-ext>GitHub</a></p><h3 id=atomio>Atom.io</h3><p>atom-language-avro 0.0.13 was released on 14 August 2015. It provides syntax highlighting.</p><p>It is available as <a href=https://atom.io/packages/atom-language-avro>Atom.io package</a> |
| and <a href=https://github.com/jonesetc/atom-language-avro>GitHub</a></p><h3 id=vim>Vim</h3><p>A <code>.avdl</code> detecting plugin by Gurpreet Atwal on <a href=https://github.com/gurpreetatwal/vim-avro>GitHub</a> (Last change in December 2016)</p><p><a href=https://github.com/apache/avro/blob/master/share/editors/avro-idl.vim>avro-idl.vim</a> in the Avro repository <code>share/editors</code> directory (last change in September 2010)</p><p>Both provide syntax highlighting.</p><div class=section-index></div><div class="text-muted mt-5 pt-3 border-top">Last modified April 13, 2023: <a href=https://github.com/apache/avro/commit/8b181dcaa392cfc9bf9ed903deb586de9878f938>Fix the path for Java javadoc HTMLs (8b181dc)</a></div></div></main></div></div><footer class="bg-dark py-5 row d-print-none"><div class="container-fluid mx-sm-5"><div class=row><div class="col-4 col-sm-3 text-xs-center order-sm-2"><ul class="list-inline mb-0"><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title="User mailing list" aria-label="User mailing list"><a class=text-white target=_blank rel=noopener href=mailto:user@avro.apache.org aria-label="User mailing list"><i class="fa fa-envelope"></i></a></li><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title=Twitter aria-label=Twitter><a class=text-white target=_blank rel=noopener href=https://twitter.com/ApacheAvro aria-label=Twitter><i class="fab fa-twitter"></i></a></li><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title="Stack Overflow" aria-label="Stack Overflow"><a class=text-white target=_blank rel=noopener href=https://stackoverflow.com/questions/tagged/avro aria-label="Stack Overflow"><i class="fab fa-stack-overflow"></i></a></li></ul></div><div class="col-4 col-sm-3 text-right text-xs-center order-sm-3"><ul class="list-inline mb-0"><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title=GitHub aria-label=GitHub><a class=text-white target=_blank rel=noopener href=https://github.com/apache/avro aria-label=GitHub><i class="fab fa-github"></i></a></li><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title=Issues aria-label=Issues><a class=text-white target=_blank rel=noopener href=https://issues.apache.org/jira/projects/AVRO/issues aria-label=Issues><i class="fab fa-jira"></i></a></li><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title="Chat with other project developers at Slack" aria-label="Chat with other project developers at Slack"><a class=text-white target=_blank rel=noopener href=https://the-asf.slack.com/ aria-label="Chat with other project developers at Slack"><i class="fab fa-slack"></i></a></li><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title="Developer mailing list" aria-label="Developer mailing list"><a class=text-white target=_blank rel=noopener href=mailto:dev@avro.apache.org aria-label="Developer mailing list"><i class="fa fa-envelope"></i></a></li></ul></div><div class="col-10 col-sm-3 text-center py-2 order-sm-2"><a href=https://www.apache.org/><small class=text-white>© 2023 The Apache Software Foundation </small></a><small class=text-white>All Rights Reserved</small><p><small class=text-white>Apache Avro, Avro™, Apache®, and the Apache feather logo are either registered trademarks or trademarks of The Apache Software Foundation.</small></p></div><div class="col-5 col-sm-3 order-sm-2"><a href=https://www.apache.org/events/current-event.html><img src=https://www.apache.org/events/current-event-234x60.png></a></div></div></div></footer></div><script src=https://cdn.jsdelivr.net/npm/popper.js@1.16.1/dist/umd/popper.min.js integrity=sha384-9/reFTGAW83EW2RDu2S0VKaIzap3H66lZH81PoYlFhbGU+6BZp6G7niu735Sk7lN crossorigin=anonymous></script> |
| <script src=https://cdn.jsdelivr.net/npm/bootstrap@4.6.1/dist/js/bootstrap.min.js integrity="sha512-UR25UO94eTnCVwjbXozyeVd6ZqpaAE9naiEUBK/A+QDbfSTQFhPGj5lOR6d8tsgbBk84Ggb5A3EkjsOgPRPcKA==" crossorigin=anonymous></script> |
| <script src=/js/tabpane-persist.js></script> |
| <script src=/update-site/js/main.min.b0910468256f44515fad3d1c8b5cf64a439da3abc1acef42ad39b9ceac3ae705.js integrity="sha256-sJEEaCVvRFFfrT0ci1z2SkOdo6vBrO9CrTm5zqw65wU=" crossorigin=anonymous></script> |
| <script src=/js/prism.js></script></body></html> |
