Geabaire uses its own bespoke board formatting system. It is a direct alternative to the open standard known as the "Open Board Format". It encodes the entire textual content of a board into a single (albeit large) JSON File. This document marks the beginning of this format's specification.

Top-Level Look

A board consists of three top-level properties; meta, boards and paths, all of which must exist for the board to render properly within Geabaire.

Boards

This contains the meat of the board. It is a map of board IDs to board content. The parent field within the board's meta refers to the ID of the root board, which is the first and only board to be loaded on first launch.

Whether or not to load subsequent boards is based on the user's navigation. The user navigation should be implemented as a stack of board IDs whose first entry is the root board. It is also recommended that you add protection such that it is impossible to remove the root board from your navigation history.

A board takes the following form:

id: The UUID of the board (the same as its key) (Deprecated)
owner: The UUID of the owner of the board (Deprecated)
parent: The UUID of the parent board — the board which subsequently links to this board (null in the case of the root board)
grid: An object containing the properties rows and columns which determines how many rows and columns to render the board's buttons as.
buttons: An array which contains the buttons to be rendered, this constitutes the largest portion of data within any board. See button below for details on the contents of a button.

Buttons are rendered from the buttons array based on the number of rows and columns, in Geabaire this defaults to rendering row-by-row.

Empty Example:

"5ed545e5-3292-426f-93b2-1ee7433ed734": {
    "id": "",
    "owner": "",
    "parent": "",
    "grid": {
        "rows": 2,
        "columns": 2
    },
    "buttons": []
},

Board Buttons

Buttons are the clickable elements of a board, and constitute part of a board. There are three types of buttons:

Phrasal buttons: These add some text to the currently constructed phrase when pressed.
Navigation buttons: These navigate a user to a sub-board.
Utility buttons: These are special buttons which have platform-defined functionality. They are constructed as phrasal buttons with a special control phrase in their label in the form <% NAME> where name is the type of utility button. In Geabaire there are two utility buttons; keyboard and plural which open the devices' native keyboard and pluralises the previous utterance respectively.

Buttons are constructed from the following fields:

label: The text shown inside of a button, and the text which is appended to a phrase.
border_color: The color of the border around a button
background_color: The background color of a button
part_of_speech: A part of speech tag for this button, not currently used by Geabaire
child: (Optional) the ID of a sub-board to navigate to when clicked, the prescence of this field makes it a navigation button.
hide_label: Whether or not to render the label, this is useful in cases where the image alone is sufficient.
image: a UUID of the image
image_type: The image type, this is no longer used within Geabaire (Deprecated)

If a button within the array is null that implies that an empty button should be rendered within React Native to keep the grid-like apperance, this might not be necessary on web platforms due to the prescence of CSS Grid.

Paths

Paths is the part of the board which stores a form of search-tree which is used by the word finder functionality. It stores an array of how to get to every possible word. It is an array of objects where the objects take the form:

{
    "label": "mo ghestaltaí",
    "path": [
        "liomsa",
        "mo ghestaltaí"
    ]
},

Where mo ghestaltaí is the text available within the search window, and liomsa -> mo ghestaltaí is the method of getting to that particular word, i.e., one must press on liomsa to get navigated to its subboard, where the target word can be found. In future versions of this functionality, it should be automatable such that a user can click on the target word and be shown how to navigate to that word to further build motor planning.

The reason for it being an array rather than a map is there are multiple cases where the same utterance can be constructed in multiple ways.

MVP Board

To help build understanding of the board format, I (Rían) have created an entire board from scratch by hand, by following the documentation above, which shows the simplest form of board, with small grid sizes and only 2 sub-boards. The entire board json can be found below, and you can test this board by using the following login information:

Username	Password
mvp-board@abair.ie	test1234

The board defined below is a quick-and-dirty example showing you basic navigation, how buttons are created, etc. It doesn't show the full functionality of the format (i.e., no utility buttons)

{
    "meta": {
        "id": "928208ca-a54f-4fe5-933e-e266a39b82bb",
        "owner": "a67d620c-5f6b-45be-8ced-09f1c12ec680",
        "parent": "5ed545e5-3292-426f-93b2-1ee7433ed734",
        "version": 0
    },
    "boards": {
        "5ed545e5-3292-426f-93b2-1ee7433ed734": {
            "id": "",
            "owner": "",
            "parent": "",
            "grid": {
                "rows": 2,
                "columns": 2
            },
            "buttons": [
                {
                    "label": "Sub-Board 1",
                    "border_color": "#f00eec",
                    "background_color": "#ffffff",
                    "part_of_speech": "verb",
                    "hide_label": false,
                    "image": "19fd02e6-e39a-4229-8a18-6dd9f786e0e2",
                    "image_type": "svg",
                    "child": "00d9c7c1-359b-4877-a332-8a66cd2d38b8"
                },
                {
                    "label": "Sub-Board 2",
                    "border_color": "#f00eec",
                    "background_color": "#ffffff",
                    "part_of_speech": "verb",
                    "hide_label": false,
                    "image": "e22caac3-55f0-4718-8c8b-a7045354466c",
                    "image_type": "svg",
                    "child": "f1213615-d5b1-4563-9904-06cd1ec9e6ee"
                },
                {
                    "label": "dia dhuit",
                    "border_color": "#f00eec",
                    "background_color": "#ffffff",
                    "part_of_speech": "verb",
                    "hide_label": false,
                    "image": "d7311556-06f4-4618-9a13-2c1184ca6cde",
                    "image_type": "svg"
                },
                {
                    "label": "go raibh maith agat",
                    "border_color": "#f00eec",
                    "background_color": "#ffffff",
                    "part_of_speech": "verb",
                    "hide_label": false,
                    "image": "24065d48-a8d2-416b-bb32-f5df41384f09",
                    "image_type": "svg"
                }   
            ]
        },
        "00d9c7c1-359b-4877-a332-8a66cd2d38b8": {
            "id": "",
            "owner": "",
            "parent": "",
            "grid": {
                "rows": 4,
                "columns": 4
            },
            "buttons": [
                null, 
                null, 
                null, 
                null,
                null, 
                {
                    "label": "Conas atá tú",
                    "border_color": "#f00eec",
                    "background_color": "#ffffff",
                    "part_of_speech": "verb",
                    "hide_label": false,
                    "image": "d7311556-06f4-4618-9a13-2c1184ca6cde",
                    "image_type": "svg"
                },
                {
                    "label": "An labhraíonn tú Gaeilge",
                    "border_color": "#f00eec",
                    "background_color": "#ffffff",
                    "part_of_speech": "verb",
                    "hide_label": false,
                    "image": "d7311556-06f4-4618-9a13-2c1184ca6cde",
                    "image_type": "svg"
                },
                null,
                null, 
                {
                    "label": "Le do thoil",
                    "border_color": "#f00eec",
                    "background_color": "#ffffff",
                    "part_of_speech": "verb",
                    "hide_label": false,
                    "image": "d7311556-06f4-4618-9a13-2c1184ca6cde",
                    "image_type": "svg"
                },
                {
                    "label": "Tá mé go maith",
                    "border_color": "#f00eec",
                    "background_color": "#ffffff",
                    "part_of_speech": "verb",
                    "hide_label": false,
                    "image": "d7311556-06f4-4618-9a13-2c1184ca6cde",
                    "image_type": "svg"
                }, 
                null,
                null,
                null,
                null, 
                null
            ]
        },
        "f1213615-d5b1-4563-9904-06cd1ec9e6ee": {
            "id": "",
            "owner": "",
            "parent": "",
            "grid": {
                "rows": 1,
                "columns": 1
            },
            "buttons": [
                {
                    "label": "The only button in this grid.",
                    "border_color": "#f00eec",
                    "background_color": "#ffffff",
                    "part_of_speech": "verb",
                    "hide_label": false,
                    "image": "d7311556-06f4-4618-9a13-2c1184ca6cde",
                    "image_type": "svg"
                }
            ]
        }
    },
    "paths": []
}

Meta​

Boards​

Board Buttons​

Paths​

MVP Board​

Meta

Boards

Board Buttons

Paths

MVP Board