This document is no longer maintained and is out of date. For the latest specification, see SHACL Specification.

LDOM (Linked Data Object Model) is an RDF-based modeling language that is compatible with Linked Data principles and leverages some object-oriented concepts to the Web. LDOM makes it possible to define classes together with their associated properties, and to specify additional constraints that valid members of those classes should fulfill. These additional constraints are expressed using SPARQL, yet the structural definitions of associated properties can also be used by tools without a SPARQL processor. In addition to a vocabulary for structural constraints, LDOM includes modularization features that make it possible to define new modeling terms (SPARQL functions and templates) based on executable semantics.

LDOM has a wide range of potential use cases. Its alignment with object-oriented principles means that LDOM can be used to store and share data objects that represent the "model" in applications built with a Model-View-Control architecture. In contrast to most object-oriented systems, RDF adds the value of having a unique identification mechanism for objects (via their URIs), thus also allowing data models to reference each other across the web. Through its foundation on Linked Data principles, LDOM data models are self-describing, which means that applications can dynamically learn about the behavior of objects by resolving URIs. Finally, the structural definitions of classes and properties can be exploited by user interface builders to select suitable display and input widgets.

This document introduces LDOM to people familiar with basic concepts of RDF and SPARQL. A simple model about rectangles and squares is used to introduce all major features of LDOM, including class definitions, constraints, rules, functions and templates. This document can serve as the "Hello, World" example of LDOM. This primer is a possible companion to another document (to be written) that serves as a language reference and full specification.

Introduction

LDOM (Linked Data Object Model) is a modeling language for linked data, based on a minimum sub-set of RDF Schema and object-oriented principles. Features of LDOM include:

• An RDF vocabulary to define classes together with structural declarations of the properties associated with those classes.
• Complex constraints can be expressed in SPARQL and associated with classes to validate instances of those classes.
• Rules can be used to construct new values from existing values.
• Built-in extension mechanisms, allowing users to define new high-level template languages as well as falling back to SPARQL when needed.
• An RDF vocabulary to define new SPARQL functions that can be used in any SPARQL query.

LDOM is based on RDF and is compatible with Linked Data principles, making it possible to mix LDOM declarations with models created in other semantic web languages. Other sections elaborate on the relationships of LDOM with RDF Schema and OWL.

This document uses a running example model illustrated in the following UML diagram. In a nut shell, there is a class Rectangle which has a subclass Square, both in the example namespace "ex". All Rectangles can have a width and a height, both integers greater than 0. The area of a Rectangle gets computed by multiplying width and height. Squares must have equal width and height. Rectangles can have one creator, which must be an instance of the class schema:Person.

LDOM definitions are represented in RDF and can be serialized in multiple RDF formats. The example snippets in this document use Turtle [[turtle]] notation. TODO: Future versions should have this switchable between Turtle and JDON-LD [[json-ld]]. You should be familiar with basic RDF concepts [[rdf11-concepts]] such as triples and (for the advanced concepts of LDOM) with SPARQL [[sparql11-overview]].

The Turtle source code of the complete LDOM file can be found at ldomsquare.ldom.ttl.

The LDOM system vocabulary is defined in itself, using its own LDOM File. This file also includes in-line comments for open issues as well as many technical details that are omitted in this primer for space considerations.

Within this document, the following namespace prefix bindings are used:

Class Declarations

Basic class definitions are covered by a subset of RDF Schema (see relationship with RDF Schema), as illustrated in the following example source code:

ex:Rectangle
	a rdfs:Class ;
	rdfs:subClassOf rdfs:Resource ;
	rdfs:label "Rectangle" .

ex:Square
	a rdfs:Class ;
	rdfs:subClassOf ex:Rectangle ;
	rdfs:label "Square" .

The type rdfs:Class (or its subclasses such as owl:Class) are used to declare a class. rdfs:subClassOf is used to indicate that all instances of a subclass are also instances of its superclass(es). The commonly used properties rdfs:label and rdfs:comment are recommended to declare human-readable labels and documentation.

The reuse of the standard RDF Schema terms means that LDOM models can be readily mixed with existing Linked Data models.

LDOM introduces a property ldom:abstract that can be set to true for classes that should not be directly instantiated. Furthermore, classes may be marked ldom:private to indicate that they are only meant to be used inside of the graph that they have been defined in. This can be used to discourage instantiation outside of controlled scenarios.

Note that in contrast to many object-oriented languages, RDF Schema classes may have multiple superclasses. The root class in RDF Schema is rdfs:Resource, and top-level classes in an LDOM model must state explicitly that they are rdfs:subClassOf rdfs:Resource. In other words, each valid LDOM class needs to have at least one named superclass.

Property Declarations

Object-oriented systems have a concept of properties (or fields) that hold attributes and relationships of a given class. The following sections explain how such property attachments can be represented in LDOM.

ex:Rectangle
	a rdfs:Class ;
	rdfs:subClassOf rdfs:Resource ;
	rdfs:label "Rectangle" ;
	ldom:property [
		a ldom:PropertyConstraint ;     # This type declaration is optional
		ldom:predicate ex:height ;
		ldom:minCount 1 ;
		ldom:maxCount 1 ;
		ldom:valueType xsd:integer ;
		rdfs:label "height" ;
		rdfs:comment "The height of the Rectangle." ;
	] ;
	ldom:property [
		ldom:predicate ex:width ;
		ldom:minCount 1 ;
		ldom:maxCount 1 ;
		ldom:valueType xsd:integer ;
		rdfs:label "width" ;
		rdfs:comment "The width of the Rectangle." ;
	] ;
	ldom:property [
		ldom:predicate ex:creator ;
		ldom:maxCount 1 ;
		ldom:valueType schema:Person ;
		rdfs:label "creator" ;
		rdfs:comment "The creator of the Rectangle." ;
	] ;

{
	"@context" : [
	    "http://www.w3.org/ns/ldom/context.jsonld",
	    {
	    	"ex" : "http://example.com/ns#"
	    }
	],
	
	"@graph" : [
	    {
	    	"@id" : "http://example.com/ns",
	    	"@type" : "Graph",
	    	"library" : "http://www.w3.org/ns/ldom/core",
	    	"label" : "Test Graph",
	    	"comment" : "This is a comment."
	    },
	    {
	    	"@id" : "ex:Rectangle",
	    	"@type" : "Class",
	    	"subClassOf" : "rdfs:Resource",
	    	"label" : "Rectangle",
	    	"property" : [
	    	    {
	    	    	"predicate" : "ex:width",
	    	    	"minCount" : 1,
	    	    	"maxCount" : 1,
	    	    	"valueType" : "xsd:integer",
	    	    	"label" : "width",
	    	    	"comment" : "The width of the Rectangle."
	    	    },
	    	    ...
	    	]
	    }
	]
}

ex:Rectangle
	a rdfs:Class ;
	rdfs:subClassOf rdfs:Resource ;
	rdfs:label "Rectangle" ;
	ldom:property [
		ldom:predicate ex:height ;
		ldom:maxCount 1 ;
		ldom:valueType xsd:integer ;
		ldom:minExclusive 0 ;
		...
	] ;

ex:TestRectangle
	a ex:Rectangle ;
	ex:creator ex:PersonWithEmail ;
	ex:height 6 ;
	ex:width 7 ;
	rdfs:label "Test rectangle" .

schema:Person
	ldom:inverseProperty [
		ldom:predicate ex:creator ;
		ldom:valueType ex:Rectangle ;
		rdfs:label "created rectangle" ;
		rdfs:comment "Links a Person with all rectangles that he or she created." ;
	] ...

Constraints

The property declarations shown in the previous chapter define conditions that all valid instances of a class need to fulfill. They do this in a declarative language with a limited number of properties such as ldom:maxCount. However, in many cases it is necessary to define additional conditions that are used to verify valid data, or to simply communicate the desired semantics of a model's elements.

ex:Square
	a rdfs:Class ;
	rdfs:label "Square" ;
	rdfs:subClassOf ex:Rectangle ;
	ldom:constraint [
		ldom:message "Width and height of a Square must be equal" ;
		ldom:path ex:width ;
		ldom:path ex:height ;
		ldom:sparql """
			ASK {
				?this ex:width ?width .
				?this ex:height ?height .
				FILTER (?width != ?height) .
			}
			""" ;
	] ;
.

ex:Square
	a rdfs:Class ;
	rdfs:label "Square" ;
	rdfs:subClassOf ex:Rectangle ;
	ldom:constraint [
		ldom:sparql """
			CONSTRUCT {
				_:cv a ldom:Error ;
					ldom:root ?this ;
					ldom:message "Width and height of a Square must be equal" ;
					ldom:path ex:width ;
					ldom:path ex:height 
			}
			WHERE {
				?this ex:width ?width .
				?this ex:height ?height .
				FILTER (?width != ?height) .
			}
			""" ;
	] ;
.

ex:Rectangle
	ldom:constraint [
		a ldom:ShapeConstraint ;
		ldom:predicate ex:creator ;
		ldom:some [
			ldom:property [
				ldom:predicate schema:email ;
				ldom:minCount 1 ;
			] ;
		] ;
	] ;

ex:Country
	a rdfs:Class ;
	rdfs:subClassOf rdfs:Resource ;
	rdfs:label "Country" ;
  	ldom:property [
  		a ldom:PrimaryKeyPropertyConstraint ;
		ldom:predicate ex:isoCode ;
		ldom:valueType xsd:string ;
		ldom:uriStart "http://example.org/country-" ;
		rdfs:label "ISO code" ;
    ] ...

ex:RectangleWithArea
	a rdfs:Class ;
	rdfs:subClassOf ex:Rectangle ;
	ldom:constraint [
		a ldom:OrConstraint ;
		ldom:shape1 [
			ldom:property [
				ldom:predicate ex:width ;
				ldom:minCount 1 ;
			] ;
			ldom:property [
				ldom:predicate ex:height ;
				ldom:minCount 1 ;
			]
		] ;
		ldom:shape2 [
			ldom:property [
				ldom:predicate ex:area ;
				ldom:minCount 1 ;
			]
		]
	] ;
.

ex:MyConstraint
	a ldom:GlobalConstraint ;
	ldom:message "Deprecated properties should not be used anywhere." ;
	ldom:level ldom:Warning ;
	ldom:sparql """
			SELECT ?root ?predicate ?value
			WHERE {
				?root ?predicate ?value .
				?predicate owl:deprecated ?any .
			}
		""" ;
.

Templates

LDOM Templates are "boxed" queries that can be used as values of ldom:constraint and ldom:property (as well as ldom:rule if that gets included into the standard). The role of a template is to encapsulate a reusable piece of SPARQL logic so that users do not need to reinvent the wheel. Templates hide the complexity of the underlying SPARQL query and are therefore suitable for people who are not familiar with SPARQL. The following example declares a LDOM template that can be used for constraints to express that the values of a given property shall be greater than 0.

ex:PositivePropertyValueConstraint
	a ldom:ConstraintTemplate ;
	rdfs:subClassOf ldom:TemplateConstraint ;
	rdfs:label "Positive property value constraint" ;
	ldom:labelTemplate "Values of property {?property} must be > 0" ;
	rdfs:comment """
		A template that can be used to define a LDOM constraint on a given property
		(ex:property) to make sure that the values of that property are > 0.
		""" ;
	ldom:argument [
		ldom:predicate ex:property ;
		ldom:valueType rdf:Property ;
		rdfs:comment "The property to constrain (e.g. ex:width or ex:height)." ;
	] ;
	ldom:sparql """
		SELECT (?property AS ?path) ?message
		WHERE {
			?this ?property ?value .
			FILTER (?value <= 0) .
			BIND (CONCAT("Property ", ldom:label(?property), 
				" must only have positive values, but found ",
				xsd:string(?value)) AS ?message) .
		}
		""" ;
.

In the example above, the template takes an argument, as specified by the ldom:argument. This argument is represented by a value of the property ex:property which is mapped to the variable ?property when the query executes. Here is an example that instantiates, or "calls", the template to define constraints on the properties ex:width and ex:height for all instances of the class ex:Rectangle.

ex:Rectangle
	...
	ldom:constraint [
		a ex:PositivePropertyValueConstraint ;
		ex:property ex:height ;
	] ;
	ldom:constraint [
		a ex:PositivePropertyValueConstraint ;
		ex:property ex:width ;
	] .

When a LDOM engine encounters such a constraint definition, it will execute the ldom:sparql body of the template and pre-bind the declared argument variables with the values specified in the template call. In the case of ex:height, the template's body basically becomes the following, where every appearance of the variable ?property has been replaced with the constant ex:height.

SELECT (ex:height AS ?path) ?message
WHERE {
	?this ex:height ?value .
	FILTER (?value <= 0) .
	BIND (CONCAT("Property ", ldom:label(ex:height), 
		" must only have positive values, but found ", xsd:string(?value)) AS ?message) .
}

LDOM templates make it possible to create libraries of reusable constraints and rules (and other use cases), so that users do not need to learn SPARQL. The LDOM standard comes with several of such reusable constraints including ldom:PropertyConstraint and ldom:Argument which is used by LDOM itself to declare the arguments of templates.

The example above highlights that LDOM templates can be used to create higher-level modeling languages that introduce constructs such as the ex:PositivePropertyValueConstraint above together with semantics that are executable by any LDOM-compliant engine. At the same time, high-level elements such as the property declarations can also be used by other engines that do not necessarily rely on SPARQL.

ex:SimpleFormProfile
	a ldom:Profile ;
	ldom:member ldom:AbstractCountPropertyConstraint ; # defines ldom:min/maxCount
	ldom:member ldom:AbstractValueTypePropertyConstraint . # defines ldom:valueType

Functions

LDOM Functions are similar to Templates in their syntax, but they are used to declare new SPARQL functions based on an encapsulated, reusable query. The following snippet defines a function ex:computeArea that takes a Rectangle as its argument and returns an integer that is the result of multiplying the Rectangle's width with its height.

ex:computeArea
	a ldom:Function ;
	rdfs:subClassOf ldom:Functions ;
	rdfs:label "compute area" ;
	rdfs:comment "Computes the area of a given rectangle (?arg1) as the product of its width and height." ;
	ldom:argument [
		ldom:predicate ldom:arg1 ;
		ldom:valueType ex:Rectangle ;
		rdfs:comment "The rectangle whose area to compute." ;
	] ;
	ldom:sparql """
		SELECT ((?width * ?height) AS ?result)
		WHERE {
			?arg1 ex:width ?width .
			?arg1 ex:height ?height .
		}
		""" ;
	ldom:returnType xsd:integer ;
.

In LDOM-compliant SPARQL processors, this new function can be used such as in the following example:

SELECT *
WHERE {
    ?rectangle a ex:Rectangle .
    FILTER (ex:computeArea(?rectangle) >= 100) .
}

LDOM functions have a SELECT query as their body, and this query needs to have one result variable (here: ?result). The first binding of this variable will be used as result of the function execution. The execution mechanism is illustrated in the following diagram.

Derived Properties

LDOM includes a special kind of property constraints for properties that are computed (or derived or inferred) from other values. A good example of this is the ex:area property for rectangles:

ex:Rectangle
	...
	ldom:property [
		a ldom:DerivedPropertyConstraint ;
		ldom:predicate ex:area ;
		ldom:maxCount 1 ;
		ldom:sparql "ex:computeArea(?this)" ;
		ldom:valueType xsd:integer ;
		rdfs:label "area" ;
		rdfs:comment "The area of the Rectangle, defined as the product of width x height." ;
	] ;

The ldom:DerivedPropertyConstraint above will flag a constraint violation if the value of ex:area is not equal to the result of the provided SPARQL expression.

Some LDOM implementations may also chose to use constraints of this type in a constructive way, to automatically compute missing values (but this is not covered by the standard).

Rules

(Unclear whether the WG will include inferencing, so this feature is at risk)

LDOM makes it possible to attach executable rules to classes. Rules are represented as SPARQL CONSTRUCT queries that apply to all instances of the associated class and its subclasses. In those rules, the variable ?this refers to each instance of those classes. A LDOM execution engine will make sure that ?this has the correct values. The triples that are constructed by such a rule become "inferred" and are added to the RDF graph, so that other rules can "see" the new triples. In the following example, the value of ex:area gets computed by multiplying the values of ex:width and ex:height.

ex:Rectangle
	ldom:rule [
		ldom:sparql """
			CONSTRUCT {
				?this ex:area ?area .                 # Infer ?area as a value of ex:area
			}
			WHERE {
				?this ex:width ?width .               # Get the width of ?this Rectangle
				?this ex:height ?height .             # Get the height of ?this Rectangle
				BIND ((?width * ?height) AS ?area) .  # Compute area := width * height
			}
		""" ;
	] .

The property ldom:rule is used to link a class with a rule. The values of this property must be either CONSTRUCT queries or template calls that wrap a CONSTRUCT query.

Contexts

LDOM constraints can be grouped into contexts - URIs that have the type ldom:Context. This makes it possible to indicate that certain constraints shall not apply by default, but only for certain applications or user communities. The property ldom:context links an ldom:Constraint with a context:

ex:Rectangle
	ldom:property [
		ldom:predicate dct:publisher ;
		ldom:minCount 1 ;
		ldom:context <http://example.org/trackable>
	] .

In the example above, the class ex:Rectangle has been extended with a minimum cardinality constraint on the property dct:publisher. This constraint is applicable in the provided ldom:context only, which means that it does not apply by default. However, certain applications that process ex:Rectangle instances can trigger the constraint checking in a context that includes all default constraints plus the extra constraints from the http://example.org/trackable context.

The operation that triggers the constraint checking can take included and excluded contexts as argument. Contexts can be organized into hierarchies using ldom:subContextOf, which means that whenever a super-context is requested then all constraints from its sub-contexts also apply. The built-in URI ldom:DefaultContext can be used to specify the default context, and that is also the default value if ldom:context is unspecified.

Graph Management

LDOM models are typically organized in RDF graphs (e.g. stored as files or named graphs on a database). These graphs usually have a URI that helps a system resolve the graph when it is requested. Each LDOM graph may declare an instance of ldom:Graph that has the graph URI as its URI and contains information about the graph itself, including a human-readable label and comments.

For constraint checking and rule execution, LDOM definitions often need to reference other graphs that either contain additional classes, properties and instances, or that may declare templates, rules and constraints that are needed at run-time. LDOM graphs may reference each other via two dedicated properties:

• ldom:include links a graph with other graphs that shall be included into the query graph over which LDOM constraints and rules are executed. This is a transitive property, i.e. includes of includes are also added.
• ldom:library links a graph with other (library) graphs that shall be included into the control graph that includes template definitions as well as the LDOM metamodel itself.

The separation between the graph closures via ldom:include and ldom:library allows LDOM users and implementations to optimize performance because they can exclude certain (library) graphs from the union graph that is used by the SPARQL engine. Furthermore, editing and display tools may chose to hide library graphs as they often contain rather low-level information that is not of interest to average users.

Test Case Vocabulary

It is a well-established practice in software development to define test cases that formalize the expected behavior of a piece of code. In the same spirit, LDOM includes a simple vocabulary to represent constraint checking scenarios together with expected constraint violations. These can be used by modelers to ensure that the constraint definitions are correct, and remain correct as the model evolves.

Due to space considerations, this Primer only covers a small example test case to illustrate the syntax. For details, see the yet-to-be-written formal specification. The example below instructs the LDOM engine to verify that the given resource ex:Father from the given ldom:graph shall be checked for constraints. The test passes "green" if the outcome is exactly one constraint violation that is structurally equivalent to the provided ldom:violation.

ex:TestCase
	a ldom:ResourceConstraintCheckingTestCase ;
	ldom:check ex:Father ;
	ldom:graph <http://www.w3.org/ns/ldom/test/constraint-inverse-001> ;
	ldom:ignore ldom:message ;
	ldom:violation [
		a ldom:Error ;
		ldom:root ex:Father ;
		ldom:path [ ldom:inverse ex:child ] ;
	] .

Relationships with other Languages

The design of LDOM was influenced by a number of other languages.