Syntax

The syntax of TreeLDR revolves around IRIs and other syntactic constructs composing those IRIs to define types, properties, and layouts.

Internationalized Resource Identifiers (IRI)

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/>;

Compact IRIs

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 <>.

Items

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.

Base IRI definition

A base IRI definition is required to use relative IRI references in a document. Its syntax is as follows:

base <IRI>;

Prefix Definition

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;

Property Definition

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;

Type Definition

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;

Type Properties

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.

Embedding Properties Definitions

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.

Composite Types

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.

Layout Definitions

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;

Structure Layout

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).

Other Layouts

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.