Publishing RDF/SHACL Graphs as GraphQL

This document (for maintainers of RDF/SHACL data models) explains how RDF graphs can be published through the GraphQL services of TopBraid. In a nutshell, one or more GraphQL schemas are automatically generated using data shape definitions in the Shapes Constraint Language (SHACL). These SHACL shapes may be automatically generated using other input GraphQL schemas, enhancing them in the process with numerous features to query data stored in an RDF dataset. SHACL data shapes can also be generated from other input formats supported by TopQuarant's products. The features available to end users are described in Querying RDF Graphs with GraphQL.

Introduction

TopBraid products can take a SHACL shapes graph as input and produce an executable GraphQL schema that supports queries against data in RDF graph databases.

The SHACL shape definitions may originate from existing third-party data models, or shapes that were created specifically to expose certain views on existing data. Multiple shape definitions may cover the same underlying RDF graph data. GraphQL schema syntax itself may be used to define shapes, see GraphQL Schemas to RDF/SHACL.

Using SHACL node shape definitions, the processor generates GraphQL object types with fields derived from property shapes. The fields are augmented with various arguments for filtering, aggregations, ordering and paging, transformations and deriving values.

The resulting GraphQL services provide an easy-to-use yet highly flexible and powerful query language to produce JSON views on any RDF-based data such as enterprise knowledge graphs. It also enables the use of GraphQL together with existing RDF technology such as SPARQL, rule engines and SHACL data validation components.

Generating GraphQL Schemas

An RDF graph may contain thousands of classes or data shapes. A GraphQL service that includes all of them at once would quickly become unusable. In order to instruct the processor on which shapes and classes shall be exposed via GraphQL, the starting point is an instance of the class graphql:Schema. This schema instance must use the following properties to include or exclude shapes:

The algorithm that produces the set of published shapes first collects all shapes or classes defined using the graphql:publicXY and graphql:protectedXY properties above from the schema and also all its transitive values of owl:imports and rdf:type properties. Then it removes those that are marked via graphql:privateShape.

All published shapes can be queried via GraphQL and are automatically exposed by the root query object. Those that are marked protected can not be queried from the root query but can be reached and traversed from other object types. Here is an example:

ex:MySchema
	a graphql:Schema ;
	graphql:publicShape ex:Human .

ex:Human
	a sh:NodeShape ;
	sh:property [
		sh:path ex:id ;
		sh:datatype xsd:string ;
		sh:minCount 1 ;
		sh:maxCount 1 ;
		sh:order "0"^^xsd:decimal ;
		graphql:isIDField true ;
	] ;
	sh:property [
		sh:path ex:name ;
		sh:datatype xsd:string ;
		sh:minCount 1 ;
		sh:maxCount 1 ;
		sh:order "1"^^xsd:decimal ;
	] ;
	sh:property [
		sh:path ex:height ;
		sh:datatype xsd:decimal ;
		sh:maxCount 1 ;
		sh:order "2"^^xsd:decimal ;
	] ;
	sh:property [
		sh:path ex:friends ;
		sh:node ex:Human ;
		sh:order "3"^^xsd:decimal ;
	].

If you have used the automated GraphQL Schemas to RDF/SHACL conversion to produce the SHACL shape above, then the input shape might have looked as follows:

type Human {
	id: ID!
	name: String!
	height: Float
	friends: [Human]
}

The processor will internally generate the following GraphQL schema:

schema {
	query: RootRDFQuery
}

type RootRDFQuery {
	humans (... filters etc, see later...): [Human]
	... generated fields for aggregations and introspection ...
}

type Human {
	uri: ID!
	label: String!
	id (... filters etc...): ID!
	name (... filters etc...): String!
	height (... filters etc...): Float
	friends (... filters etc...): [Human]
	... generated fields for aggregations, derived values ...
}

As shown above, the system automatically produces a root query object that has fields for every public shape, with a name that is basically the plural form of the shape name. These root query fields can take a large number of arguments to select which of the matching objects shall be returned, but we get to these details in Querying RDF Graphs with GraphQL.

Completing this introductory example, here is an example GraphQL query against this schema, returning all humans where the name starts with L, and all their friends, translating the height from meters to feet.

{
	humans (where: {name:{pattern:"^L"}}, orderBy: name) {
		id
    	name
		height (transform: "$height / 0.3048")
		friends {
			id
			name
		}
	}
}

A possible result JSON would be:

{
	"data": {
		"humans": [
			{
				"id": "1003",
				"name": "Leia Organa",
				"height": 4.921259842519685,
				"friends": [
					{
						"id": "1002",
						"name": "Han Solo"
					},
					{
						"id": "1000",
						"name": "Luke Skywalker"
					}
				]
			},
			...
		]
	}
}

Objects and Fields

For each published node shape in a schema, the processor will create one GraphQL object type as described in the following sections.

# A resource for which only the URI and label can be queried.
type _Resource {
	uri: ID!
	label: String!
}

Defining multiple GraphQL Schemas

A dataset may contain many named graphs and heterogeneous data. It is possible to define multiple GraphQL schemas for the same data, and in the same shapes graph. Each instance of graphql:Schema can either be identified by its URI or by its graphql:name. This is best explained through an example.

ex:MySchema
	a graphql:Schema ;
	graphql:name "starwars" ;
	graphql:publicShape ex:Human .

The above schema is available through the URL schema [server]/graphql/[dataset]/starwars.

If a schema does not carry a graphql:name then it can be accessed via the qname of its URI, replacing : with _: [server]/graphql/[dataset]/ex_MySchema would also work.