JSON-LD Context

JSON-LD is a JSON-based format to serialize Linked Data. It adds semantics to a JSON document by introducing new keywords and allows one to embed a JSON-LD context to the document that defines the vocabulary used in the document. For instance, here is a simple JSON-LD document.

{
	"@context": {
		"foo": "https://example.com/property"
	},
	"foo": "value"
}

The @context value defines the JSON-LD context used in the document. Here it defines that the foo term designates the https://example.com/property. This means that this document is semantically equivalent to the following:

{
	"foo": "https://example.com/property"
}

TreeLDR allows you to generate JSON-LD contexts from a TreeLDR schema, and import some JSON-LD contexts that can be interpreted as a schema into a TreeLDR schema.

Generating a JSON-LD Context

For now, only type scoped contexts are supported, even if no rdf:a property is present in the layout.

Generating a JSON-LD context is done by using the json-ld-context subcommand of the command line utility after the list of inputs, and by specifying what layout should be embedded into the context.

tldrc -i input1 ... -i inputN json-ld-context Layout1 ... LayoutN

For instance, consider the following layout for the schema:BlogPosting type:

// example/basic_post.tldr
base <https://example.com/>;
use <https://schema.org/> as schema;

layout BasicPost for schema:BlogPosting {
	/// Title of the post.
	schema:title: xs:string,

	/// Content of the post.
	schema:body: xs:string
}

Use the following command to generate JSON-LD Context:

tldrc -i example/basic_post.tldr -i example/schema.org.tldr json-ld-context https://example.com/BasicPost

The JSON-LD Context generated:

{
	"title": "https://schema.org/title",
	"body": "https://schema.org/body"
}

This context can then be safely embedded into a BasicPost JSON-LD instance as its context:

{
	"@context": {
		"title": "https://schema.org/title",
		"body": "https://schema.org/body"
	},
	"title": "Title",
	"body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
}

Type Scoped Contexts

In the example above, properties are defined for the entire document. Their scope is not limited to nodes representing BasicPost objects, and could potentially conflict with other term definitions. To avoid this, JSON-LD allows us to define type scoped contexts that only apply to nodes of a given type. The downside is that the type must appear in the node itself.

One can ensure that by adding the rdf:type property to the layout.

layout BasicPost for schema:BlogPosting {
	/// Include the type.
	rdf:type,

	schema:title: xs:string,
	schema:body: xs:string
}

This will generate the following context, with the BasicPost type scoped context.

{
	"type": "@type",
	"BasicPost": {
		"@id": "https://schema.org/BlogPosting",
		"title": "https://schema.org/title",
		"body": "https://schema.org/body"
	}
}

The name of the layout is used to define the type scoped context. The rdf:type property has been translated into a @type keyword alias. This can be avoided by renaming the property into the keyword itself:

layout BasicPost for schema:BlogPosting {
	/// Include the type.
	rdf:type as @type,

	...
}

This will generate a similar context, but without the type term definition.

{
	"BasicPost": {
		"title": "https://schema.org/title",
		"body": "https://schema.org/body"
	}
}

This context can then be safely embedded into a BasicPost JSON-LD instance as its context:

{
	"@context": {
		"BasicPost": {
			"title": "https://schema.org/title",
			"body": "https://schema.org/body"
		}
	},
	"@type": "BasicPost",
	"title": "Title",
	"body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
}

Note how the @type field with the BasicPost value is now required to use the type scoped context.

Importing a JSON-LD Context

JSON-LD context import is not implemented yet.

Last updated