docs/Developer/Ontology/GraphFileFormat.md

   1 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.\r
   2 \r
   3 ## Syntax\r
   4 \r
   5 ### Indentation\r
   6 \r
   7 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.\r
   8 \r
   9 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.\r
  10 \r
  11 ### Statements\r
  12 \r
  13 A graph file describes a collection of statements. One statement is written as:\r
  14 \r
  15     Subject Predicate Object\r
  16 \r
  17 and represented graphically as\r
  18 \r
  19 ![Subject Predicate Object](Images/SubPreObj.png)\r
  20 \r
  21 Statements with the same subject can be written in the same line\r
  22 \r
  23     Subject Predicate1 Object1 Predicate2 Object2 Predicate3 Object3\r
  24 \r
  25 or with multiple indented lines\r
  26 \r
  27 ~~~\r
  28  Subject\r
  29      Predicate1 Object1\r
  30      Predicate2 Object2\r
  31      Predicate3 Object3\r
  32 ~~~\r
  33 \r
  34 These forms can also be combined\r
  35 \r
  36 ~~~\r
  37  Subject Predicate1 Object1 Predicate2 Object2\r
  38      Predicate3 Object3\r
  39      Predicate4 Object4\r
  40 ~~~\r
  41 \r
  42 Statements with the same subject and predicate can be abbreviated as\r
  43 \r
  44 ~~~\r
  45  Subject\r
  46      Predicate\r
  47          Object1\r
  48          Object2\r
  49          Object3\r
  50 ~~~\r
  51 \r
  52 In this case, there must be no objects in the same line with the predicate.\r
  53 \r
  54 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:\r
  55 \r
  56 ![Subject Predicate Object Chain](Images/SubPreObj_chain_01.png)\r
  57 \r
  58 ~~~\r
  59 Subject Predicate1 Object1\r
  60 Object1 Predicate2 Object2\r
  61 \r
  62 Subject\r
  63     Predicate1 Object1 Predicate2 Object2\r
  64 \r
  65 Subject\r
  66     Predicate1 Object1\r
  67         Predicate2 Object2\r
  68 \r
  69 Subject\r
  70     Predicate1\r
  71         Object1 Predicate2 Object2         \r
  72 \r
  73 Subject\r
  74     Predicate1\r
  75         Object1\r
  76             Predicate2 Object2\r
  77 \r
  78 Subject\r
  79     Predicate1\r
  80         Object1\r
  81             Predicate2\r
  82                 Object2\r
  83 ~~~\r
  84 \r
  85 ### Resources\r
  86 \r
  87 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:\r
  88 * Identifier\r
  89 * URI\r
  90 * Reference to a child of another resource\r
  91 * Literal value (not allowed as a predicate)\r
  92 * Data type (not allowed as a predicate)\r
  93 * A special relation: =, <T, <R, : (allowed only as a predicate)\r
  94 \r
  95 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.\r
  96 \r
  97 URI is enclosed in <>-characters and must begin with "http:". For example\r
  98 `<http://www.simantics.org/Layer0-1.0/InstanceOf>`.\r
  99 \r
 100 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.\r
 101 \r
 102 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>.\r
 103 \r
 104 Special relations are abbreviations of some Layer0 relations:\r
 105 {|\r
 106 |-\r
 107 |width="40px" align="center"| =\r
 108 | <nowiki>http://www.simantics.org/Layer0-1.0/Equals</nowiki>\r
 109 |-\r
 110 |width="40px" align="center"| <T\r
 111 | <nowiki>http://www.simantics.org/Layer0-1.0/Inherits</nowiki>\r
 112 |-\r
 113 |width="40px" align="center"| <R\r
 114 | <nowiki>http://www.simantics.org/Layer0-1.0/SubrelationOf</nowiki>\r
 115 |-\r
 116 |width="40px" align="center"| :\r
 117 | <nowiki>http://www.simantics.org/Layer0-1.0/InstanceOf</nowiki>\r
 118 |-\r
 119 |width="40px" align="center"| >--\r
 120 | <nowiki>http://www.simantics.org/Layer0-1.0/IsDomainOf</nowiki>\r
 121 |-\r
 122 |width="40px" align="center"| <--\r
 123 | <nowiki>http://www.simantics.org/Layer0-1.0/HasDomain</nowiki>\r
 124 |-\r
 125 |width="40px" align="center"| -->\r
 126 | <nowiki>http://www.simantics.org/Layer0-1.0/HasRange</nowiki>\r
 127 |-\r
 128 |width="40px" align="center"| ==>\r
 129 | <nowiki>http://www.simantics.org/Layer0-1.0/RequiresValueType</nowiki>\r
 130 |}\r
 131 \r
 132 ### Templates\r
 133 \r
 134 A template is a parametrized graph that can be defined and instantiated.\r
 135 \r
 136 A template is defines as follows:\r
 137 \r
 138 ~~~\r
 139  <name of the template> : L0.Template\r
 140      @template <parameters>\r
 141          <template body>\r
 142 ~~~\r
 143 \r
 144 for example\r
 145 \r
 146 ~~~\r
 147  L0.assert : L0.Template\r
 148      @template %type %predicate %object\r
 149          %type\r
 150              L0.Asserts _ : L0.Assertion\r
 151                  L0.HasPredicate %predicate\r
 152                  L0.HasObject    %object\r
 153 ~~~\r
 154 \r
 155 The template body is written in normal graph notation that can be refer to the parameters.\r
 156 \r
 157 A templates is applied as follows:\r
 158 \r
 159     @<name of the template> <parameter1> ... <parameterN>\r
 160         <parameterN+1> ...\r
 161             ...\r
 162         <parameterN+2> ...\r
 163             ...\r
 164         ...\r
 165 \r
 166 For example\r
 167 \r
 168     My.Type <T L0.Entity\r
 169         @L0.assert My.HasTransformation\r
 170             4.0 : My.Transformation\r
 171 \r
 172 ## Completion rules\r
 173 \r
 174 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.\r
 175 \r
 176 ### Merging equal resources\r
 177 \r
 178 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:\r
 179 \r
 180 ~~~\r
 181 L0 = <http://www.simantics.org/Layer0-1.0>\r
 182 Foo <T L0.Entity\r
 183 ~~~\r
 184 \r
 185 ### Typing literals\r
 186 \r
 187 The data type of a literal must be specified either with HasDataType statement or by instantiating a type that asserts this kind of statement:\r
 188 \r
 189     1 : L0.Literal\r
 190         L0.HasDataType @Integer\r
 191 \r
 192     1 : L0.Integer\r
 193 \r
 194 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:\r
 195 * Boolean\r
 196 * Integer\r
 197 * Double\r
 198 * String\r
 199 * BooleanArray\r
 200 * IntegerArray\r
 201 * DoubleArray\r
 202 * StringArray\r
 203 \r
 204 ### Inverse relations\r
 205 \r
 206 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.\r
 207 \r
 208 Relations will thus have inverses if:\r
 209 * an inverse is explicitly defined for a relation:\r
 210 \r
 211       ONTOLOGY.SymmetricRelation <R L0.IsWeaklyRelatedTo\r
 212          @L0.symmetric\r
 213       ONTOLOGY.RelationWithExplicitInverse <R L0.IsRelatedTo\r
 214          L0.InverseOf ONTOLOGY.RelationWithExplicitInverse.Inverse <R L0.IsRelatedTo\r
 215 \r
 216 * a relation is inherited from another relation that has an inverse, in which case an inverse relation is generated if one is not defined.\r
 217 \r
 218       ONTOLOGY.RelationWithGeneratedInverse <R L0.IsComposedOf\r
 219       // ONTOLOGY.RelationWithGeneratedInverse.Inverse will be generated\r