First Schema

Now that TreeLDR is installed we can start using it to generate schemas and code. This chapter shows how to create a basic TreeLDR project with a simple schema definition and how to use the tldrc compiler to generate a JSON Schema and JSON-LD Context.

Creating a Directory

TreeLDR files can coexist inside any project, such as a Rust or TypeScript project, along with other source files. For the sake of this example, however, we will create a dedicated directory to host all the TreeLDR files. On Linux or macOS, open a terminal, create and enter some treeldr_example directory:

mkdir treeldr_example
cd treeldr_exampl

Having a dedicated directory may also be the way to go if you wish to use the same TreeLDR definitions inside multiple projects: creating a dedicated directory and importing it inside other projects using relative paths, symbolic links, or git submodules.

Writing a TreeLDR File

Now that we have a place to work, we can start using TreeLDR. We will follow the blogging example application introduced in the introduction chapter and define a TreeLDR file that defines the two main concepts of the application: users and blog posts.

Create a schema.tldr file that will contain our schema definition. The .tldr is used to recognize TreeLDR files. Populate the file with the following content:

base <https://example.com/>;
use <http://www.w3.org/2001/XMLSchema#> as xs;

/// Blog user.
type User {
	/// Unique email identifier.
	email: required xs:string,

	/// Name of the user.
	name: xs:string,

	/// Birth date of the user.
	birthDate: xs:date
}

/// Blog post.
type BlogPost {
	/// Title.
	title: required xs:string,

	/// Post content.
	content: required xs:string
}

This file defines two types User and BlogPost describing the concepts manipulated by our application. Each user is uniquely identified by its email and has an optional name and birth date. Each blog post has a required title and content.

The first line of the file defines a base IRI for the schema. This allows TreeLDR to uniquely identify everything in the schema definition using an IRI. For instance the BlogPost type is really identified by https://example.com/BlogPost once resolved against the base IRI.

The second line of the file is a prefix definition. It specifies that xs is a shorthand for http://www.w3.org/2001/XMLSchema#. This means that later in the file, when we write xs:string for example, it is equivalent to http://www.w3.org/2001/XMLSchema#string, which is a data type that is predefined in TreeLDR to denote strings.