Comment on page
Syntax
The syntax of TreeLDR revolves around IRIs and other syntactic constructs composing those IRIs to define types, properties, and layouts.
An Internationalized Resource Identifier (IRI) is a sequence of characters uniquely identifying a resource. It is a generalization of Uniform Resource Identifiers (URIs), themselves a superset of Uniform Resource Locators (URLs). IRIs are used in the Semantic Web to define common vocabularies shared between applications allowing them to understand each other.
For this reason, in TreeLDR each entity (type, property or layout) is identified by an IRI. IRIs are written between
<>
, for instance:<https://treeldr.org/example>
An IRI can be either absolute or relative (without the scheme part). Relative IRIs are resolved against the base IRI of the document into an absolute IRI. For instance, if we consider
https://treeldr.org/
to be the base IRI of the document, then the following syntax is equivalent to the previous above:<example> // resolved into <https://treeldr.org/example>
When the relative IRI path is composed of a unique segment, then it is possible to omit the surrounding
<>
. So example
here is equivalent to <example>
which is itself equivalent to <https://treeldr.org/example>
considering the current base IRI.The base IRI of a document is defined using a
base
item:base <https://treeldr.org/>;
To avoid repetitions, it is possible to define prefixes in the document that can be then used to shorten the size of IRIs. Once a prefix is defined, then
prefix:suffix
syntax can be used. The final IRI is obtained by concatenating prefix
with suffix
(which is different from relative IRI resolution). For instance, let's consider the following tldr
prefix definition:use <https://treeldr.org/> as tldr;
Then the
tldr:example
syntax is equivalent to <https://treeldr.org/example>
. It is not possible to use compact IRIs between <>
.A TreeLDR document is composed of a list of items. An item can be one of the following:
- A base IRI declaration, specifying the base IRI of the document;
- a prefix definition, used in compact IRIs throughout the document;
- a property definition; or
- a type definition;
- a layout definition.
A base IRI definition is required to use relative IRI references in a document. Its syntax is as follows:
base <IRI>;
A prefix definition is used to define prefixes later used to expand compact IRIs occurring in the document. Its syntax is as follows:
use <IRI> as prefix;
A new property can be defined with the
property
keyword.property <IRI> : Range;
Here
Range
is a type expression defining the range of the property. It is required unless its range has already been defined elsewhere. For instance:base <https://example.org>;
use <https://example.org/> as example;
// The following three definitions are equivalent.
property <https://example.org/myProperty>;
property example:myProperty;
property myProperty;
A new type can be defined with the
type
keyword.type <IRI>;
For instance:
base <https://example.org>;
use <https://example.org/> as example;
// The following three definitions are equivalent.
type <https://example.org/myType>;
type example:myType;
type myType;
It is possible to specify the properties for which the defined type is the domain by listing them between braces
{}
:type <IRI> {
<property/IRI/1>,
...
<property/IRI/n>,
}
In this case, the ending
;
is removed.For instance:
type MyType {
<https://example.org/myProperty1>,
example:myProperty2,
myProperty3
}
Between braces, the base IRI changes for the IRI of the defined type. Here
myProperty3
is resolved into https://example.org/MyType/myProperty
and not into https://example.org/myProperty
.Properties occurring inside a type definition do not need a
property
definition, however in this case the range of the property needs to be defined inside the type.type MyType {
property: Range
}
Type expressions are not affected by the base IRI change inside
{}
. Here Range
is resolved into https://example.org/Range
.TreeLDR also allows the definition of types by composition (union, intersection, restriction). The dedicated syntax for each composition operator is detailed in the associated section of this book.
A new layout can be defined with the
layout
keyword.layout <IRI> for <Type>;
Note the
for
clause specifying for which type this layout is defined. This clause is optional if you want to define an orphan layout, without any semantics attached.For instance:
base <https://example.org>;
use <https://example.org/> as example;
// The following three definitions are equivalent.
layout <https://example.org/myLayout> for MyType;
layout example:myLayout for MyType;
layout myLayout for MyType;
The above syntax does not describe the actual content of the layout. There are many different sorts of layouts. The simplest and most common layout is the structure layout. Similarly to a type definition with property, a structure layout is defined using braces
{}
:layout <IRI> for <Type> {
<property/IRI/1> as fieldName1 : LayoutExpr1,
...
<property/IRI/N> as fieldNameN : LayoutExprN
}
A structure layout is composed of a list of fields. Each field is composed of the following:
- a property IRI specifying the semantics of the field;
- a name; and
- a layout expression specifying the layout of the field.
For instance:
layout MyLayout for MyType {
<https://example.org/myProperty1> as a : Layout1,
example:myProperty2 as b : Layout2,
myProperty3 as c : Layout3
}
Between braces, the base IRI changes into the IRI of the defined type, but only for properties IRIs. Here
myProperty3
is resolved into https://example.org/MyType/myProperty
and not into https://example.org/myProperty
, but Layout3
is resolved into https://example.org/Layout3
.Specifying the name of each field is optional. If unspecified, the IRI of the property is used to derive an appropriate name for the field. Similarly, if the layout of the field is not specified, a default layout is derived using the default layout of the property range (if any).
As said earlier, TreeLDR provides all sorts of layouts (primitive, structure, enumeration, union, intersection, array, etc.). The full list of layouts and their associated syntax is provided in the Layouts section.
Last modified 1yr ago