--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/readme.md	Sun Feb 25 17:12:33 2018 +0300
@@ -0,0 +1,160 @@
+
+# SINOPSYS 
+
+```xml
+<package
+	xmlns="http://implab.org/schemas/data-model.v1.xsd"
+	name="simple-model"
+>
+	<!-- import predefined types -->
+	<import href="types.xml"/>
+	
+	<!-- define entity -->
+	<entity name="Order">
+		<!-- define primary key -->
+		<primaryKey name="Id" type="uuid"/>
+		
+		<!-- define simple property -->
+		<property name="OrderDate" type="dateTime"/>
+		
+		<!-- define hasA relation -->
+		<hasA name="Item" type="Item">
+			<!-- specified a property which holds reference -->
+			<thisKey name="ItemId"/>
+		</hasA>
+		
+		<!-- define hasMany relation -->
+		<hasMany name="Comments" type="OrderComment">
+			<otherKey name="Order"/>
+		</hasMany>
+	</entity>
+	
+	<entity name="Item">
+		<primaryKey name="Id" type="uuid"/>
+		
+		<property name="Title" type="string" />
+		
+	</entity>
+	
+	<entity name="OrderComment">
+		<primaryKey name="Id" type="uuid" />
+		
+		<property name="Comment" type="text" />
+		
+		<property name="Date" type="dateTime" />
+		
+		<hasA name="Order" type="Order">
+			<thisKey name="OrderId" />
+		</hasA>
+	</entity>
+</package>
+```
+
+# DESCRIPTION
+
+Описание модели включает в себя описание наборов сущностей, каждый набор
+называется пакетом.
+
+В пакете содержатся описания сущностей, а также объявления внешних типов,
+которые используются при описании сущностей.
+
+Для уменьшения количества дублируемого кода, а также для упрощения читаемости
+и упрощения сопровождения существует возможность импортирования уже объявленных
+пакетов. В процессе сборки происходит предварительная обработка, которая
+использует все директивы `import` для составления общего модуля, состоящего
+из нескольких пакетов, при этом пакет с которого был начат процесс сборки
+называется первичным и после окончания предварительной обработки для него будет
+выполнена сборка.
+
+Каждая сущность модели состоит из нескольких типов членов, это
+* Свойства - используются для хранения состояния сущности, аналогичны столбцам в таблице
+* Ключи - информация для идентификации записей, каждая запись должна иметь по крайней мере первичный ключ.
+* Отношения - информация о связях между сущностями
+
+## Properties
+
+## PrimaryKey
+
+Внешний ключ представляет собой набор уникальных данных, позволяющий однозначно
+идентифицировать запись, при этом внешний ключ может состоять как из одного
+поля (простые), так и из нескольких (составные)
+
+Простые первичные ключи
+
+```xml
+<primaryKey name="Id" type="uuid"/>
+```
+
+Составные первичные ключи
+
+```xml
+<primaryKey name="Id">
+	<member name="Owner"/>
+	<member name="SeqNum"/>
+</primaryKey>
+<property name="SeqNum" type="integer"/>
+<hasA name="Owner" type="User">
+	<thisKey name="UserId" />
+</hasA>
+```
+При описании составных ключей перечисляется набор членов сущности, которые
+будут образовывать уникальный набор данных для первичного ключа, следует
+отметить, что не все отношения храняться в самой сущности, например,
+`hasMany` может хранится не в записях самой сущности, а в записях связанной
+сущности, такие отношения нельзя включать в первичный ключ.
+Отношение `hasA`, напротив, как парвило хранится в свойствах самой сущности
+и включение его в первичный ключ означает автоматическое включение всех
+свойств.
+
+## Relations
+
+### hasA
+
+`hasA` это отношение, при котором текущей сущности может
+соответсвовать одна связанная сущность. При реализации
+данного отношение может быть указано свойство, используемое
+для хранения ссылки при помощи дочернего элемента `thisKey`
+
+`thisKey` указывает способ реализации отношения, при котором
+в текущей сущности хранится информация для осуществления связи.
+
+По-умолчанию для связи используются первичные ключи, что
+позволяет автоматически определять набор и типы необходимых
+свойств для хранения ссылки.
+
+```xml
+<hasA name="Order" type="Order" optional="true">
+	<thisKey name="OrderId" />
+</hasA>
+```
+
+В случях когда первичный ключ является сложным можно указать
+префикс или явно перечислить свойства в которых будет хранится
+связь
+
+```xml
+<property name="UserId" type="uuid"/>
+<property name="MemberNo" type="integer"/>
+<hasA name="Membership" type="Membership">
+	<thisKey>
+		<member name="UserId"/>
+		<member name="MemberNo"/>
+	</thisKey>
+</hasA>
+```
+
+### hasMany
+
+Отношение при котором с текущей записью связано произвольное
+количество записей другой сущности.
+
+Как правило это отношение является комплиментарным к `hasA` с другой стороны.
+
+```xml
+<hasMany name="Roles" type="Role">
+	<otherKey name="User"/>
+</hasMany>
+```
+
+`otherKey` указывает имя члена в связанной сущности, который хранит информацию
+о связи, это может быть оношение, свойство или ключ.
\ No newline at end of file