Textual graph format is used to write ontologies in Simantics platform. [Graph Compiler](GraphCompiler.md) translates textual format to binary [Transferable graphs](TransferableGraph.md) that can be then imported to Simantics database.

## Syntax

### Indentation

The graph format is indentation based. The amount of indentation can be freely chosen, but it has to be consistent with the previous lines. The lines can be indendented only with spaces. Tabulators are not allowed.

Both C and C++ style comments are allowed. If a C style comment begins a line, there must not be anything else in the line after the comment, otherwise the amount of indentation would be then unclear. Text in parenthesis (), [] and {} can be freely indented.

### Statements

A graph file describes a collection of statements. One statement is written as:

    Subject Predicate Object

and represented graphically as

![Subject Predicate Object](Images/SubPreObj.png)

Statements with the same subject can be written in the same line

    Subject Predicate1 Object1 Predicate2 Object2 Predicate3 Object3

or with multiple indented lines

~~~
 Subject
     Predicate1 Object1
     Predicate2 Object2
     Predicate3 Object3
~~~

These forms can also be combined

~~~
 Subject Predicate1 Object1 Predicate2 Object2
     Predicate3 Object3
     Predicate4 Object4
~~~

Statements with the same subject and predicate can be abbreviated as

~~~
 Subject
     Predicate
         Object1
         Object2
         Object3
~~~

In this case, there must be no objects in the same line with the predicate.

Statements concerning the object of another statement can be written after the object if the object is not in the same line with the original subject. The following texts describe the same graph:

![Subject Predicate Object Chain](Images/SubPreObj_chain_01.png)

~~~
Subject Predicate1 Object1
Object1 Predicate2 Object2

Subject
    Predicate1 Object1 Predicate2 Object2

Subject
    Predicate1 Object1
        Predicate2 Object2

Subject
    Predicate1
        Object1 Predicate2 Object2         

Subject
    Predicate1
        Object1
            Predicate2 Object2

Subject
    Predicate1
        Object1
            Predicate2
                Object2
~~~

### Resources

Subject, predicate, and object of a statement are all resources. Predicates and other resources are handled little differently. A resource can be in one of the following forms:
* Identifier
* URI
* Reference to a child of another resource
* Literal value (not allowed as a predicate)
* Data type (not allowed as a predicate)
* A special relation: =, <T, <R, : (allowed only as a predicate)

Identifier must begin with a letter or '_' and continue with letters, numbers and '_' characters. Single underscore _ is a special identifier that denotes a fresh resource: Every _ refers to a different resources.

URI is enclosed in <>-characters and must begin with "http:". For example
`<http://www.simantics.org/Layer0-1.0/InstanceOf>`.

The syntax of literal values and data types is specified in [[Databoard Specification#Value Text Notation]]. Variants and tagged values (of some union type) must be enclosed in parenthesis. A data type must be prefixed with $ and union types and array types must be enclosed in parenthesis.

References are used to refer URIs: If identifier A referes to <nowiki><http://somedomain/A></nowiki>, then A.Foo referes to <nowiki><http://somedomain/A/Foo></nowiki>. If URI contains non-alphanumerical characters, the name can be enclosed in double quotes. For example A."Cul-de-sac" refers to <nowiki><http://somedomain/A/Cul-de-sac></nowiki>.

Special relations are abbreviations of some Layer0 relations:
{|
|-
|width="40px" align="center"| =
| <nowiki>http://www.simantics.org/Layer0-1.0/Equals</nowiki>
|-
|width="40px" align="center"| <T
| <nowiki>http://www.simantics.org/Layer0-1.0/Inherits</nowiki>
|-
|width="40px" align="center"| <R
| <nowiki>http://www.simantics.org/Layer0-1.0/SubrelationOf</nowiki>
|-
|width="40px" align="center"| :
| <nowiki>http://www.simantics.org/Layer0-1.0/InstanceOf</nowiki>
|-
|width="40px" align="center"| >--
| <nowiki>http://www.simantics.org/Layer0-1.0/IsDomainOf</nowiki>
|-
|width="40px" align="center"| <--
| <nowiki>http://www.simantics.org/Layer0-1.0/HasDomain</nowiki>
|-
|width="40px" align="center"| -->
| <nowiki>http://www.simantics.org/Layer0-1.0/HasRange</nowiki>
|-
|width="40px" align="center"| ==>
| <nowiki>http://www.simantics.org/Layer0-1.0/RequiresValueType</nowiki>
|}

### Templates

A template is a parametrized graph that can be defined and instantiated.

A template is defines as follows:

~~~
 <name of the template> : L0.Template
     @template <parameters>
         <template body>
~~~

for example

~~~
 L0.assert : L0.Template
     @template %type %predicate %object
         %type
             L0.Asserts _ : L0.Assertion
                 L0.HasPredicate %predicate
                 L0.HasObject    %object
~~~

The template body is written in normal graph notation that can be refer to the parameters.

A templates is applied as follows:

    @<name of the template> <parameter1> ... <parameterN>
        <parameterN+1> ...
            ...
        <parameterN+2> ...
            ...
        ...

For example

    My.Type <T L0.Entity
        @L0.assert My.HasTransformation
            4.0 : My.Transformation

## Completion rules

A textual graph is flattened to a set of raw statements in a straightforward way. After that some rules are applied that add statements to the graph.

### Merging equal resources

All resources that have the relation `<http://www.simantics.org/Layer0-1.0/Equals>` (=) between them are merged, i.e their statements are combined. This can be used to give shorthand references to resources:

~~~
L0 = <http://www.simantics.org/Layer0-1.0>
Foo <T L0.Entity
~~~

### Typing literals

The data type of a literal must be specified either with HasDataType statement or by instantiating a type that asserts this kind of statement:

    1 : L0.Literal
        L0.HasDataType @Integer

    1 : L0.Integer

In order to make writing graphs easier, the InstanceOf statement of a literal is derived from the value, if it is not explicitly specified. The following literal types defined in Layer0 are supported:
* Boolean
* Integer
* Double
* String
* BooleanArray
* IntegerArray
* DoubleArray
* StringArray

### Inverse relations

A default inverse relation is created for a relation whose superrelation has an inverse. Also superrelations are added to inverses automatically based on the superrelations of the relation.

Relations will thus have inverses if:
* an inverse is explicitly defined for a relation:

      ONTOLOGY.SymmetricRelation <R L0.IsWeaklyRelatedTo
         @L0.symmetric
      ONTOLOGY.RelationWithExplicitInverse <R L0.IsRelatedTo
         L0.InverseOf ONTOLOGY.RelationWithExplicitInverse.Inverse <R L0.IsRelatedTo

* a relation is inherited from another relation that has an inverse, in which case an inverse relation is generated if one is not defined.

      ONTOLOGY.RelationWithGeneratedInverse <R L0.IsComposedOf
      // ONTOLOGY.RelationWithGeneratedInverse.Inverse will be generated