Repository navigation
6. Core Language Concepts
This page describes the concepts shared by all ORBIT diagram types.
While each diagram type may define its own grammar, all ORBIT documents follow the same foundational structure and rules.
An ORBIT document consists of:
- Optional global documentation
- Diagram type declaration
- Model definitions
Example:
"""
Customer management database.
Stores users, orders and payments.
"""
diagram database;
table users {
column id int;
};
A global documentation block describes the entire model.
Unlike comments, documentation is part of the model and may be used by renderers, documentation generators, exporters, and other tools.
A global documentation block must appear immediately before the diagram type declaration.
No empty lines are allowed between the documentation block and the diagram type declaration.
Example:
"""
Customer management database.
"""
diagram database;
Every ORBIT document must declare exactly one diagram type.
The diagram type determines:
- Domain grammar
- Available elements
- Available relationships
- Validation rules
Example:
diagram database;
Abstract form:
diagram <diagram-type>;
Elements are the primary building blocks of a model.
Examples:
- Table
- Class
- Task
- Milestone
- Process
- Stakeholder
The exact element types are defined by each diagram grammar.
Abstract form:
<element-type> <identifier> {
...
};
Example:
table users {
column id int;
};
Elements and attributes may contain documentation blocks.
Documentation blocks are part of the model and may be used by renderers and external tools.
A documentation block must appear immediately before the element or attribute it describes.
No empty lines are allowed between the documentation block and the target declaration.
Example:
"""
System users.
"""
table users {
"""
Unique identifier.
"""
column id int;
};
Attributes define properties of an element.
Examples:
- Columns
- Fields
- Parameters
- Metadata
- Configuration values
Abstract form:
<attribute-type> <identifier> <value>;
Example:
column email string;
Relationships define connections between elements.
Examples:
- References
- Associations
- Dependencies
- Flows
- Transitions
Relationship syntax is defined by each diagram grammar.
Relationships may represent:
- One-to-one
- One-to-many
- Many-to-one
- Many-to-many
or other domain-specific connection types.
Abstract form:
<relationship-definition>;
Example:
relationship user_orders {
orders.user_id -> users.id;
};
Comments are ignored by the model.
Comments do not participate in validation, rendering, documentation generation, or exports.
Example:
// Temporary migration table
Identifiers uniquely name model elements.
Identifiers should be descriptive and follow a consistent naming convention within a model.
Example:
users
customer_orders
payment_history
Every statement must terminate with a semicolon, including block statements.
Example:
diagram database;
column id int;
relationship user_orders {
orders.user_id -> users.id;
};
"""
Model description.
"""
diagram <diagram-type>;
"""
Element description.
"""
<element-type> <identifier> {
"""
Attribute description.
"""
<attribute-type> <identifier> <value>;
};
<relationship-definition>;
"""
Customer management database.
"""
diagram database;
"""
System users.
"""
table users {
"""
Unique identifier.
"""
column id int;
"""
User email address.
"""
column email string;
};
relationship user_orders {
orders.user_id -> users.id;
};
На этой странице описаны концепции, общие для всех типов диаграмм ORBIT.
Каждая грамматика может определять собственные конструкции, однако все документы ORBIT подчиняются единому набору базовых правил.
Документ ORBIT состоит из:
- Необязательной глобальной документации
- Объявления типа диаграммы
- Определений модели
Пример:
"""
Customer management database.
Stores users, orders and payments.
"""
diagram database;
table users {
column id int;
};
Глобальный блок документации описывает модель целиком.
В отличие от комментариев, документация является частью модели и может использоваться рендерерами, генераторами документации, экспортерами и другими инструментами.
Глобальный блок документации должен располагаться непосредственно перед объявлением типа диаграммы.
Между блоком документации и объявлением типа диаграммы не допускаются пустые строки.
Пример:
"""
Customer management database.
"""
diagram database;
Каждый документ ORBIT обязан объявлять ровно один тип диаграммы.
Тип диаграммы определяет:
- Используемую грамматику
- Доступные элементы
- Доступные связи
- Правила валидации
Пример:
diagram database;
Абстрактная форма:
diagram <diagram-type>;
Элементы являются основными строительными блоками модели.
Примеры:
- Таблица
- Класс
- Задача
- Веха
- Процесс
- Заинтересованная сторона
Конкретные типы элементов определяются грамматикой диаграммы.
Абстрактная форма:
<element-type> <identifier> {
...
};
Элементы и атрибуты могут содержать блоки документации.
Блоки документации являются частью модели и могут использоваться рендерерами и внешними инструментами.
Блок документации должен располагаться непосредственно перед элементом или атрибутом, который он описывает.
Между документацией и описываемой конструкцией не допускаются пустые строки.
Пример:
"""
System users.
"""
table users {
"""
Unique identifier.
"""
column id int;
};
Атрибуты определяют свойства элементов.
Примеры:
- Колонки
- Поля
- Параметры
- Метаданные
- Конфигурация
Абстрактная форма:
<attribute-type> <identifier> <value>;
Связи определяют отношения между элементами модели.
Примеры:
- Ссылки
- Ассоциации
- Зависимости
- Потоки
- Переходы
Конкретный синтаксис связей определяется грамматикой соответствующего типа диаграммы.
Связи могут представлять:
- Один к одному
- Один ко многим
- Многие к одному
- Многие ко многим
либо другие виды отношений, характерные для конкретной предметной области.
Абстрактная форма:
<relationship-definition>;
Комментарии игнорируются моделью.
Комментарии не участвуют в валидации, рендеринге, генерации документации или экспорте.
Пример:
// Temporary migration table
Идентификаторы используются для именования элементов модели.
Имена должны быть понятными и использовать единый стиль в пределах проекта.
Примеры:
users
customer_orders
payment_history
Каждая инструкция должна завершаться символом ;, включая блочные инструкции.
Пример:
diagram database;
column id int;
relationship user_orders {
orders.user_id -> users.id;
};
"""
Model description.
"""
diagram <diagram-type>;
"""
Element description.
"""
<element-type> <identifier> {
"""
Attribute description.
"""
<attribute-type> <identifier> <value>;
};
<relationship-definition>;
"""
Customer management database.
"""
diagram database;
"""
System users.
"""
table users {
"""
Unique identifier.
"""
column id int;
"""
User email address.
"""
column email string;
};
relationship user_orders {
orders.user_id -> users.id;
};