Graph File Format

Textual graph format is used to write ontologies in Simantics platform. Graph compiler translates textual format to binary transferable graphs 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

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

Subject Predicate1 Object2 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 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 <http://somedomain/A>, then A.Foo referes to <http://somedomain/A/Foo>. If URI contains non-alphanumerical characters, the name can be enclosed in double quotes. For example A."Cul-de-sac" refers to <http://somedomain/A/Cul-de-sac>.

Special relations are abbreviations of some Layer0 relations:

=	http://www.simantics.org/Layer0-1.0/Equals
<T	http://www.simantics.org/Layer0-1.0/Inherits
<R	http://www.simantics.org/Layer0-1.0/SubrelationOf
:	http://www.simantics.org/Layer0-1.0/InstanceOf

Templates

Templates is a parametrized graphs 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