| <!doctype html><html lang=en-US dir=ltr class="docs-wrapper plugin-docs plugin-id-default docs-version-1.1.0 docs-doc-page docs-doc-id-compiler/syntax" data-has-hydrated=false><head><meta charset=UTF-8><meta name=generator content="Docusaurus v3.10.1"><title data-rh=true>Schema IDL | Apache Fory™</title><meta data-rh=true name=viewport content="width=device-width, initial-scale=1.0"/><meta data-rh=true property=og:url content=https://fory.apache.org/docs/1.1.0/compiler/syntax /><meta data-rh=true property=og:locale content=en_US /><meta data-rh=true property=og:locale:alternate content=zh_CN /><meta data-rh=true name=docusaurus_locale content=en-US /><meta data-rh=true name=docsearch:language content=en-US /><meta data-rh=true http-equiv=Content-Security-Policy content="frame-src 'self' https://ghbtns.com/;"/><meta data-rh=true property=og:image content=https://fory.apache.org/img/logo.png /><meta data-rh=true property=og:image:width content=1500 /><meta data-rh=true property=og:image:height content=1500 /><meta data-rh=true name=twitter:card content=summary_large_image /><meta data-rh=true name=twitter:image content=https://fory.apache.org/img/logo.png /><meta data-rh=true name=docusaurus_version content=1.1.0 /><meta data-rh=true name=docusaurus_tag content=docs-default-1.1.0 /><meta data-rh=true name=docsearch:version content=1.1.0 /><meta data-rh=true name=docsearch:docusaurus_tag content=docs-default-1.1.0 /><meta data-rh=true property=og:title content="Schema IDL | Apache Fory™"/><meta data-rh=true name=description content="This document provides the syntax and semantic reference for Fory IDL."/><meta data-rh=true property=og:description content="This document provides the syntax and semantic reference for Fory IDL."/><link data-rh=true rel=icon href=/img/favicon.ico /><link data-rh=true rel=canonical href=https://fory.apache.org/docs/1.1.0/compiler/syntax /><link data-rh=true rel=alternate href=https://fory.apache.org/docs/1.1.0/compiler/syntax hreflang=en-US /><link data-rh=true rel=alternate href=https://fory.apache.org/zh-CN/docs/1.1.0/compiler/syntax hreflang=zh-CN /><link data-rh=true rel=alternate href=https://fory.apache.org/docs/1.1.0/compiler/syntax hreflang=x-default /><script data-rh=true type=application/ld+json>{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://fory.apache.org/docs/1.1.0/compiler/syntax","name":"Schema IDL","position":1}]}</script><link rel=alternate type=application/rss+xml href=/blog/rss.xml title="Apache Fory™ RSS Feed"><link rel=alternate type=application/atom+xml href=/blog/atom.xml title="Apache Fory™ Atom Feed"><script type=text/javascript>"fury.apache.org"===window.location.host&&(window.location.href="https://fory.apache.org"),function(){for(var o=window.location.pathname,a=["guide","introduction","start"],n=0;n<a.length;n++){var t=a[n],i=RegExp("^((?:/[a-z]{2}-[A-Z]{2})?/docs(?:/(?:next|[0-9]+.[0-9]+))?)/docs/"+t+"(/.*)?$"),c=o.match(i);if(c){var r=c[1]+"/"+t+(c[2]||"");window.location.replace(r+window.location.search+window.location.hash);return}}}()</script><link rel=stylesheet href=/assets/css/styles.3a1edaa1.css /><script src=/assets/js/runtime~main.605b11b1.js defer></script><script src=/assets/js/main.283fea4b.js defer></script></head><body><svg style="display: none;"><defs> |
| <symbol id=theme-svg-external-link viewBox="0 0 24 24"><path fill=currentColor d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol> |
| </defs></svg> |
| <script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||"light"),document.documentElement.setAttribute("data-theme-choice",t||"light")}(),function(){try{for(var[t,e]of new URLSearchParams(window.location.search).entries())if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id=__docusaurus><div role=region aria-label="Skip to main content"><a class=skipToContent_fXgn href=#__docusaurus_skipToContent_fallback>Skip to main content</a></div><nav aria-label=Main class="theme-layout-navbar navbar navbar--fixed-top"><div class=navbar__inner><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded=false class="navbar__toggle clean-btn" type=button><svg width=30 height=30 viewBox="0 0 30 30" aria-hidden=true><path stroke=currentColor stroke-linecap=round stroke-miterlimit=10 stroke-width=2 d="M4 7h22M4 15h22M4 23h22"/></svg></button><a class=navbar__brand href=/><div class=navbar__logo><img src=/img/fory-logo-light.png alt="Apache Fory™ Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"/><img src=/img/fory-logo-dark.png alt="Apache Fory™ Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"/></div><b class="navbar__title text--truncate"></b></a><a aria-current=page class="navbar__item navbar__link navbar__link--active" href=/docs/1.1.0/introduction/overview>Docs</a><a class="navbar__item navbar__link" href=/docs/1.1.0/specification/xlang_serialization_spec>Specification</a><a class="navbar__item navbar__link" href=/docs/1.1.0/community/>Community</a><a class="navbar__item navbar__link" href=/user>Users</a><a class="navbar__item navbar__link" href=/download>Download</a><a class="navbar__item navbar__link" href=/blog>Blog</a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link>ASF</a><ul class=dropdown__menu><li><a href=https://www.apache.org/ target=_blank rel="noopener noreferrer" class=dropdown__link>Foundation</a><li><a href=https://www.apache.org/licenses/ target=_blank rel="noopener noreferrer" class=dropdown__link>License</a><li><a href=https://www.apache.org/events/current-event.html target=_blank rel="noopener noreferrer" class=dropdown__link>Events</a><li><a href=https://privacy.apache.org/policies/privacy-policy-public.html target=_blank rel="noopener noreferrer" class=dropdown__link>Privacy</a><li><a href=https://www.apache.org/security/ target=_blank rel="noopener noreferrer" class=dropdown__link>Security</a><li><a href=https://www.apache.org/foundation/sponsorship.html target=_blank rel="noopener noreferrer" class=dropdown__link>Sponsorship</a><li><a href=https://www.apache.org/foundation/thanks.html target=_blank rel="noopener noreferrer" class=dropdown__link>Thanks</a><li><a href=https://www.apache.org/foundation/policies/conduct.html target=_blank rel="noopener noreferrer" class=dropdown__link>Code of Conduct</a></ul></div><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class=navbar__link aria-haspopup=true aria-expanded=false role=button href=/docs/1.1.0/compiler/syntax>1.1.0</a><ul class=dropdown__menu><li><a class=dropdown__link href=/docs/next/compiler/syntax>dev</a><li><a class=dropdown__link href=/docs/compiler/syntax>1.3.0</a><li><a class=dropdown__link href=/docs/1.2.0/compiler/syntax>1.2.0</a><li><a aria-current=page class="dropdown__link dropdown__link--active" href=/docs/1.1.0/compiler/syntax>1.1.0</a><li><a class=dropdown__link href=/docs/1.0.0/compiler/syntax>1.0.0</a><li><a class=dropdown__link href=/docs/0.17/compiler/syntax>0.17</a><li><a class=dropdown__link href=/docs/0.16/compiler/syntax>0.16</a><li><a class=dropdown__link href=/docs/0.15/compiler/syntax>0.15</a><li><a class=dropdown__link href=/docs/0.14/introduction/overview>0.14</a><li><a class=dropdown__link href=/docs/0.13/introduction/overview>0.13</a><li><a class=dropdown__link href=/docs/0.12/introduction/overview>0.12</a><li><a class=dropdown__link href=/docs/0.11/introduction/overview>0.11</a><li><a class=dropdown__link href=/docs/0.10/introduction/overview>0.10</a></ul></div><a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class="navbar__item navbar__link header-github-link" aria-label="GitHub repository"></a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link><svg viewBox="0 0 24 24" width=20 height=20 aria-hidden=true class=iconLanguage_nlXk><path fill=currentColor d="M12.87 15.07l-2.54-2.51.03-.03c1.74-1.94 2.98-4.17 3.71-6.53H17V4h-7V2H8v2H1v1.99h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z"/></svg>English</a><ul class=dropdown__menu><li><a href=/docs/1.1.0/compiler/syntax target=_self rel="noopener noreferrer" class="dropdown__link dropdown__link--active" lang=en-US>English</a><li><a href=/zh-CN/docs/1.1.0/compiler/syntax target=_self rel="noopener noreferrer" class=dropdown__link lang=zh-CN>简体中文</a></ul></div><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type=button disabled title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill=currentColor d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill=currentColor d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill=currentColor d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"/></svg></button></div><div class=navbarSearchContainer_Bca1><div class=navbar__search><span aria-label="expand searchbar" role=button class=search-icon tabindex=0></span><input id=search_input_react type=search placeholder=Loading... aria-label=Search class="navbar__search-input search-bar" disabled/></div></div></div></div><div role=presentation class=navbar-sidebar__backdrop></div></nav><div id=__docusaurus_skipToContent_fallback class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class=docsWrapper_hBAB><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type=button></button><div class=docRoot_UBD9><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class=sidebarViewport_aRkj><div class=sidebar_njMd><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=true href=/docs/1.1.0/introduction/overview><span title=Introduction class=categoryLinkLabel_W154>Introduction</span></a></div><ul class=menu__list><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/introduction/overview><span title=Overview class=linkLabel_WmDU>Overview</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/introduction/features><span title=Features class=linkLabel_WmDU>Features</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/introduction/benchmark><span title=Benchmark class=linkLabel_WmDU>Benchmark</span></a></ul><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=true href=/docs/1.1.0/start/install><span title=Start class=categoryLinkLabel_W154>Start</span></a></div><ul class=menu__list><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/start/install><span title=Install class=linkLabel_WmDU>Install</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/start/usage><span title=Usage class=linkLabel_WmDU>Usage</span></a></ul><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" role=button aria-expanded=true href=/docs/1.1.0/compiler/><span title="Schema IDL & Compiler" class=categoryLinkLabel_W154>Schema IDL & Compiler</span></a></div><ul class=menu__list><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/compiler/><span title=Overview class=linkLabel_WmDU>Overview</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current=page tabindex=0 href=/docs/1.1.0/compiler/syntax><span title="Schema IDL" class=linkLabel_WmDU>Schema IDL</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/compiler/compiler_guide><span title="Compiler Guide" class=linkLabel_WmDU>Compiler Guide</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/compiler/generated_code><span title="Generated Code" class=linkLabel_WmDU>Generated Code</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/compiler/flatbuffers_idl><span title="FlatBuffers IDL Support" class=linkLabel_WmDU>FlatBuffers IDL Support</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/docs/1.1.0/compiler/protobuf_idl_support><span title="Protobuf IDL Support" class=linkLabel_WmDU>Protobuf IDL Support</span></a></ul><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=true href=/docs/1.1.0/guide/java/><span title=Guide class=categoryLinkLabel_W154>Guide</span></a></div><ul class=menu__list><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/java/><span title=Java class=categoryLinkLabel_W154>Java</span></a><button aria-label="Expand sidebar category 'Java'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/python/><span title=Python class=categoryLinkLabel_W154>Python</span></a><button aria-label="Expand sidebar category 'Python'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/rust/><span title=Rust class=categoryLinkLabel_W154>Rust</span></a><button aria-label="Expand sidebar category 'Rust'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/cpp/><span title=C++ class=categoryLinkLabel_W154>C++</span></a><button aria-label="Expand sidebar category 'C++'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/go/><span title=Go class=categoryLinkLabel_W154>Go</span></a><button aria-label="Expand sidebar category 'Go'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/javascript/><span title=JavaScript class=categoryLinkLabel_W154>JavaScript</span></a><button aria-label="Expand sidebar category 'JavaScript'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/csharp/><span title=C# class=categoryLinkLabel_W154>C#</span></a><button aria-label="Expand sidebar category 'C#'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/swift/><span title=Swift class=categoryLinkLabel_W154>Swift</span></a><button aria-label="Expand sidebar category 'Swift'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/dart/><span title=Dart class=categoryLinkLabel_W154>Dart</span></a><button aria-label="Expand sidebar category 'Dart'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/scala/><span title=Scala class=categoryLinkLabel_W154>Scala</span></a><button aria-label="Expand sidebar category 'Scala'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/kotlin/><span title=Kotlin class=categoryLinkLabel_W154>Kotlin</span></a><button aria-label="Expand sidebar category 'Kotlin'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist" tabindex=0 href=/docs/1.1.0/guide/xlang/><span title="Cross Language" class=categoryLinkLabel_W154>Cross Language</span></a><button aria-label="Expand sidebar category 'Cross Language'" aria-expanded=false type=button class="clean-btn menu__caret"></button></div></ul></ul></nav></div></div></aside><main class=docMainContainer_TBSr><div class="container padding-top--md padding-bottom--lg"><div class=row><div class="col docItemCol_VOVn"><div class="theme-doc-version-banner alert alert--warning margin-bottom--md" role=alert><div>This is documentation for <!-- -->Apache Fory™<!-- --> <b>1.1.0</b>, which is no longer actively maintained.</div><div class=margin-top--md>For up-to-date documentation, see the <b><a href=/docs/compiler/syntax>latest version</a></b> (<!-- -->1.3.0<!-- -->).</div></div><div class=docItemContainer_Djhp><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label=Breadcrumbs><ul class=breadcrumbs><li class=breadcrumbs__item><a aria-label="Home page" class=breadcrumbs__link href=/><svg viewBox="0 0 24 24" class=breadcrumbHomeIcon_YNFT><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill=currentColor /></svg></a><li class=breadcrumbs__item><span class=breadcrumbs__link>Schema IDL & Compiler</span><li class="breadcrumbs__item breadcrumbs__item--active"><span class=breadcrumbs__link>Schema IDL</span></ul></nav><span class="theme-doc-version-badge badge badge--secondary">Version: 1.1.0</span><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type=button class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Schema IDL</h1></header><p>This document provides the syntax and semantic reference for Fory IDL.</p> |
| <p>For compiler usage and build integration, see |
| <a class="" href=/docs/1.1.0/compiler/compiler_guide>Compiler Guide</a>. For protobuf/FlatBuffers frontend mapping |
| rules, see <a class="" href=/docs/1.1.0/compiler/protobuf_idl_support>Protocol Buffers IDL Support</a> and |
| <a class="" href=/docs/1.1.0/compiler/flatbuffers_idl>FlatBuffers IDL Support</a>.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=file-structure>File Structure<a href=#file-structure class=hash-link aria-label="Direct link to File Structure" title="Direct link to File Structure" translate=no></a></h2> |
| <p>An Fory IDL file typically consists of:</p> |
| <ol> |
| <li class="">Optional package declaration</li> |
| <li class="">Optional file-level options</li> |
| <li class="">Optional import statements</li> |
| <li class="">Type definitions (enums, messages, and unions)</li> |
| <li class="">Optional service definitions</li> |
| </ol> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// Optional package declaration</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> com</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">example</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">models</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Optional file-level options</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"com.example.models"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Import statements</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"common/types.fdl"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Type definitions</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> Color </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> User </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> OrderRequest </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>102</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Order </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>103</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">union Event </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>104</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Service definitions</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>service</span><span class="token plain"> </span><span class="token class-name">OrderService</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>rpc</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>GetOrder</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">OrderRequest</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>returns</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Order</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=comments>Comments<a href=#comments class=hash-link aria-label="Direct link to Comments" title="Direct link to Comments" translate=no></a></h2> |
| <p>Fory IDL supports both single-line and block comments:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// This is a single-line comment</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>/*</span><br/></div><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic> * This is a block comment</span><br/></div><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic> * that spans multiple lines</span><br/></div><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic> */</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Example</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Inline comment</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=package-declaration>Package Declaration<a href=#package-declaration class=hash-link aria-label="Direct link to Package Declaration" title="Direct link to Package Declaration" translate=no></a></h2> |
| <p>The package declaration defines the namespace for all types in the file.</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> com</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">example</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">models</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>You can optionally specify a package alias used for auto-generated type IDs:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> com</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">example</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">models </span><span class="token positional-class-name class-name">alias</span><span class="token plain"> models_v1</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p><strong>Rules:</strong></p> |
| <ul> |
| <li class="">Optional but recommended</li> |
| <li class="">Must appear before any type definitions</li> |
| <li class="">Only one package declaration per file</li> |
| <li class="">Used for name-based type registration</li> |
| <li class="">Package alias is used for auto-ID hashing</li> |
| </ul> |
| <p><strong>Language Mapping:</strong></p> |
| <table><thead><tr><th>Language<th>Package Usage<tbody><tr><td>Java<td>Java package<tr><td>Python<td>Module name (dots to underscores)<tr><td>Go<td>Package name (last component)<tr><td>Rust<td>Module name (dots to underscores)<tr><td>C++<td>Namespace (dots to <code>::</code>)<tr><td>C#<td>Namespace<tr><td>JavaScript/TypeScript<td>TypeScript module name<tr><td>Swift<td>Namespace wrapper or prefix<tr><td>Dart<td>Library name (package segments)<tr><td>Scala<td>Scala package<tr><td>Kotlin<td>Kotlin package</table> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=file-level-options>File-Level Options<a href=#file-level-options class=hash-link aria-label="Direct link to File-Level Options" title="Direct link to File-Level Options" translate=no></a></h2> |
| <p>Options can be specified at file level to control language-specific code generation.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=syntax>Syntax<a href=#syntax class=hash-link aria-label="Direct link to Syntax" title="Direct link to Syntax" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> option_name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> value</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=java-package-option>Java Package Option<a href=#java-package-option class=hash-link aria-label="Direct link to Java Package Option" title="Direct link to Java Package Option" translate=no></a></h3> |
| <p>Override the Java package for generated code:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"com.mycorp.payment.v1"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Effect:</strong></p> |
| <ul> |
| <li class="">Generated Java files will be in <code>com/mycorp/payment/v1/</code> directory</li> |
| <li class="">Java package declaration will be <code>package com.mycorp.payment.v1;</code></li> |
| <li class="">Type registration still uses the Fory IDL package (<code>payment</code>) for cross-language compatibility</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=go-package-option>Go Package Option<a href=#go-package-option class=hash-link aria-label="Direct link to Go Package Option" title="Direct link to Go Package Option" translate=no></a></h3> |
| <p>Specify the Go import path and package name:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> go_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"github.com/mycorp/apis/gen/payment/v1;paymentv1"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Format:</strong> <code>"import/path;package_name"</code> or just <code>"import/path"</code> (last segment used as package name)</p> |
| <p><strong>Effect:</strong></p> |
| <ul> |
| <li class="">Generated Go files will have <code>package paymentv1</code></li> |
| <li class="">The import path can be used in other Go code</li> |
| <li class="">Type registration still uses the Fory IDL package (<code>payment</code>) for cross-language compatibility</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=c-namespace-option>C# Namespace Option<a href=#c-namespace-option class=hash-link aria-label="Direct link to C# Namespace Option" title="Direct link to C# Namespace Option" translate=no></a></h3> |
| <p>Override the C# namespace for generated code:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> csharp_namespace </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"MyCorp.Payment.V1"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Effect:</strong></p> |
| <ul> |
| <li class="">Generated C# files use <code>namespace MyCorp.Payment.V1;</code></li> |
| <li class="">Output path follows namespace segments (<code>MyCorp/Payment/V1/</code> under <code>--csharp_out</code>)</li> |
| <li class="">Type registration still uses the Fory IDL package (<code>payment</code>) for cross-language compatibility</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=kotlin-package-option>Kotlin Package Option<a href=#kotlin-package-option class=hash-link aria-label="Direct link to Kotlin Package Option" title="Direct link to Kotlin Package Option" translate=no></a></h3> |
| <p>Override the Kotlin package for generated source:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> kotlin_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"com.mycorp.payment.v1"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Effect:</strong></p> |
| <ul> |
| <li class="">Generated Kotlin files are written under <code>com/mycorp/payment/v1/</code></li> |
| <li class="">Kotlin source uses <code>package com.mycorp.payment.v1</code></li> |
| <li class="">Type registration still uses the Fory IDL package (<code>payment</code>) for cross-language compatibility</li> |
| </ul> |
| <p>If <code>kotlin_package</code> is absent, Kotlin uses the FDL package. A Kotlin import |
| graph cannot mix default-package schemas with named Kotlin packages.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=go-nested-type-style-option>Go Nested Type Style Option<a href=#go-nested-type-style-option class=hash-link aria-label="Direct link to Go Nested Type Style Option" title="Direct link to Go Nested Type Style Option" translate=no></a></h3> |
| <p>Control Go naming for nested message/enum/union types:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> go_nested_type_style </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"camelcase"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Envelope</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payload</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Values:</strong></p> |
| <ul> |
| <li class=""><code>underscore</code> (default): <code>Envelope_Payload</code></li> |
| <li class=""><code>camelcase</code>: <code>EnvelopePayload</code></li> |
| </ul> |
| <p>The CLI flag <code>--go_nested_type_style</code> overrides this schema option when both are set.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=swift-namespace-style-option>Swift Namespace Style Option<a href=#swift-namespace-style-option class=hash-link aria-label="Direct link to Swift Namespace Style Option" title="Direct link to Swift Namespace Style Option" translate=no></a></h3> |
| <p>Control how package namespace is reflected in Swift generated type names:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">v1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> swift_namespace_style </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"flatten"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Values:</strong></p> |
| <ul> |
| <li class=""><code>enum</code> (default): namespace wrappers (for example <code>Payment.V1.Payment</code>)</li> |
| <li class=""><code>flatten</code>: package prefix on top-level types (for example <code>Payment_V1_Payment</code>)</li> |
| </ul> |
| <p><strong>Important:</strong> namespace wrapper/prefixing is only applied when package is non-empty. If package is empty, Swift emits top-level types directly for both styles.</p> |
| <p>The CLI flag <code>--swift_namespace_style</code> overrides this schema option when both are set.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=rust-chrono-temporal-types-option>Rust Chrono Temporal Types Option<a href=#rust-chrono-temporal-types-option class=hash-link aria-label="Direct link to Rust Chrono Temporal Types Option" title="Direct link to Rust Chrono Temporal Types Option" translate=no></a></h3> |
| <p>Rust generated code uses Fory's lightweight temporal carrier types by default: |
| <code>fory::Date</code>, <code>fory::Timestamp</code>, and <code>fory::Duration</code>. Set |
| <code>rust_use_chrono_temporal_types</code> when the generated Rust API should expose |
| chrono temporal types instead:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> rust_use_chrono_temporal_types </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Event</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">date</span><span class="token plain"> business_day </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">timestamp</span><span class="token plain"> created_at </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">duration</span><span class="token plain"> timeout </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>With this option, Rust code maps <code>date</code> to <code>chrono::NaiveDate</code>, <code>timestamp</code> to |
| <code>chrono::NaiveDateTime</code>, and <code>duration</code> to <code>chrono::Duration</code>. The Rust crate |
| that compiles the generated code must depend on <code>chrono</code> and enable Fory's |
| <code>chrono</code> feature.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=java-outer-classname-option>Java Outer Classname Option<a href=#java-outer-classname-option class=hash-link aria-label="Direct link to Java Outer Classname Option" title="Direct link to Java Outer Classname Option" translate=no></a></h3> |
| <p>Generate all types as inner classes of a single outer wrapper class:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_outer_classname </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"DescriptorProtos"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> </span><span class="token class-name">Status</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> UNKNOWN </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ACTIVE </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Status</span><span class="token plain"> status </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Effect:</strong></p> |
| <ul> |
| <li class="">Generates a single file <code>DescriptorProtos.java</code> instead of separate files</li> |
| <li class="">All enums and messages become <code>public static</code> inner classes</li> |
| <li class="">The outer class is <code>public final</code> with a private constructor</li> |
| <li class="">Useful for grouping related types together</li> |
| </ul> |
| <p><strong>Generated structure:</strong></p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>final</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">DescriptorProtos</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token class-name">DescriptorProtos</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>static</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> </span><span class="token class-name">Status</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token constant" style=color:#36acaa>UNKNOWN</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token constant" style=color:#36acaa>ACTIVE</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>static</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>class</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token class-name">String</span><span class="token plain"> id</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>private</span><span class="token plain"> </span><span class="token class-name">Status</span><span class="token plain"> status</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// ...</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Combined with java_package:</strong></p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"com.example.proto"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_outer_classname </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"PaymentProtos"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>This generates <code>com/example/proto/PaymentProtos.java</code> with all types as inner classes.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=java-multiple-files-option>Java Multiple Files Option<a href=#java-multiple-files-option class=hash-link aria-label="Direct link to Java Multiple Files Option" title="Direct link to Java Multiple Files Option" translate=no></a></h3> |
| <p>Control whether types are generated in separate files or as inner classes:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_outer_classname </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"PaymentProtos"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_multiple_files </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Receipt</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Behavior:</strong></p> |
| <table><thead><tr><th><code>java_outer_classname</code><th><code>java_multiple_files</code><th>Result<tbody><tr><td>Not set<td>Any<td>Separate files (one per type)<tr><td>Set<td><code>false</code> (default)<td>Single file with all types as inner classes<tr><td>Set<td><code>true</code><td>Separate files (overrides outer class)</table> |
| <p><strong>Effect of <code>java_multiple_files = true</code>:</strong></p> |
| <ul> |
| <li class="">Each top-level enum and message gets its own <code>.java</code> file</li> |
| <li class="">Overrides <code>java_outer_classname</code> behavior</li> |
| <li class="">Useful when you want separate files but still specify an outer class name for other purposes</li> |
| </ul> |
| <p><strong>Example without java_multiple_files (default):</strong></p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_outer_classname </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"PaymentProtos"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Generates: PaymentProtos.java containing Payment and Receipt as inner classes</span><br/></div></code></pre></div></div> |
| <p><strong>Example with java_multiple_files = true:</strong></p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_outer_classname </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"PaymentProtos"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_multiple_files </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Generates: Payment.java, Receipt.java (separate files)</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=multiple-options>Multiple Options<a href=#multiple-options class=hash-link aria-label="Direct link to Multiple Options" title="Direct link to Multiple Options" translate=no></a></h3> |
| <p>Multiple options can be specified:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> payment</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"com.mycorp.payment.v1"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> go_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"github.com/mycorp/apis/gen/payment/v1;paymentv1"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> deprecated </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Payment</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=protobuf-extension-syntax>Protobuf Extension Syntax<a href=#protobuf-extension-syntax class=hash-link aria-label="Direct link to Protobuf Extension Syntax" title="Direct link to Protobuf Extension Syntax" translate=no></a></h3> |
| <p>In <code>.fdl</code> files, use native Fory IDL syntax only (for example, <code>[id=100]</code>, <code>ref</code>, |
| <code>optional</code>, <code>nullable=true</code>).</p> |
| <p>Protobuf extension syntax with <code>(fory).</code> is for <code>.proto</code> files and the protobuf |
| frontend only.</p> |
| <p>For protobuf extension options, see |
| <a class="" href=/docs/1.1.0/compiler/protobuf_idl_support#fory-extension-options-protobuf>Protocol Buffers IDL Support</a>.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=option-priority>Option Priority<a href=#option-priority class=hash-link aria-label="Direct link to Option Priority" title="Direct link to Option Priority" translate=no></a></h3> |
| <p>For language-specific packages/namespaces:</p> |
| <ol> |
| <li class="">Language-specific option (<code>java_package</code>, <code>go_package</code>, <code>csharp_namespace</code>, |
| <code>kotlin_package</code>)</li> |
| <li class="">Fory IDL package declaration (fallback)</li> |
| </ol> |
| <p><strong>Example:</strong></p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> myapp</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">models</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"com.example.generated"</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <table><thead><tr><th>Scenario<th>Java Package Used<tbody><tr><td><code>java_package</code> present<td><code>com.example.generated</code><tr><td>No <code>java_package</code><td><code>myapp.models</code> (fallback)</table> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=cross-language-type-registration>Cross-Language Type Registration<a href=#cross-language-type-registration class=hash-link aria-label="Direct link to Cross-Language Type Registration" title="Direct link to Cross-Language Type Registration" translate=no></a></h3> |
| <p>Language-specific options only affect where code is generated, not the type namespace used for serialization. This ensures cross-language compatibility:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> myapp</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">models</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> java_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"com.mycorp.generated"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>option</span><span class="token plain"> go_package </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"github.com/mycorp/gen;genmodels"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>All languages will register <code>User</code> with namespace <code>myapp.models</code>, enabling:</p> |
| <ul> |
| <li class="">Java serialized data → Go deserialization</li> |
| <li class="">Go serialized data → Java deserialization</li> |
| <li class="">Any language combination works seamlessly</li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=import-statement>Import Statement<a href=#import-statement class=hash-link aria-label="Direct link to Import Statement" title="Direct link to Import Statement" translate=no></a></h2> |
| <p>Import statements allow you to use types defined in other Fory IDL files.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=basic-syntax>Basic Syntax<a href=#basic-syntax class=hash-link aria-label="Direct link to Basic Syntax" title="Direct link to Basic Syntax" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"path/to/file.fdl"</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=multiple-imports>Multiple Imports<a href=#multiple-imports class=hash-link aria-label="Direct link to Multiple Imports" title="Direct link to Multiple Imports" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"common/types.fdl"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"common/enums.fdl"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"models/address.fdl"</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=path-resolution>Path Resolution<a href=#path-resolution class=hash-link aria-label="Direct link to Path Resolution" title="Direct link to Path Resolution" translate=no></a></h3> |
| <p>Import paths are resolved relative to the importing file:</p> |
| <div class="language-text codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-text codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">project/</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">├── common/</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">│ └── types.fdl</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">├── models/</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">│ ├── user.fdl # import "../common/types.fdl"</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">│ └── order.fdl # import "../common/types.fdl"</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">└── main.fdl # import "common/types.fdl"</span><br/></div></code></pre></div></div> |
| <p><strong>Rules:</strong></p> |
| <ul> |
| <li class="">Import paths are quoted strings (double or single quotes)</li> |
| <li class="">Paths are resolved relative to the importing file's directory</li> |
| <li class="">Imported types become available as if defined in the current file</li> |
| <li class="">Circular imports are detected and reported as errors</li> |
| <li class="">Transitive imports work (if A imports B and B imports C, A has access to C's types)</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=complete-example>Complete Example<a href=#complete-example class=hash-link aria-label="Direct link to Complete Example" title="Direct link to Complete Example" translate=no></a></h3> |
| <p><strong>common/types.fdl:</strong></p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> common</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> Status </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> PENDING </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ACTIVE </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> COMPLETED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Address </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> street </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> city </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> country </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>models/user.fdl:</strong></p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> models</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"../common/types.fdl"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> User </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>200</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Address</span><span class="token plain"> home_address </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Uses imported type</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Status</span><span class="token plain"> status </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Uses imported enum</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=unsupported-import-syntax>Unsupported Import Syntax<a href=#unsupported-import-syntax class=hash-link aria-label="Direct link to Unsupported Import Syntax" title="Direct link to Unsupported Import Syntax" translate=no></a></h3> |
| <p>The following protobuf import modifiers are <strong>not supported</strong>:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// NOT SUPPORTED - will produce an error</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>public</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"other.fdl"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>import</span><span class="token plain"> weak </span><span class="token string" style=color:#e3116c>"other.fdl"</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p><strong><code>import public</code></strong>: Fory IDL uses a simpler import model. All imported types are available to the importing file only. Re-exporting is not supported. Import each file directly where needed.</p> |
| <p><strong><code>import weak</code></strong>: Fory IDL requires all imports to be present at compile time. Optional dependencies are not supported.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=import-errors>Import Errors<a href=#import-errors class=hash-link aria-label="Direct link to Import Errors" title="Direct link to Import Errors" translate=no></a></h3> |
| <p>The compiler reports errors for:</p> |
| <ul> |
| <li class=""><strong>File not found</strong>: The imported file doesn't exist</li> |
| <li class=""><strong>Circular import</strong>: A imports B which imports A (directly or indirectly)</li> |
| <li class=""><strong>Parse errors</strong>: Syntax errors in imported files</li> |
| <li class=""><strong>Unsupported syntax</strong>: <code>import public</code> or <code>import weak</code></li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=enum-definition>Enum Definition<a href=#enum-definition class=hash-link aria-label="Direct link to Enum Definition" title="Direct link to Enum Definition" translate=no></a></h2> |
| <p>Enums define a set of named integer constants.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=basic-syntax-1>Basic Syntax<a href=#basic-syntax-1 class=hash-link aria-label="Direct link to Basic Syntax" title="Direct link to Basic Syntax" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> </span><span class="token class-name">Status</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> PENDING </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ACTIVE </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> COMPLETED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=with-explicit-type-id>With Explicit Type ID<a href=#with-explicit-type-id class=hash-link aria-label="Direct link to With Explicit Type ID" title="Direct link to With Explicit Type ID" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> Status </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> PENDING </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ACTIVE </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> COMPLETED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=reserved-values>Reserved Values<a href=#reserved-values class=hash-link aria-label="Direct link to Reserved Values" title="Direct link to Reserved Values" translate=no></a></h3> |
| <p>Reserve field numbers or names to prevent reuse:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> </span><span class="token class-name">Status</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>reserved</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>15</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>9</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>to</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>11</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>40</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>to</span><span class="token plain"> max</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reserved numbers</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>reserved</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"OLD_STATUS"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"DEPRECATED"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reserved names</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> PENDING </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ACTIVE </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> COMPLETED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=enum-type-options>Enum Type Options<a href=#enum-type-options class=hash-link aria-label="Direct link to Enum Type Options" title="Direct link to Enum Type Options" translate=no></a></h3> |
| <p>Enum-level options are declared inline in <code>[]</code> after the enum name:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> Status </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">deprecated</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> PENDING </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ACTIVE </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>FDL does not support <code>option ...;</code> statements inside enum bodies.</p> |
| <p><strong>Unsupported:</strong></p> |
| <ul> |
| <li class=""><code>allow_alias</code> is <strong>not supported</strong>. Each enum value must have a unique integer.</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=language-mapping>Language Mapping<a href=#language-mapping class=hash-link aria-label="Direct link to Language Mapping" title="Direct link to Language Mapping" translate=no></a></h3> |
| <table><thead><tr><th>Language<th>Implementation<tbody><tr><td>Java<td><code>enum Status { UNKNOWN, ACTIVE, ... }</code><tr><td>Python<td><code>class Status(IntEnum): UNKNOWN = 0</code><tr><td>Go<td><code>type Status int32</code> with constants<tr><td>Rust<td><code>#[repr(i32)] enum Status { Unknown }</code><tr><td>C++<td><code>enum class Status : int32_t { ... }</code><tr><td>C#<td><code>enum Status { Unknown, Active, ... }</code><tr><td>JavaScript/TypeScript<td><code>export enum Status { UNKNOWN, ... }</code><tr><td>Swift<td><code>enum Status</code> with stable IDs<tr><td>Dart<td><code>enum Status { unknown, active, ... }</code><tr><td>Scala<td>Scala 3 <code>enum Status</code><tr><td>Kotlin<td><code>enum class Status</code></table> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=enum-prefix-stripping>Enum Prefix Stripping<a href=#enum-prefix-stripping class=hash-link aria-label="Direct link to Enum Prefix Stripping" title="Direct link to Enum Prefix Stripping" translate=no></a></h3> |
| <p>When enum values use a protobuf-style prefix (enum name in UPPER_SNAKE_CASE), the compiler automatically strips the prefix for languages with scoped enums:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// Input with prefix</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> </span><span class="token class-name">DeviceTier</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> DEVICE_TIER_UNKNOWN </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> DEVICE_TIER_TIER1 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> DEVICE_TIER_TIER2 </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Generated code:</strong></p> |
| <table><thead><tr><th>Language<th>Output<th>Style<tbody><tr><td>Java<td><code>UNKNOWN, TIER1, TIER2</code><td>Scoped enum<tr><td>Rust<td><code>Unknown, Tier1, Tier2</code><td>Scoped enum<tr><td>C++<td><code>UNKNOWN, TIER1, TIER2</code><td>Scoped enum<tr><td>Python<td><code>UNKNOWN, TIER1, TIER2</code><td>Scoped IntEnum<tr><td>Go<td><code>DeviceTierUnknown, DeviceTierTier1, ...</code><td>Unscoped const<tr><td>JavaScript/TypeScript<td><code>UNKNOWN, TIER1, TIER2</code><td>Scoped enum<tr><td>C#<td><code>Unknown, Tier1, Tier2</code><td>Scoped enum<tr><td>Swift<td><code>unknown, tier1, tier2</code><td>Scoped enum<tr><td>Dart<td><code>unknown, tier1, tier2</code><td>Scoped enum<tr><td>Scala<td><code>Unknown, Tier1, Tier2</code><td>Scoped enum<tr><td>Kotlin<td><code>UNKNOWN, TIER1, TIER2</code><td>Scoped enum</table> |
| <p><strong>Note:</strong> The prefix is only stripped if the remainder is a valid identifier. For example, <code>DEVICE_TIER_1</code> is kept unchanged because <code>1</code> is not a valid identifier name.</p> |
| <p><strong>Grammar:</strong></p> |
| <div class="language-text codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-text codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">enum_def := 'enum' IDENTIFIER [type_options] '{' enum_body '}'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">type_options := '[' type_option (',' type_option)* ']'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">type_option := IDENTIFIER '=' option_value</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">enum_body := (reserved_stmt | enum_value)*</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">reserved_stmt := 'reserved' reserved_items ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">enum_value := IDENTIFIER '=' INTEGER ';'</span><br/></div></code></pre></div></div> |
| <p><strong>Rules:</strong></p> |
| <ul> |
| <li class="">Enum names must be unique within the file</li> |
| <li class="">Enum values must have explicit integer assignments</li> |
| <li class="">Value integers must be unique within the enum (no aliases)</li> |
| <li class="">Type ID (<code>[id=100]</code>) is optional for enums but recommended for cross-language use</li> |
| </ul> |
| <p><strong>Example with All Features:</strong></p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// HTTP status code categories</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> HttpCategory </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>200</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>reserved</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>10</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>to</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>20</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reserved for future use</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>reserved</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"UNKNOWN"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reserved name</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> INFORMATIONAL </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> SUCCESS </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> REDIRECTION </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> CLIENT_ERROR </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> SERVER_ERROR </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>5</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=message-definition>Message Definition<a href=#message-definition class=hash-link aria-label="Direct link to Message Definition" title="Direct link to Message Definition" translate=no></a></h2> |
| <p>Messages define structured data types with typed fields.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=basic-syntax-2>Basic Syntax<a href=#basic-syntax-2 class=hash-link aria-label="Direct link to Basic Syntax" title="Direct link to Basic Syntax" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Person</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">int32</span><span class="token plain"> age </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=with-explicit-type-id-1>With Explicit Type ID<a href=#with-explicit-type-id-1 class=hash-link aria-label="Direct link to With Explicit Type ID" title="Direct link to With Explicit Type ID" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Person </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">int32</span><span class="token plain"> age </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=without-explicit-type-id>Without Explicit Type ID<a href=#without-explicit-type-id class=hash-link aria-label="Direct link to Without Explicit Type ID" title="Direct link to Without Explicit Type ID" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Person</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Auto-generated when enable_auto_type_id = true</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">int32</span><span class="token plain"> age </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=language-mapping-1>Language Mapping<a href=#language-mapping-1 class=hash-link aria-label="Direct link to Language Mapping" title="Direct link to Language Mapping" translate=no></a></h3> |
| <table><thead><tr><th>Language<th>Implementation<tbody><tr><td>Java<td>POJO class with getters/setters<tr><td>Python<td><code>@dataclass</code> class<tr><td>Go<td>Struct with exported fields<tr><td>Rust<td>Struct with <code>#[derive(ForyStruct)]</code><tr><td>C++<td>Struct with <code>FORY_STRUCT</code> macro<tr><td>C#<td><code>[ForyStruct]</code> class<tr><td>JavaScript/TypeScript<td><code>export interface</code> declaration<tr><td>Swift<td><code>@ForyStruct</code> struct or class<tr><td>Dart<td><code>@ForyStruct</code> <code>final class</code><tr><td>Scala<td>Scala 3 <code>case class</code> or class<tr><td>Kotlin<td><code>data class</code> or class</table> |
| <p>Type IDs control cross-language registration for messages, unions, and enums. See |
| <a href=#type-ids class="">Type IDs</a> for auto-generation, aliases, and collision handling.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=reserved-fields>Reserved Fields<a href=#reserved-fields class=hash-link aria-label="Direct link to Reserved Fields" title="Direct link to Reserved Fields" translate=no></a></h3> |
| <p>Reserve field numbers or names to prevent reuse after removing fields:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>reserved</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>15</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>9</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>to</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>11</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reserved field numbers</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>reserved</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"old_field"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"temp"</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reserved field names</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=message-type-options>Message Type Options<a href=#message-type-options class=hash-link aria-label="Direct link to Message Type Options" title="Direct link to Message Type Options" translate=no></a></h3> |
| <p>Message-level options are declared inline in <code>[]</code> after the message name:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> User </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">deprecated</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>FDL does not support <code>option ...;</code> statements inside message or enum bodies.</p> |
| <p><strong>Grammar:</strong></p> |
| <div class="language-text codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-text codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">message_def := 'message' IDENTIFIER [type_options] '{' message_body '}'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">type_options := '[' type_option (',' type_option)* ']'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">type_option := IDENTIFIER '=' option_value</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">message_body := (reserved_stmt | nested_type | field_def)*</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">nested_type := enum_def | message_def | union_def</span><br/></div></code></pre></div></div> |
| <p><strong>Rules:</strong></p> |
| <ul> |
| <li class="">Type IDs follow the rules in <a href=#type-ids class="">Type IDs</a>.</li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=nested-types>Nested Types<a href=#nested-types class=hash-link aria-label="Direct link to Nested Types" title="Direct link to Nested Types" translate=no></a></h2> |
| <p>Messages can contain nested message, enum, and union definitions. This is useful for defining types that are closely related to their parent message.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=nested-messages>Nested Messages<a href=#nested-messages class=hash-link aria-label="Direct link to Nested Messages" title="Direct link to Nested Messages" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">SearchResponse</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Result</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> url </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> title </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token builtin">string</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> snippets </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token plain">Result</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> results </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=nested-enums>Nested Enums<a href=#nested-enums class=hash-link aria-label="Direct link to Nested Enums" title="Direct link to Nested Enums" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Container</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> </span><span class="token class-name">Status</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> STATUS_UNKNOWN </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> STATUS_ACTIVE </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> STATUS_INACTIVE </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Status</span><span class="token plain"> status </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=qualified-type-names>Qualified Type Names<a href=#qualified-type-names class=hash-link aria-label="Direct link to Qualified Type Names" title="Direct link to Qualified Type Names" translate=no></a></h3> |
| <p>Nested types can be referenced from other messages using qualified names (Parent.Child):</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">SearchResponse</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Result</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> url </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> title </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">SearchResultCache</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reference nested type with qualified name</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">SearchResponse</span><span class="token positional-class-name class-name punctuation" style=color:#393A34>.</span><span class="token positional-class-name class-name">Result</span><span class="token plain"> cached_result </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token plain">SearchResponse</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">Result</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> all_results </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=deeply-nested-types>Deeply Nested Types<a href=#deeply-nested-types class=hash-link aria-label="Direct link to Deeply Nested Types" title="Direct link to Deeply Nested Types" translate=no></a></h3> |
| <p>Nesting can be multiple levels deep:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Outer</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Middle</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Inner</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Inner</span><span class="token plain"> inner </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Middle</span><span class="token plain"> middle </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">OtherMessage</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reference deeply nested type</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Outer</span><span class="token positional-class-name class-name punctuation" style=color:#393A34>.</span><span class="token positional-class-name class-name">Middle</span><span class="token positional-class-name class-name punctuation" style=color:#393A34>.</span><span class="token positional-class-name class-name">Inner</span><span class="token plain"> deep_ref </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=language-specific-generation>Language-Specific Generation<a href=#language-specific-generation class=hash-link aria-label="Direct link to Language-Specific Generation" title="Direct link to Language-Specific Generation" translate=no></a></h3> |
| <table><thead><tr><th>Language<th>Nested Type Generation<tbody><tr><td>Java<td>Static inner classes (<code>SearchResponse.Result</code>)<tr><td>Python<td>Nested classes within dataclass<tr><td>Go<td>Flat structs with underscore (<code>SearchResponse_Result</code>, configurable to camelcase)<tr><td>Rust<td>Nested modules (<code>search_response::Result</code>)<tr><td>C++<td>Nested classes (<code>SearchResponse::Result</code>)<tr><td>C#<td>Nested classes (<code>SearchResponse.Result</code>)<tr><td>JavaScript/TypeScript<td>Flat names (<code>Result</code>)<tr><td>Swift<td>Nested namespace wrappers or flattened names<tr><td>Dart<td>Flat classes with underscore (<code>SearchResponse_Result</code>)<tr><td>Scala<td>Nested companion/object scope<tr><td>Kotlin<td>Flat generated names</table> |
| <p><strong>Note:</strong> Go defaults to underscore-separated nested names; set <code>option go_nested_type_style = "camelcase";</code> to use concatenated names. Rust emits nested modules for nested types.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=nested-type-rules>Nested Type Rules<a href=#nested-type-rules class=hash-link aria-label="Direct link to Nested Type Rules" title="Direct link to Nested Type Rules" translate=no></a></h3> |
| <ul> |
| <li class="">Nested type names must be unique within their parent message</li> |
| <li class="">Nested types can have their own type IDs</li> |
| <li class="">Numeric type IDs must be globally unique (including nested types); see <a href=#type-ids class="">Type IDs</a> |
| for auto-generation and collision handling</li> |
| <li class="">Within a message, you can reference nested types by simple name</li> |
| <li class="">From outside, use the qualified name (Parent.Child)</li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=union-definition>Union Definition<a href=#union-definition class=hash-link aria-label="Direct link to Union Definition" title="Direct link to Union Definition" translate=no></a></h2> |
| <p>Unions define a value that can hold exactly one of several case types.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=basic-syntax-3>Basic Syntax<a href=#basic-syntax-3 class=hash-link aria-label="Direct link to Basic Syntax" title="Direct link to Basic Syntax" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">union Animal </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>106</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Dog</span><span class="token plain"> dog </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Cat</span><span class="token plain"> cat </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=using-a-union-in-a-message>Using a Union in a Message<a href=#using-a-union-in-a-message class=hash-link aria-label="Direct link to Using a Union in a Message" title="Direct link to Using a Union in a Message" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Person </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Animal</span><span class="token plain"> pet </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> </span><span class="token positional-class-name class-name">Animal</span><span class="token plain"> favorite_pet </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=rules>Rules<a href=#rules class=hash-link aria-label="Direct link to Rules" title="Direct link to Rules" translate=no></a></h3> |
| <ul> |
| <li class="">Case IDs must be non-negative and unique within the union</li> |
| <li class="">Runtime unknown-case markers only select the carrier and do not add entries to |
| the schema case table</li> |
| <li class="">Cases cannot be <code>optional</code> or <code>ref</code></li> |
| <li class="">Union cases support field options for payload metadata, such as scalar encoding |
| and collection element metadata</li> |
| <li class="">Case types can be primitives, enums, messages, or other named types</li> |
| <li class="">Union type IDs follow the rules in <a href=#type-ids class="">Type IDs</a>.</li> |
| </ul> |
| <p><strong>Grammar:</strong></p> |
| <div class="language-text codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-text codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">union_def := 'union' IDENTIFIER [type_options] '{' union_field* '}'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">union_field := ['repeated'] field_type IDENTIFIER '=' INTEGER [field_options] ';'</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=service-definition>Service Definition<a href=#service-definition class=hash-link aria-label="Direct link to Service Definition" title="Direct link to Service Definition" translate=no></a></h2> |
| <p>Services define RPC method contracts in Fory IDL. They are optional: schemas |
| with services still generate the normal data model types, and gRPC service code |
| is generated only when the compiler is run with <code>--grpc</code> for Java or Python.</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> GetPetRequest </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>200</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> PetRecord </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>201</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Animal</span><span class="token plain"> animal </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>service</span><span class="token plain"> </span><span class="token class-name">PetDirectory</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>rpc</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>GetPet</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">GetPetRequest</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>returns</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">PetRecord</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>rpc</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>Classify</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Animal</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>returns</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">Animal</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>The first method uses message request and response types. The second method uses |
| a direct union request and response type, which is supported in Fory IDL.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=streaming-rpcs>Streaming RPCs<a href=#streaming-rpcs class=hash-link aria-label="Direct link to Streaming RPCs" title="Direct link to Streaming RPCs" translate=no></a></h3> |
| <p>Use <code>stream</code> before the request type, the response type, or both:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>service</span><span class="token plain"> </span><span class="token class-name">PetDirectory</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>rpc</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>GetPet</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">GetPetRequest</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>returns</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">PetRecord</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// unary</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>rpc</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>WatchPets</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">GetPetRequest</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>returns</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>stream</span><span class="token plain"> </span><span class="token class-name">PetRecord</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// server streaming</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>rpc</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>ImportPets</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>stream</span><span class="token plain"> </span><span class="token class-name">PetRecord</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>returns</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token class-name">PetRecord</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// client streaming</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>rpc</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>ChatPets</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>stream</span><span class="token plain"> </span><span class="token class-name">Animal</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>returns</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>stream</span><span class="token plain"> </span><span class="token class-name">Animal</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// bidirectional streaming</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=rpc-type-rules>RPC Type Rules<a href=#rpc-type-rules class=hash-link aria-label="Direct link to RPC Type Rules" title="Direct link to RPC Type Rules" translate=no></a></h3> |
| <ul> |
| <li class="">Request and response types must reference named message or union types.</li> |
| <li class="">Enum, primitive, collection, map, and array types are not valid direct RPC |
| request or response types. Wrap those values in a message when they are part |
| of a service contract.</li> |
| <li class="">The generated Java and Python gRPC companions use Fory serialization for each |
| RPC payload. Applications that compile or run those companions provide their |
| own grpc-java or <code>grpcio</code> dependency.</li> |
| </ul> |
| <p><strong>Grammar:</strong></p> |
| <div class="language-text codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-text codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">service_def := 'service' IDENTIFIER '{' rpc_method* '}'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">rpc_method := 'rpc' IDENTIFIER '(' ['stream'] named_type ')'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> 'returns' '(' ['stream'] named_type ')' ';'</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=field-definition>Field Definition<a href=#field-definition class=hash-link aria-label="Direct link to Field Definition" title="Direct link to Field Definition" translate=no></a></h2> |
| <p>Fields define the properties of a message.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=basic-syntax-4>Basic Syntax<a href=#basic-syntax-4 class=hash-link aria-label="Direct link to Basic Syntax" title="Direct link to Basic Syntax" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token positional-class-name class-name">field_type</span><span class="token plain"> field_name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> field_number</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=with-modifiers>With Modifiers<a href=#with-modifiers class=hash-link aria-label="Direct link to With Modifiers" title="Direct link to With Modifiers" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token builtin">string</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> tags </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Nullable list</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">list</span><span class="token operator" style=color:#393A34><</span><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> </span><span class="token builtin">string</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> tags </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Elements may be null</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">list</span><span class="token operator" style=color:#393A34><</span><span class="token plain">ref Node</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> nodes </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Elements tracked as references</span><br/></div></code></pre></div></div> |
| <p><strong>Grammar:</strong></p> |
| <div class="language-text codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-text codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">field_def := [modifiers] field_type IDENTIFIER '=' INTEGER ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">modifiers := { 'optional' | 'ref' }</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">field_type := primitive_type | named_type | list_type | array_type | map_type</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">list_type := 'list' '<' { 'optional' | 'ref' | scalar_encoding } field_type '>'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">array_type := 'array' '<' array_element_type '>'</span><br/></div></code></pre></div></div> |
| <p><code>optional</code> before <code>list</code> applies to the collection field. <code>ref</code> is only valid |
| for named message/union fields; for collection contents, use <code>list<ref T></code> or |
| <code>map<K, ref V></code>. <code>repeated</code> is accepted as an alias for <code>list</code>.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=field-modifiers>Field Modifiers<a href=#field-modifiers class=hash-link aria-label="Direct link to Field Modifiers" title="Direct link to Field Modifiers" translate=no></a></h3> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=optional><code>optional</code><a href=#optional class=hash-link aria-label="Direct link to optional" title="Direct link to optional" translate=no></a></h4> |
| <p>Marks the field as nullable:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Required, non-null</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> email </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Nullable</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Generated Code:</strong></p> |
| <table><thead><tr><th>Language<th>Non-optional<th>Optional<tbody><tr><td>Java<td><code>String name</code><td><code>@Nullable String email</code><tr><td>Python<td><code>name: str</code><td><code>name: Optional[str]</code><tr><td>Go<td><code>Name string</code><td><code>Name *string</code><tr><td>Rust<td><code>name: String</code><td><code>name: Option<String></code><tr><td>C++<td><code>std::string name</code><td><code>std::optional<std::string> name</code><tr><td>C#<td><code>string name</code><td><code>string? email</code><tr><td>JavaScript/TypeScript<td><code>name: string</code><td><code>name?: string | null</code><tr><td>Swift<td><code>String name</code><td><code>String? email</code><tr><td>Dart<td><code>String name</code><td><code>String? email</code><tr><td>Scala<td><code>name: String</code><td><code>email: Option[String]</code><tr><td>Kotlin<td><code>name: String</code><td><code>email: String?</code></table> |
| <p><strong>Default Values:</strong></p> |
| <table><thead><tr><th>Type<th>Default Value<tbody><tr><td>Non-optional types<td>Language default<tr><td>Optional types<td><code>null</code>/<code>None</code>/<code>nil</code></table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=ref><code>ref</code><a href=#ref class=hash-link aria-label="Direct link to ref" title="Direct link to ref" translate=no></a></h4> |
| <p>Enables reference tracking for shared/circular references:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Node</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> value </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ref </span><span class="token positional-class-name class-name">Node</span><span class="token plain"> parent </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Can point to shared object</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token plain">ref Node</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> children </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Use Cases:</strong></p> |
| <ul> |
| <li class="">Shared objects (same object referenced multiple times)</li> |
| <li class="">Circular references (object graphs with cycles)</li> |
| <li class="">Tree structures with parent pointers</li> |
| </ul> |
| <p><strong>Generated Code:</strong></p> |
| <table><thead><tr><th>Language<th>Without <code>ref</code><th>With <code>ref</code><tbody><tr><td>Java<td><code>Node parent</code><td><code>Node parent</code> with <code>@Ref</code><tr><td>Python<td><code>parent: Node</code><td><code>parent: Node = pyfory.field(ref=True)</code><tr><td>Go<td><code>Parent Node</code><td><code>Parent *Node</code> with <code>fory:"ref"</code><tr><td>Rust<td><code>parent: Node</code><td><code>parent: Rc<Node></code><tr><td>C++<td><code>Node parent</code><td><code>std::shared_ptr<Node> parent</code><tr><td>C#<td><code>Node parent</code><td><code>Node? parent</code> with runtime ref tracking<tr><td>JavaScript/TypeScript<td><code>parent: Node</code><td><code>parent: Node</code> (no ref distinction)<tr><td>Swift<td><code>Node parent</code><td>class reference with runtime ref tracking<tr><td>Dart<td><code>Node parent</code><td><code>Node parent</code> with <code>@ForyField(ref: true)</code><tr><td>Scala<td><code>parent: Node</code><td><code>@Ref parent: Node</code><tr><td>Kotlin<td><code>parent: Node</code><td><code>@Ref parent: Node?</code></table> |
| <p>Rust uses <code>Rc</code> and <code>RcWeak</code> by default for ref-tracked fields. Use |
| <code>ref(thread_safe=true)</code> when the generated Rust type must use <code>Arc</code> or |
| <code>ArcWeak</code> for cross-thread shared ownership. This setting is a Rust codegen |
| carrier choice; it does not change the wire format or make the referenced value |
| itself thread-safe. For protobuf option syntax, see |
| <a class="" href=/docs/1.1.0/compiler/protobuf_idl_support#field-level-options>Protocol Buffers IDL Support</a>.</p> |
| <p>Rust pointer carrier mapping:</p> |
| <table><thead><tr><th>Fory IDL<th>Rust type<tbody><tr><td><code>ref Node parent</code><td><code>Rc<Node></code><tr><td><code>ref(thread_safe=true) Node parent</code><td><code>Arc<Node></code><tr><td><code>ref(weak=true) Node parent</code><td><code>RcWeak<Node></code><tr><td><code>ref(weak=true, thread_safe=true) Node parent</code><td><code>ArcWeak<Node></code></table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=list><code>list</code><a href=#list class=hash-link aria-label="Direct link to list" title="Direct link to list" translate=no></a></h4> |
| <p>Marks the field as an ordered collection:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Document</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token builtin">string</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> tags </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token plain">User</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> authors </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Generated Code:</strong></p> |
| <table><thead><tr><th>Language<th>Type<tbody><tr><td>Java<td><code>List<String></code><tr><td>Python<td><code>List[str]</code><tr><td>Go<td><code>[]string</code><tr><td>Rust<td><code>Vec<String></code><tr><td>C++<td><code>std::vector<std::string></code><tr><td>C#<td><code>List<string></code><tr><td>JavaScript/TypeScript<td><code>string[]</code><tr><td>Swift<td><code>[String]</code><tr><td>Dart<td><code>List<String></code><tr><td>Scala<td><code>List[String]</code><tr><td>Kotlin<td><code>List<String></code></table> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=combining-modifiers>Combining Modifiers<a href=#combining-modifiers class=hash-link aria-label="Direct link to Combining Modifiers" title="Direct link to Combining Modifiers" translate=no></a></h3> |
| <p>Modifiers can be combined:</p> |
| <div class="language-fdl codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-fdl codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">message Example {</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> optional list<string> tags = 1; // Nullable list</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list<optional string> aliases = 2; // Elements may be null</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list<ref Node> children = 3; // Elements tracked as references</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> optional ref User owner = 4; // Nullable tracked reference</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">}</span><br/></div></code></pre></div></div> |
| <p><code>optional</code> before <code>list</code> applies to the field/collection. <code>ref</code> before <code>list</code> or |
| <code>map</code> is invalid; put <code>ref</code> inside the element/value type instead. <code>repeated</code> is |
| accepted as an alias for <code>list</code>.</p> |
| <p><strong>List modifier mapping:</strong></p> |
| <table><thead><tr><th>Fory IDL<th>Java<th>Python<th>Go<th>Rust<th>C++<th>Dart<th>Scala<tbody><tr><td><code>optional list<string></code><td><code>@Nullable List<String></code><td><code>Optional[List[str]]</code><td><code>[]string</code> + <code>nullable</code><td><code>Option<Vec<String>></code><td><code>std::optional<std::vector<std::string>></code><td><code>List<String>?</code><td><code>Option[List[String]]</code><tr><td><code>list<optional string></code><td><code>List<String></code> (nullable elements)<td><code>List[Optional[str]]</code><td><code>[]*string</code><td><code>Vec<Option<String>></code><td><code>std::vector<std::optional<std::string>></code><td><code>List<String?></code><td><code>List[Option[String]]</code><tr><td><code>list<ref User></code><td><code>List<@Ref User></code><td><code>List[User]</code><td><code>[]*User</code> + <code>ref=false</code><td><code>Vec<Rc<User>></code><td><code>std::vector<std::shared_ptr<User>></code><td><code>List<User></code> + <code>@ListField(element: DeclaredType(ref: true))</code><td><code>List[User @Ref]</code></table> |
| <p>Use <code>ref(thread_safe=true)</code> in Fory IDL (or <code>[(fory).thread_safe_pointer = true]</code> in protobuf) |
| to generate <code>Arc</code> instead of <code>Rc</code> in Rust.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=field-numbers>Field Numbers<a href=#field-numbers class=hash-link aria-label="Direct link to Field Numbers" title="Direct link to Field Numbers" translate=no></a></h2> |
| <p>Each field must have a unique positive integer identifier:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Example</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> first </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> second </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> third </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Rules and best practices:</strong></p> |
| <ul> |
| <li class="">Numbers must be unique within a message.</li> |
| <li class="">Numbers must be positive integers.</li> |
| <li class="">Gaps are allowed and are useful when fields are removed.</li> |
| <li class="">Prefer sequential numbering from <code>1</code>.</li> |
| <li class="">Never reuse a removed field number for a different field.</li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=type-system>Type System<a href=#type-system class=hash-link aria-label="Direct link to Type System" title="Direct link to Type System" translate=no></a></h2> |
| <p>Fory IDL provides a cross-language type system for primitives, named types, and |
| collections. Field modifiers (<code>optional</code>, <code>ref</code>) control nullability and |
| reference tracking, while <code>list<T></code> and <code>array<T></code> choose collection schema kind |
| (see <a href=#field-modifiers class="">Field Modifiers</a>).</p> |
| <p>The compact tables in this section show common generated carriers. For the |
| complete 1.0 runtime surface, including C#, Swift, Dart, Scala, and Kotlin, see |
| the <a class="" href=/docs/1.1.0/specification/xlang_type_mapping>xlang type-mapping specification</a>.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=primitive-types>Primitive Types<a href=#primitive-types class=hash-link aria-label="Direct link to Primitive Types" title="Direct link to Primitive Types" translate=no></a></h3> |
| <table><thead><tr><th>Type<th>Description<th>Size<tbody><tr><td><code>bool</code><td>Boolean value<td>1 byte<tr><td><code>int8</code><td>Signed 8-bit integer<td>1 byte<tr><td><code>int16</code><td>Signed 16-bit integer<td>2 bytes<tr><td><code>int32</code><td>Signed 32-bit integer, varint by default<td>4 bytes<tr><td><code>int64</code><td>Signed 64-bit integer, PVL varint by default<td>8 bytes<tr><td><code>uint8</code><td>Unsigned 8-bit integer<td>1 byte<tr><td><code>uint16</code><td>Unsigned 16-bit integer<td>2 bytes<tr><td><code>uint32</code><td>Unsigned 32-bit integer, varint by default<td>4 bytes<tr><td><code>uint64</code><td>Unsigned 64-bit integer, PVL varint by default<td>8 bytes<tr><td><code>float16</code><td>IEEE 754 binary16 floating point<td>2 bytes<tr><td><code>bfloat16</code><td>Brain floating point<td>2 bytes<tr><td><code>float32</code><td>32-bit floating point<td>4 bytes<tr><td><code>float64</code><td>64-bit floating point<td>8 bytes<tr><td><code>string</code><td>UTF-8 string<td>Variable<tr><td><code>bytes</code><td>Binary data<td>Variable<tr><td><code>date</code><td>Calendar date<td>Variable<tr><td><code>timestamp</code><td>Date and time with timezone<td>Variable<tr><td><code>duration</code><td>Duration<td>Variable<tr><td><code>decimal</code><td>Decimal value<td>Variable<tr><td><code>any</code><td>Dynamic value (runtime type)<td>Variable</table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=boolean>Boolean<a href=#boolean class=hash-link aria-label="Direct link to Boolean" title="Direct link to Boolean" translate=no></a></h4> |
| <table><thead><tr><th>Language<th>Type<th>Notes<tbody><tr><td>Java<td><code>boolean</code> / <code>Boolean</code><td>Primitive or boxed<tr><td>Python<td><code>bool</code><td><tr><td>Go<td><code>bool</code><td><tr><td>Rust<td><code>bool</code><td><tr><td>C++<td><code>bool</code><td><tr><td>JavaScript/TypeScript<td><code>boolean</code><td><tr><td>Dart<td><code>bool</code><td></table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=integer-types>Integer Types<a href=#integer-types class=hash-link aria-label="Direct link to Integer Types" title="Direct link to Integer Types" translate=no></a></h4> |
| <p>Fory IDL provides fixed-width signed integers (varint encoding for 32/64-bit by default):</p> |
| <table><thead><tr><th>Fory IDL Type<th>Size<th>Range<tbody><tr><td><code>int8</code><td>8-bit<td>-128 to 127<tr><td><code>int16</code><td>16-bit<td>-32,768 to 32,767<tr><td><code>int32</code><td>32-bit<td>-2^31 to 2^31 - 1<tr><td><code>int64</code><td>64-bit<td>-2^63 to 2^63 - 1</table> |
| <p><strong>Language Mapping (Signed):</strong></p> |
| <table><thead><tr><th>Fory IDL<th>Java<th>Python<th>Go<th>Rust<th>C++<th>JavaScript/TypeScript<th>Dart<tbody><tr><td><code>int8</code><td><code>byte</code><td><code>pyfory.Int8</code><td><code>int8</code><td><code>i8</code><td><code>int8_t</code><td><code>number</code><td><code>int</code><tr><td><code>int16</code><td><code>short</code><td><code>pyfory.Int16</code><td><code>int16</code><td><code>i16</code><td><code>int16_t</code><td><code>number</code><td><code>int</code><tr><td><code>int32</code><td><code>int</code><td><code>pyfory.Int32</code><td><code>int32</code><td><code>i32</code><td><code>int32_t</code><td><code>number</code><td><code>int</code><tr><td><code>int64</code><td><code>long</code><td><code>pyfory.Int64</code><td><code>int64</code><td><code>i64</code><td><code>int64_t</code><td><code>bigint | number</code><td><code>Int64</code></table> |
| <p>Fory IDL provides fixed-width unsigned integers (varint encoding for 32/64-bit by default):</p> |
| <table><thead><tr><th>Fory IDL<th>Size<th>Range<tbody><tr><td><code>uint8</code><td>8-bit<td>0 to 255<tr><td><code>uint16</code><td>16-bit<td>0 to 65,535<tr><td><code>uint32</code><td>32-bit<td>0 to 2^32 - 1<tr><td><code>uint64</code><td>64-bit<td>0 to 2^64 - 1</table> |
| <p><strong>Language Mapping (Unsigned):</strong></p> |
| <table><thead><tr><th>Fory IDL<th>Java<th>Python<th>Go<th>Rust<th>C++<th>JavaScript/TypeScript<th>Dart<tbody><tr><td><code>uint8</code><td><code>short</code><td><code>pyfory.UInt8</code><td><code>uint8</code><td><code>u8</code><td><code>uint8_t</code><td><code>number</code><td><code>int</code><tr><td><code>uint16</code><td><code>int</code><td><code>pyfory.UInt16</code><td><code>uint16</code><td><code>u16</code><td><code>uint16_t</code><td><code>number</code><td><code>int</code><tr><td><code>uint32</code><td><code>long</code><td><code>pyfory.UInt32</code><td><code>uint32</code><td><code>u32</code><td><code>uint32_t</code><td><code>number</code><td><code>int</code><tr><td><code>uint64</code><td><code>long</code><td><code>pyfory.UInt64</code><td><code>uint64</code><td><code>u64</code><td><code>uint64_t</code><td><code>bigint | number</code><td><code>Uint64</code></table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=integer-encoding-modifiers>Integer Encoding Modifiers<a href=#integer-encoding-modifiers class=hash-link aria-label="Direct link to Integer Encoding Modifiers" title="Direct link to Integer Encoding Modifiers" translate=no></a></h4> |
| <p>For 32/64-bit integers, Fory IDL uses variable-length encoding by default. Add a |
| scalar encoding modifier when you need a different wire encoding:</p> |
| <table><thead><tr><th>Modifier<th>Valid types<th>Notes<tbody><tr><td><code>varint</code><td><code>int32</code>, <code>int64</code>, <code>uint32</code>, <code>uint64</code><td>Explicit spelling of default<tr><td><code>fixed</code><td><code>int32</code>, <code>int64</code>, <code>uint32</code>, <code>uint64</code><td>Fixed-width little-endian<tr><td><code>tagged</code><td><code>int64</code>, <code>uint64</code><td>Tagged 64-bit encoding</table> |
| <p>Modifiers are part of the scalar type expression, so they can be used in nested |
| list and map positions:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">fixed </span><span class="token builtin">int32</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">list</span><span class="token operator" style=color:#393A34><</span><span class="token plain">fixed </span><span class="token builtin">int32</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> offsets </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">map</span><span class="token operator" style=color:#393A34><</span><span class="token builtin">string</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> tagged </span><span class="token builtin">uint64</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> counters </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>Underscore spellings for integer encoding are not FDL type names.</p> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=floating-point-types>Floating-Point Types<a href=#floating-point-types class=hash-link aria-label="Direct link to Floating-Point Types" title="Direct link to Floating-Point Types" translate=no></a></h4> |
| <table><thead><tr><th>Fory IDL Type<th>Size<th>Precision<tbody><tr><td><code>float32</code><td>32-bit<td>~7 digits<tr><td><code>float64</code><td>64-bit<td>~15-16 digits</table> |
| <p><strong>Language Mapping:</strong></p> |
| <table><thead><tr><th>Fory IDL<th>Java<th>Python annotation/value<th>Go<th>Rust<th>C++<th>JavaScript/TypeScript<th>Dart<tbody><tr><td><code>float16</code><td><code>Float16</code><td><code>pyfory.Float16</code> / <code>float</code><td><code>float16.Float16</code><td><code>Float16</code><td><code>fory::float16_t</code><td><code>number</code><td><code>double</code><tr><td><code>bfloat16</code><td><code>BFloat16</code><td><code>pyfory.BFloat16</code> / <code>float</code><td><code>bfloat16.BFloat16</code><td><code>BFloat16</code><td><code>fory::bfloat16_t</code><td><code>number</code><td><code>double</code><tr><td><code>float32</code><td><code>float</code><td><code>pyfory.Float32</code><td><code>float32</code><td><code>f32</code><td><code>float</code><td><code>number</code><td><code>Float32</code><tr><td><code>float64</code><td><code>double</code><td><code>pyfory.Float64</code><td><code>float64</code><td><code>f64</code><td><code>double</code><td><code>number</code><td><code>double</code></table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=string-type>String Type<a href=#string-type class=hash-link aria-label="Direct link to String Type" title="Direct link to String Type" translate=no></a></h4> |
| <table><thead><tr><th>Language<th>Type<th>Notes<tbody><tr><td>Java<td><code>String</code><td>Immutable<tr><td>Python<td><code>str</code><td><tr><td>Go<td><code>string</code><td>Immutable<tr><td>Rust<td><code>String</code><td>Owned, heap-allocated<tr><td>C++<td><code>std::string</code><td><tr><td>JavaScript/TypeScript<td><code>string</code><td><tr><td>Dart<td><code>String</code><td></table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=bytes-type>Bytes Type<a href=#bytes-type class=hash-link aria-label="Direct link to Bytes Type" title="Direct link to Bytes Type" translate=no></a></h4> |
| <table><thead><tr><th>Language<th>Type<th>Notes<tbody><tr><td>Java<td><code>byte[]</code><td><tr><td>Python<td><code>bytes</code><td>Immutable<tr><td>Go<td><code>[]byte</code><td><tr><td>Rust<td><code>Vec<u8></code><td><tr><td>C++<td><code>std::vector<uint8_t></code><td><tr><td>JavaScript/TypeScript<td><code>Uint8Array</code><td><tr><td>Dart<td><code>Uint8List</code><td></table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=temporal-types>Temporal Types<a href=#temporal-types class=hash-link aria-label="Direct link to Temporal Types" title="Direct link to Temporal Types" translate=no></a></h4> |
| <h5 class="anchor anchorTargetStickyNavbar_Vzrq" id=date>Date<a href=#date class=hash-link aria-label="Direct link to Date" title="Direct link to Date" translate=no></a></h5> |
| <table><thead><tr><th>Language<th>Type<th>Notes<tbody><tr><td>Java<td><code>java.time.LocalDate</code><td><tr><td>Python<td><code>datetime.date</code><td><tr><td>Go<td><code>time.Time</code><td>Time portion ignored<tr><td>Rust<td><code>fory::Date</code><td>Set <code>rust_use_chrono_temporal_types = true</code> to generate <code>chrono::NaiveDate</code><tr><td>C++<td><code>fory::serialization::Date</code><td><tr><td>JavaScript/TypeScript<td><code>Date</code><td><tr><td>Dart<td><code>LocalDate</code><td>Fory package type</table> |
| <h5 class="anchor anchorTargetStickyNavbar_Vzrq" id=timestamp>Timestamp<a href=#timestamp class=hash-link aria-label="Direct link to Timestamp" title="Direct link to Timestamp" translate=no></a></h5> |
| <table><thead><tr><th>Language<th>Type<th>Notes<tbody><tr><td>Java<td><code>java.time.Instant</code><td>UTC-based<tr><td>Python<td><code>datetime.datetime</code><td><tr><td>Go<td><code>time.Time</code><td><tr><td>Rust<td><code>fory::Timestamp</code><td>Set <code>rust_use_chrono_temporal_types = true</code> to generate <code>chrono::NaiveDateTime</code><tr><td>C++<td><code>fory::serialization::Timestamp</code><td><tr><td>JavaScript/TypeScript<td><code>Date</code><td><tr><td>Dart<td><code>Timestamp</code><td>Fory package type</table> |
| <h5 class="anchor anchorTargetStickyNavbar_Vzrq" id=duration>Duration<a href=#duration class=hash-link aria-label="Direct link to Duration" title="Direct link to Duration" translate=no></a></h5> |
| <table><thead><tr><th>Language<th>Type<th>Notes<tbody><tr><td>Java<td><code>java.time.Duration</code><td><tr><td>Python<td><code>datetime.timedelta</code><td><tr><td>Go<td><code>time.Duration</code><td><tr><td>Rust<td><code>fory::Duration</code><td>Set <code>rust_use_chrono_temporal_types = true</code> to generate <code>chrono::Duration</code><tr><td>C++<td><code>fory::serialization::Duration</code><td><tr><td>Dart<td><code>Duration</code><td></table> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=any>Any<a href=#any class=hash-link aria-label="Direct link to Any" title="Direct link to Any" translate=no></a></h4> |
| <table><thead><tr><th>Language<th>Type<th>Notes<tbody><tr><td>Java<td><code>Object</code><td>Runtime type written<tr><td>Python<td><code>Any</code><td>Runtime type written<tr><td>Go<td><code>any</code><td>Runtime type written<tr><td>Rust<td><code>Box<dyn Any></code><td>Runtime type written<tr><td>C++<td><code>std::any</code><td>Runtime type written<tr><td>JavaScript/TypeScript<td><code>any</code><td>Runtime type written<tr><td>Dart<td><code>Object?</code><td>Runtime type written</table> |
| <p><strong>Example:</strong></p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> EventType </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>120</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> CREATED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> DELETED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> UserCreated </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>121</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> user_id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Envelope </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>122</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">EventType</span><span class="token plain"> type </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">any</span><span class="token plain"> payload </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Generated Code (<code>Envelope.payload</code>):</strong></p> |
| <table><thead><tr><th>Language<th>Generated Field Type<tbody><tr><td>Java<td><code>Object payload</code><tr><td>Python<td><code>payload: Any</code><tr><td>Go<td><code>Payload any</code><tr><td>Rust<td><code>payload: Box<dyn Any></code><tr><td>C++<td><code>std::any payload</code><tr><td>JavaScript/TypeScript<td><code>payload: any</code><tr><td>Dart<td><code>Object? payload</code></table> |
| <p><strong>Notes:</strong></p> |
| <ul> |
| <li class=""><code>any</code> always writes a null flag (same as <code>nullable</code>) because values may be empty.</li> |
| <li class="">Allowed runtime values are limited to <code>bool</code>, <code>string</code>, <code>enum</code>, <code>message</code>, and <code>union</code>. |
| Other primitives (numeric, bytes, date/time) and list/map are not supported; wrap them in a |
| message or use explicit fields instead.</li> |
| <li class=""><code>ref</code> is not allowed on <code>any</code> fields (including list/map values). Wrap <code>any</code> in a message |
| if you need reference tracking.</li> |
| <li class="">The runtime type must be registered in the target language schema/IDL registration; unknown |
| types fail to deserialize.</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=named-types>Named Types<a href=#named-types class=hash-link aria-label="Direct link to Named Types" title="Direct link to Named Types" translate=no></a></h3> |
| <p>Reference other messages, enums, or unions by name:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> </span><span class="token class-name">Status</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">User</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Order</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">User</span><span class="token plain"> customer </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reference to User message</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">Status</span><span class="token plain"> status </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Reference to Status enum</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=collection-types>Collection Types<a href=#collection-types class=hash-link aria-label="Direct link to Collection Types" title="Direct link to Collection Types" translate=no></a></h3> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=list-list>List (<code>list</code>)<a href=#list-list class=hash-link aria-label="Direct link to list-list" title="Direct link to list-list" translate=no></a></h4> |
| <p>Use the <code>list<...></code> type for list fields. <code>repeated</code> is accepted as an alias. See <a href=#field-modifiers class="">Field Modifiers</a> for |
| modifier combinations and language mapping.</p> |
| <p>Nested collection support is target-capability based. The C++ generator accepts |
| nested collection specs such as <code>list<list<...>></code>, <code>list<map<...>></code>, and |
| <code>map<..., list<...>></code>; targets that have not implemented nested field specs |
| continue to reject them. Use a message wrapper when you need portable schemas |
| across all targets.</p> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=array-array>Array (<code>array</code>)<a href=#array-array class=hash-link aria-label="Direct link to array-array" title="Direct link to array-array" translate=no></a></h4> |
| <p>Use <code>array<T></code> for dynamic-length dense numeric data. <code>array<T></code> is a distinct |
| schema kind from <code>list<T></code> and uses the packed primitive-array wire payload.</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Embedding</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> array</span><span class="token operator" style=color:#393A34><</span><span class="token builtin">int32</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> indices </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> array</span><span class="token operator" style=color:#393A34><</span><span class="token plain">float32</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> values </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> array</span><span class="token operator" style=color:#393A34><</span><span class="token plain">uint8</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> pixels </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><code>array<T></code> accepts <code>bool</code>, integer, and floating-point element domains only. It |
| does not accept <code>optional</code>, <code>ref</code>, named/object types, <code>string</code>, <code>bytes</code>, maps, |
| or scalar integer encoding modifiers such as <code>array<fixed int32></code>; array |
| elements are always fixed-width by the array contract.</p> |
| <p>Generated carriers are language-specific, but the schema kind is not:</p> |
| <table><thead><tr><th>IDL schema<th>Java default<th>Python default<th>Dart default<th>JavaScript/TypeScript<tbody><tr><td><code>list<bool></code><td><code>BoolList</code> / <code>List<Boolean></code><td><code>List[bool]</code><td><code>List<bool></code><td><code>Type.list(Type.bool())</code><tr><td><code>array<bool></code><td><code>boolean[]</code><td><code>pyfory.BoolArray</code><td><code>BoolList</code><td><code>Type.boolArray()</code><tr><td><code>array<int8></code><td><code>@Int8Type byte[]</code><td><code>pyfory.Int8Array</code><td><code>Int8List</code><td><code>Type.int8Array()</code><tr><td><code>array<int16></code><td><code>short[]</code><td><code>pyfory.Int16Array</code><td><code>Int16List</code><td><code>Type.int16Array()</code><tr><td><code>array<int32></code><td><code>int[]</code><td><code>pyfory.Int32Array</code><td><code>Int32List</code><td><code>Type.int32Array()</code><tr><td><code>array<int64></code><td><code>long[]</code><td><code>pyfory.Int64Array</code><td><code>Int64List</code><td><code>Type.int64Array()</code><tr><td><code>array<uint8></code><td><code>@UInt8Type byte[]</code><td><code>pyfory.UInt8Array</code><td><code>Uint8List</code><td><code>Type.uint8Array()</code><tr><td><code>array<uint16></code><td><code>@UInt16Type short[]</code><td><code>pyfory.UInt16Array</code><td><code>Uint16List</code><td><code>Type.uint16Array()</code><tr><td><code>array<uint32></code><td><code>@UInt32Type int[]</code><td><code>pyfory.UInt32Array</code><td><code>Uint32List</code><td><code>Type.uint32Array()</code><tr><td><code>array<uint64></code><td><code>@UInt64Type long[]</code><td><code>pyfory.UInt64Array</code><td><code>Uint64List</code><td><code>Type.uint64Array()</code><tr><td><code>array<float16></code><td><code>Float16Array</code><td><code>pyfory.Float16Array</code><td><code>Float16List</code><td><code>Type.float16Array()</code><tr><td><code>array<bfloat16></code><td><code>BFloat16Array</code><td><code>pyfory.BFloat16Array</code><td><code>Bfloat16List</code><td><code>Type.bfloat16Array()</code><tr><td><code>array<float32></code><td><code>float[]</code><td><code>pyfory.Float32Array</code><td><code>Float32List</code><td><code>Type.float32Array()</code><tr><td><code>array<float64></code><td><code>double[]</code><td><code>pyfory.Float64Array</code><td><code>Float64List</code><td><code>Type.float64Array()</code></table> |
| <p>For handwritten Dart models, <code>array<bool></code> requires <code>BoolList</code> plus |
| <code>@ArrayField(element: BoolType())</code> or |
| <code>@ForyField(type: ArrayType(element: BoolType()))</code>; <code>List<bool></code> remains |
| <code>list<bool></code>. For handwritten Java models, unsigned primitive arrays use |
| type-use annotations on the element type, for example |
| <code>private @UInt32Type int[] ids;</code>. |
| For generated Kotlin models, <code>array<int8></code> uses <code>@ArrayType ByteArray</code>, |
| including nested collection and map positions.</p> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=map>Map<a href=#map class=hash-link aria-label="Direct link to Map" title="Direct link to Map" translate=no></a></h4> |
| <p>Maps with typed keys and values:</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Config</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token map class-name">map</span><span class="token map class-name punctuation" style=color:#393A34><</span><span class="token map class-name builtin">string</span><span class="token map class-name punctuation" style=color:#393A34>,</span><span class="token map class-name"> </span><span class="token map class-name builtin">string</span><span class="token map class-name punctuation" style=color:#393A34>></span><span class="token plain"> properties </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token map class-name">map</span><span class="token map class-name punctuation" style=color:#393A34><</span><span class="token map class-name builtin">string</span><span class="token map class-name punctuation" style=color:#393A34>,</span><span class="token map class-name"> </span><span class="token map class-name builtin">int32</span><span class="token map class-name punctuation" style=color:#393A34>></span><span class="token plain"> counts </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token map class-name">map</span><span class="token map class-name punctuation" style=color:#393A34><</span><span class="token map class-name builtin">int32</span><span class="token map class-name punctuation" style=color:#393A34>,</span><span class="token map class-name"> User</span><span class="token map class-name punctuation" style=color:#393A34>></span><span class="token plain"> users </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p><strong>Language Mapping:</strong></p> |
| <table><thead><tr><th>Fory IDL<th>Java<th>Python<th>Go<th>Rust<th>C++<th>JavaScript/TypeScript<th>Dart<tbody><tr><td><code>map<string, int32></code><td><code>Map<String, Integer></code><td><code>Dict[str, int]</code><td><code>map[string]int32</code><td><code>HashMap<String, i32></code><td><code>std::map<std::string, int32_t></code><td><code>Map<string, number></code><td><code>Map<String, int></code><tr><td><code>map<string, User></code><td><code>Map<String, User></code><td><code>Dict[str, User]</code><td><code>map[string]User</code><td><code>HashMap<String, User></code><td><code>std::map<std::string, User></code><td><code>Map<string, User></code><td><code>Map<String, User></code></table> |
| <p><strong>Key Type Restrictions:</strong></p> |
| <ul> |
| <li class=""><code>string</code> (most common)</li> |
| <li class=""><code>bool</code></li> |
| <li class="">Integer types (<code>int8</code>, <code>int16</code>, <code>int32</code>, <code>int64</code>, <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint64</code>)</li> |
| <li class="">Temporal scalar types (<code>date</code>, <code>timestamp</code>, <code>duration</code>)</li> |
| <li class="">Enums</li> |
| </ul> |
| <p>Map keys do not support binary <code>bytes</code>, floating-point types, <code>decimal</code>, <code>list<T></code>, <code>array<T></code>, |
| or nested <code>map<K, V></code> types. Put those types in map values or wrap them in a message with a |
| portable scalar or enum key.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=type-compatibility-matrix>Type Compatibility Matrix<a href=#type-compatibility-matrix class=hash-link aria-label="Direct link to Type Compatibility Matrix" title="Direct link to Type Compatibility Matrix" translate=no></a></h3> |
| <p>This matrix shows which type conversions are safe across languages:</p> |
| <table><thead><tr><th>From -> To<th>bool<th>int8<th>int16<th>int32<th>int64<th>float32<th>float64<th>string<tbody><tr><td>bool<td>Y<td>Y<td>Y<td>Y<td>Y<td>-<td>-<td>-<tr><td>int8<td>-<td>Y<td>Y<td>Y<td>Y<td>Y<td>Y<td>-<tr><td>int16<td>-<td>-<td>Y<td>Y<td>Y<td>Y<td>Y<td>-<tr><td>int32<td>-<td>-<td>-<td>Y<td>Y<td>-<td>Y<td>-<tr><td>int64<td>-<td>-<td>-<td>-<td>Y<td>-<td>-<td>-<tr><td>float32<td>-<td>-<td>-<td>-<td>-<td>Y<td>Y<td>-<tr><td>float64<td>-<td>-<td>-<td>-<td>-<td>-<td>Y<td>-<tr><td>string<td>-<td>-<td>-<td>-<td>-<td>-<td>-<td>Y</table> |
| <p>Y = Safe conversion, - = Not recommended</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=best-practices>Best Practices<a href=#best-practices class=hash-link aria-label="Direct link to Best Practices" title="Direct link to Best Practices" translate=no></a></h3> |
| <ul> |
| <li class="">Use <code>int32</code> as the default for most integers; use <code>int64</code> for large values.</li> |
| <li class="">Use <code>string</code> for text data (UTF-8) and <code>bytes</code> for binary data.</li> |
| <li class="">Use <code>optional</code> only when the field may legitimately be absent.</li> |
| <li class="">Use <code>ref</code> only when needed for shared or circular references.</li> |
| <li class="">Prefer <code>list</code> for ordered sequences and <code>map</code> for key-value lookups.</li> |
| </ul> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=type-ids>Type IDs<a href=#type-ids class=hash-link aria-label="Direct link to Type IDs" title="Direct link to Type IDs" translate=no></a></h2> |
| <p>Type IDs enable efficient cross-language serialization and are used for |
| messages, unions, and enums. When <code>enable_auto_type_id = true</code> (default) and |
| <code>id</code> is omitted, the compiler auto-generates one using |
| <code>MurmurHash3(utf8(package.type_name))</code> (32-bit) and annotates it in generated |
| code. When <code>enable_auto_type_id = false</code>, types without explicit IDs are |
| registered by namespace and name instead. Collisions are detected at |
| compile-time across the current file and all imports; when a collision occurs, |
| the compiler raises an error and asks for an explicit <code>id</code> or an <code>alias</code>. |
| For Java and Scala generated code, nested name registration appends the parent |
| path to the namespace and keeps the nested type's simple name. For example, |
| <code>package demo; message Envelope { message Payload { ... } }</code> registers |
| <code>Payload</code> as namespace <code>demo.Envelope</code> and type name <code>Payload</code> in those JVM |
| targets.</p> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> Color </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> User </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">union Event </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>102</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>Enum type IDs remain optional; if omitted they are auto-generated using the same |
| hash when <code>enable_auto_type_id = true</code>.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=with-explicit-type-id-2>With Explicit Type ID<a href=#with-explicit-type-id-2 class=hash-link aria-label="Direct link to With Explicit Type ID" title="Direct link to With Explicit Type ID" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> User </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> User </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> deprecated</span><span class="token operator" style=color:#393A34>=</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Multiple options</span><br/></div></code></pre></div></div> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=without-explicit-type-id-1>Without Explicit Type ID<a href=#without-explicit-type-id-1 class=hash-link aria-label="Direct link to Without Explicit Type ID" title="Direct link to Without Explicit Type ID" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">Config</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Auto-generated when enable_auto_type_id = true</span><br/></div></code></pre></div></div> |
| <p>You can set <code>[alias="..."]</code> to change the hash source without renaming the type.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=practical-notes>Practical Notes<a href=#practical-notes class=hash-link aria-label="Direct link to Practical Notes" title="Direct link to Practical Notes" translate=no></a></h3> |
| <ul> |
| <li class="">If a type omits <code>id</code> and <code>enable_auto_type_id = true</code>, Fory generates an ID |
| with <code>MurmurHash3(utf8(package.type_name))</code> (32-bit).</li> |
| <li class="">Package alias and type alias change the hash input and can be used to resolve |
| hash collisions without renaming public types.</li> |
| <li class="">Manual IDs in the small varint range (<code>0-127</code>) are compact on the wire; auto |
| IDs are typically larger and usually consume 4-5 bytes.</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=id-assignment-strategy>ID Assignment Strategy<a href=#id-assignment-strategy class=hash-link aria-label="Direct link to ID Assignment Strategy" title="Direct link to ID Assignment Strategy" translate=no></a></h3> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// Enums: 100-199</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> Status </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> Priority </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// User domain: 200-299</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> User </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>200</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> UserProfile </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>201</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Order domain: 300-399</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Order </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>300</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> OrderItem </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>301</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=complete-example-1>Complete Example<a href=#complete-example-1 class=hash-link aria-label="Direct link to Complete Example" title="Direct link to Complete Example" translate=no></a></h2> |
| <div class="language-protobuf codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-protobuf codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// E-commerce domain model</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>package</span><span class="token plain"> com</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">shop</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">models</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Enums with type IDs</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> OrderStatus </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>100</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> PENDING </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> CONFIRMED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> SHIPPED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> DELIVERED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> CANCELLED </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>enum</span><span class="token plain"> PaymentMethod </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>101</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> CREDIT_CARD </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> DEBIT_CARD </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> PAYPAL </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> BANK_TRANSFER </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Messages with type IDs</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Address </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>200</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> street </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> city </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> state </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> country </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> postal_code </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>5</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Customer </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>201</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> email </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> phone </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> </span><span class="token positional-class-name class-name">Address</span><span class="token plain"> billing_address </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>5</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> </span><span class="token positional-class-name class-name">Address</span><span class="token plain"> shipping_address </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>6</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Product </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>202</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> sku </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> description </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">float64</span><span class="token plain"> price </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">int32</span><span class="token plain"> stock </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>5</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token builtin">string</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> categories </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>6</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token map class-name">map</span><span class="token map class-name punctuation" style=color:#393A34><</span><span class="token map class-name builtin">string</span><span class="token map class-name punctuation" style=color:#393A34>,</span><span class="token map class-name"> </span><span class="token map class-name builtin">string</span><span class="token map class-name punctuation" style=color:#393A34>></span><span class="token plain"> attributes </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>7</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> OrderItem </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>203</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ref </span><span class="token positional-class-name class-name">Product</span><span class="token plain"> product </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Track reference to avoid duplication</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">int32</span><span class="token plain"> quantity </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">float64</span><span class="token plain"> unit_price </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> Order </span><span class="token punctuation" style=color:#393A34>[</span><span class="token annotation">id</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>204</span><span class="token punctuation" style=color:#393A34>]</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> id </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ref </span><span class="token positional-class-name class-name">Customer</span><span class="token plain"> customer </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token plain">OrderItem</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> items </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">OrderStatus</span><span class="token plain"> status </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">PaymentMethod</span><span class="token plain"> payment_method </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>5</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">float64</span><span class="token plain"> total </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>6</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> notes </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>7</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">timestamp</span><span class="token plain"> created_at </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>8</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>optional</span><span class="token plain"> </span><span class="token positional-class-name class-name">timestamp</span><span class="token plain"> shipped_at </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>9</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Config without explicit type ID (auto-generated when enable_auto_type_id = true)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>message</span><span class="token plain"> </span><span class="token class-name">ShopConfig</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> store_name </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token builtin">string</span><span class="token plain"> currency </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token positional-class-name class-name">float64</span><span class="token plain"> tax_rate </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>3</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> list</span><span class="token operator" style=color:#393A34><</span><span class="token builtin">string</span><span class="token operator" style=color:#393A34>></span><span class="token plain"> supported_countries </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>4</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div> |
| <p>For protobuf-specific extension options and <code>(fory).</code> syntax, see |
| <a class="" href=/docs/1.1.0/compiler/protobuf_idl_support#fory-extension-options-protobuf>Protocol Buffers IDL Support</a>.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=grammar-summary>Grammar Summary<a href=#grammar-summary class=hash-link aria-label="Direct link to Grammar Summary" title="Direct link to Grammar Summary" translate=no></a></h2> |
| <div class="language-text codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-text codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">file := [package_decl] file_option* import_decl* definition*</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">package_decl := 'package' package_name ['alias' package_name] ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">package_name := IDENTIFIER ('.' IDENTIFIER)*</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">file_option := 'option' option_name '=' option_value ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">option_name := IDENTIFIER</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">import_decl := 'import' STRING ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">definition := type_def | service_def</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">type_def := enum_def | message_def | union_def</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">enum_def := 'enum' IDENTIFIER [type_options] '{' enum_body '}'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">enum_body := (reserved_stmt | enum_value)*</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">enum_value := IDENTIFIER '=' INTEGER ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">message_def := 'message' IDENTIFIER [type_options] '{' message_body '}'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">message_body := (reserved_stmt | nested_type | field_def)*</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">nested_type := enum_def | message_def | union_def</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">field_def := [modifiers] field_type IDENTIFIER '=' INTEGER [field_options] ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">union_def := 'union' IDENTIFIER [type_options] '{' union_field* '}'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">union_field := ['repeated'] field_type IDENTIFIER '=' INTEGER [field_options] ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">service_def := 'service' IDENTIFIER '{' rpc_method* '}'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">rpc_method := 'rpc' IDENTIFIER '(' ['stream'] named_type ')'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> 'returns' '(' ['stream'] named_type ')' ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">option_value := 'true' | 'false' | IDENTIFIER | INTEGER | STRING</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">reserved_stmt := 'reserved' reserved_items ';'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">reserved_items := reserved_item (',' reserved_item)*</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">reserved_item := INTEGER | INTEGER 'to' INTEGER | INTEGER 'to' 'max' | STRING</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">modifiers := { 'optional' | 'ref' | 'repeated' }</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">field_type := [scalar_encoding] (primitive_type | named_type | list_type | array_type | map_type)</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">primitive_type := 'bool'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> | 'int8' | 'int16' | 'int32' | 'int64'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> | 'uint8' | 'uint16' | 'uint32' | 'uint64'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> | 'float16' | 'bfloat16' | 'float32' | 'float64'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> | 'string' | 'bytes'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> | 'date' | 'timestamp' | 'duration' | 'decimal'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> | 'any'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">scalar_encoding := 'varint' | 'fixed' | 'tagged'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">named_type := qualified_name</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">qualified_name := IDENTIFIER ('.' IDENTIFIER)* // e.g., Parent.Child</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">list_type := 'list' '<' { 'optional' | 'ref' | scalar_encoding } field_type '>'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">array_type := 'array' '<' array_element_type '>'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">map_type := 'map' '<' field_type ',' field_type '>'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">type_options := '[' type_option (',' type_option)* ']'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">type_option := IDENTIFIER '=' option_value // e.g., id=100, deprecated=true</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">field_options := '[' field_option (',' field_option)* ']'</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">field_option := IDENTIFIER '=' option_value // e.g., deprecated=true, ref=true</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">STRING := '"' [^"\n]* '"' | "'" [^'\n]* "'"</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">IDENTIFIER := [a-zA-Z_][a-zA-Z0-9_]*</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">INTEGER := '-'? [0-9]+</span><br/></div></code></pre></div></div></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href=https://github.com/apache/fory-site/tree/main/docs/compiler/schema-idl.md target=_blank rel="noopener noreferrer" class=theme-edit-this-page><svg fill=currentColor height=20 width=20 viewBox="0 0 40 40" class=iconEdit_Z9Sw aria-hidden=true><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"/></g></svg>Edit this page</a></div><div class="col lastUpdated_JAkA"></div></div></footer></article><nav class="docusaurus-mt-lg pagination-nav" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href=/docs/1.1.0/compiler/><div class=pagination-nav__sublabel>Previous</div><div class=pagination-nav__label>Overview</div></a><a class="pagination-nav__link pagination-nav__link--next" href=/docs/1.1.0/compiler/compiler_guide><div class=pagination-nav__sublabel>Next</div><div class=pagination-nav__label>Compiler Guide</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href=#file-structure class="table-of-contents__link toc-highlight">File Structure</a><li><a href=#comments class="table-of-contents__link toc-highlight">Comments</a><li><a href=#package-declaration class="table-of-contents__link toc-highlight">Package Declaration</a><li><a href=#file-level-options class="table-of-contents__link toc-highlight">File-Level Options</a><ul><li><a href=#syntax class="table-of-contents__link toc-highlight">Syntax</a><li><a href=#java-package-option class="table-of-contents__link toc-highlight">Java Package Option</a><li><a href=#go-package-option class="table-of-contents__link toc-highlight">Go Package Option</a><li><a href=#c-namespace-option class="table-of-contents__link toc-highlight">C# Namespace Option</a><li><a href=#kotlin-package-option class="table-of-contents__link toc-highlight">Kotlin Package Option</a><li><a href=#go-nested-type-style-option class="table-of-contents__link toc-highlight">Go Nested Type Style Option</a><li><a href=#swift-namespace-style-option class="table-of-contents__link toc-highlight">Swift Namespace Style Option</a><li><a href=#rust-chrono-temporal-types-option class="table-of-contents__link toc-highlight">Rust Chrono Temporal Types Option</a><li><a href=#java-outer-classname-option class="table-of-contents__link toc-highlight">Java Outer Classname Option</a><li><a href=#java-multiple-files-option class="table-of-contents__link toc-highlight">Java Multiple Files Option</a><li><a href=#multiple-options class="table-of-contents__link toc-highlight">Multiple Options</a><li><a href=#protobuf-extension-syntax class="table-of-contents__link toc-highlight">Protobuf Extension Syntax</a><li><a href=#option-priority class="table-of-contents__link toc-highlight">Option Priority</a><li><a href=#cross-language-type-registration class="table-of-contents__link toc-highlight">Cross-Language Type Registration</a></ul><li><a href=#import-statement class="table-of-contents__link toc-highlight">Import Statement</a><ul><li><a href=#basic-syntax class="table-of-contents__link toc-highlight">Basic Syntax</a><li><a href=#multiple-imports class="table-of-contents__link toc-highlight">Multiple Imports</a><li><a href=#path-resolution class="table-of-contents__link toc-highlight">Path Resolution</a><li><a href=#complete-example class="table-of-contents__link toc-highlight">Complete Example</a><li><a href=#unsupported-import-syntax class="table-of-contents__link toc-highlight">Unsupported Import Syntax</a><li><a href=#import-errors class="table-of-contents__link toc-highlight">Import Errors</a></ul><li><a href=#enum-definition class="table-of-contents__link toc-highlight">Enum Definition</a><ul><li><a href=#basic-syntax-1 class="table-of-contents__link toc-highlight">Basic Syntax</a><li><a href=#with-explicit-type-id class="table-of-contents__link toc-highlight">With Explicit Type ID</a><li><a href=#reserved-values class="table-of-contents__link toc-highlight">Reserved Values</a><li><a href=#enum-type-options class="table-of-contents__link toc-highlight">Enum Type Options</a><li><a href=#language-mapping class="table-of-contents__link toc-highlight">Language Mapping</a><li><a href=#enum-prefix-stripping class="table-of-contents__link toc-highlight">Enum Prefix Stripping</a></ul><li><a href=#message-definition class="table-of-contents__link toc-highlight">Message Definition</a><ul><li><a href=#basic-syntax-2 class="table-of-contents__link toc-highlight">Basic Syntax</a><li><a href=#with-explicit-type-id-1 class="table-of-contents__link toc-highlight">With Explicit Type ID</a><li><a href=#without-explicit-type-id class="table-of-contents__link toc-highlight">Without Explicit Type ID</a><li><a href=#language-mapping-1 class="table-of-contents__link toc-highlight">Language Mapping</a><li><a href=#reserved-fields class="table-of-contents__link toc-highlight">Reserved Fields</a><li><a href=#message-type-options class="table-of-contents__link toc-highlight">Message Type Options</a></ul><li><a href=#nested-types class="table-of-contents__link toc-highlight">Nested Types</a><ul><li><a href=#nested-messages class="table-of-contents__link toc-highlight">Nested Messages</a><li><a href=#nested-enums class="table-of-contents__link toc-highlight">Nested Enums</a><li><a href=#qualified-type-names class="table-of-contents__link toc-highlight">Qualified Type Names</a><li><a href=#deeply-nested-types class="table-of-contents__link toc-highlight">Deeply Nested Types</a><li><a href=#language-specific-generation class="table-of-contents__link toc-highlight">Language-Specific Generation</a><li><a href=#nested-type-rules class="table-of-contents__link toc-highlight">Nested Type Rules</a></ul><li><a href=#union-definition class="table-of-contents__link toc-highlight">Union Definition</a><ul><li><a href=#basic-syntax-3 class="table-of-contents__link toc-highlight">Basic Syntax</a><li><a href=#using-a-union-in-a-message class="table-of-contents__link toc-highlight">Using a Union in a Message</a><li><a href=#rules class="table-of-contents__link toc-highlight">Rules</a></ul><li><a href=#service-definition class="table-of-contents__link toc-highlight">Service Definition</a><ul><li><a href=#streaming-rpcs class="table-of-contents__link toc-highlight">Streaming RPCs</a><li><a href=#rpc-type-rules class="table-of-contents__link toc-highlight">RPC Type Rules</a></ul><li><a href=#field-definition class="table-of-contents__link toc-highlight">Field Definition</a><ul><li><a href=#basic-syntax-4 class="table-of-contents__link toc-highlight">Basic Syntax</a><li><a href=#with-modifiers class="table-of-contents__link toc-highlight">With Modifiers</a><li><a href=#field-modifiers class="table-of-contents__link toc-highlight">Field Modifiers</a><li><a href=#combining-modifiers class="table-of-contents__link toc-highlight">Combining Modifiers</a></ul><li><a href=#field-numbers class="table-of-contents__link toc-highlight">Field Numbers</a><li><a href=#type-system class="table-of-contents__link toc-highlight">Type System</a><ul><li><a href=#primitive-types class="table-of-contents__link toc-highlight">Primitive Types</a><li><a href=#named-types class="table-of-contents__link toc-highlight">Named Types</a><li><a href=#collection-types class="table-of-contents__link toc-highlight">Collection Types</a><li><a href=#type-compatibility-matrix class="table-of-contents__link toc-highlight">Type Compatibility Matrix</a><li><a href=#best-practices class="table-of-contents__link toc-highlight">Best Practices</a></ul><li><a href=#type-ids class="table-of-contents__link toc-highlight">Type IDs</a><ul><li><a href=#with-explicit-type-id-2 class="table-of-contents__link toc-highlight">With Explicit Type ID</a><li><a href=#without-explicit-type-id-1 class="table-of-contents__link toc-highlight">Without Explicit Type ID</a><li><a href=#practical-notes class="table-of-contents__link toc-highlight">Practical Notes</a><li><a href=#id-assignment-strategy class="table-of-contents__link toc-highlight">ID Assignment Strategy</a></ul><li><a href=#complete-example-1 class="table-of-contents__link toc-highlight">Complete Example</a><li><a href=#grammar-summary class="table-of-contents__link toc-highlight">Grammar Summary</a></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Community</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://lists.apache.org/list.html?dev@fory.apache.org target=_blank rel="noopener noreferrer" class=footer__link-item>Mailing list<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://join.slack.com/t/fory-project/shared_invite/zt-1u8soj4qc-ieYEu7ciHOqA2mo47llS8A target=_blank rel="noopener noreferrer" class=footer__link-item>Slack<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://twitter.com/ApacheFory target=_blank rel="noopener noreferrer" class=footer__link-item>Twitter<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Docs</div><ul class="footer__items clean-list"><li class=footer__item><a class=footer__link-item href=/docs/start/install>Install</a><li class=footer__item><a class=footer__link-item href=/docs/start/usage>Usage</a><li class=footer__item><a class=footer__link-item href=/docs/introduction/benchmark>Benchmark</a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Repositories</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class=footer__link-item>Apache Fory™<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://github.com/apache/fory-site target=_blank rel="noopener noreferrer" class=footer__link-item>Website<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div></div><div class="footer__bottom text--center"><div class=margin-bottom--sm><a href=https://apache.org/ rel="noopener noreferrer" class=footerLogoLink_BH7S><img src=/img/asf_logo.svg alt="ASF Logo" class="footer__logo themedComponent_mlkZ themedComponent--light_NVdE" width=200 /><img src=/img/asf_logo.svg alt="ASF Logo" class="footer__logo themedComponent_mlkZ themedComponent--dark_xIcU" width=200 /></a></div><div class=footer__copyright><div> |
| <p> |
| Copyright © 2026 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. <br/> |
| Apache Fory, Fory, Apache, the Apache Logo and the Apache Fory logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. |
| </p> |
| </div></div></div></div></footer></div></body> |
