Definition Style Guide

Though XML is the sole official definition format at this point, any text format can be used to build x2 definitions. However, regardless of the definition format, sticking to a consistent style helps keep your generated source files clean.

Capitalization

Use PascalCase for all the user-provided identifiers. Since there is no behavior semantics in x2 definitions, they are mostly expected to be in a noun form. Underscores('_') or any other special characters are prohibited.

<?xml version="1.0" encoding="utf-8"?>
<x2 namespace="MyPhonebook">
  <definitions>
    ...
    <cell name="PhonebookEntry">
        <property name="Name" type="string"/>
        <property name="PhoneNumber" type="string"/>
    </cell>
    ...
  </definitions>
</x2>

Namespace

Every x2 definition file may contain a single namespace path specification. A namespace specification consists of one or more namespace elements in PascalCase separated by slashes('/').

<?xml version="1.0" encoding="utf-8"?>
<x2 namespace="MyNamespace1/MyNamespace2">
    ...
</x2>

Constants

Constants are also named in PascalCase and their references use dot('.') to separate a constant from its containing constant set. Typically, event type identifiers in a non-trivial system are maintained as x2 constants.

<?xml version="1.0" encoding="utf-8"?>
<x2 namespace="MyPhonebook">
  <definitions>
    ...
    <consts name="PhonebookEventType">
        <const name="PhoneNumberChanged">1</const>
    </consts>
    
    <event name="PhoneNumberChanged" id="PhoneBookEventType.PhoneNumberChanged">
        <property name="NewValue" type="string"/>
    </event>
  </definitions>
</x2>

Events

Events may be named in verb (passive especially) form to represent an occurrence of specific stuff. When two events are paired as request-response, they are usually named as '~Req' and '~Resp'.

<?xml version="1.0" encoding="utf-8"?>
<x2 namespace="MyPhonebook">
  <definitions>
    ...
    <consts name="PhonebookEventType">
        <const name="PhoneNumberChanged">1</const>

        <const name="PhonebookListReq">2</const>
        <const name="PhonebookListResp">3</const>
    </consts>
    
    <event name="PhoneNumberChanged" id="PhoneBookEventType.PhoneNumberChanged">
        <property name="NewValue" type="string"/>
    </event>
    
    <event name="PhonebookListReq" id="PhoneBookEventType.PhonebookListReq">
    </event>
    
    <event name="PhonebookListResp" id="PhoneBookEventType.PhonebookListResp">
        <property name="Entries" type="list(PhonebookEntry)"/>
    </event>
  </definitions>
</x2>