Return of the Jedi: Ontotext Platform Metamorphosis

Shiny new ONTOTEXT PLATFORM features, including support for declarative Role-Based Access Controls, GraphQL Mutation, GraphQL Federation, GraphQL schema generation (from RDFS/OWL), DockerHub Images, Helm Charts, and Platform monitoring graphs and visualisations.

April 21, 2020 22 mins. read Jem Rayfield

Ontotext Platform 3.1

Luke Skywalker has returned to his home planet of Tatooine in an attempt to rescue his friend Han Solo from the clutches of the vile gangster Jabba the Hutt. Little does Luke know that Ontotext has secretly improved its armored Platform making it more powerful than its first incarnation. This ultimate weapon will spell certain doom for the small band of rebels still struggling to ignore GraphQL over RDF.

My previous post A New Hope: The Rise of the Knowledge Graph examined the platforms GraphQL query capabilities over an RDF Star Wars data set.

This follow up blog post discusses some of the exciting new features released in version 3.1. Including Role-Based Access Controls (RBAC), GraphQL Mutation, GraphQL Federation, OWL to GraphQL schema transformation, DockerHub, Helm Charts, automated provisioning, and Platform Monitoring plus alerting.

Building your own knowledge graph just got much, much easier!

New call-to-action

GraphQL with RBAC

The Platform’s Semantic Object service provides an autogenerated GraphQL API. A GraphQL API that allows a client to query and mutate knowledge graph data, the way they want, when they want it.

However, sometimes it is prudent to restrict knowledge graph data access to authorised users. The Platforms RBAC is managed by a declaratively configured access-control mechanism that uses roles and action privileges.

The Platforms Semantic Object Modeling Language (SOML) schema grammar now introduces RBAC. Ensuring that when a GraphQL query is invoked from a client, the Platform’s Semantic Objects service controls which information is returned, and in the case of a mutation the data that can be modified.

When enabling authentication, authorisation, and RBAC, the Platform by default removes all access privileges (read/write/delete) to all objects and object properties. Therefore to grant access you must augment a schema with Declarative RBAC’s that allow an administrator to grant access to Objects, Nested Objects, and Object properties.

Using the Platform’s RBAC, it is possible to segregate duties within a team and grant a controlled level of access to specific users and roles in order that they have just enough access to perform their jobs.

GraphQL Query with RBAC

The following GraphiQL IDE is hardwired with an access token and role that has been granted with read access to only those Star Wars characters classified as voc:Hutt or voc:Droid it also provides access to a characters voc:Species voc:name . No further access is granted.

SOML Role definitions grant read action privileges using a RBAC grammar as follows (object-regex)/(property-regex)/read.

The following example role definition should be self explanatory:

      description: "Can read all Droid and Hutt object properties, 
      plus the Species name property. nothing else.."
      actions: [

You can try out this RBAC constrained query here:

query droidAndHuttCharacters { character(where: {OR: [{species: {name: {EQ: “Droid”}}}, {species: {name: {EQ: “Hutt”}}}, {species: {name: {EQ: “Wookiee”}}}]} orderBy: {name: ASC}) { name species { name } } }



When this GraphQL query is invoked, the Platform restricts the data that is returned and includes access warnings that indicate those objects/properties that are authorised. In this particular case, the role DroidHuttRead does not have sufficient permissions to retrieve voc:Wookie objects. voc:Wookie objects are therefore denied and removed from the response.

You may want to try the same query with an IDE that is hardwired/configured with a different role with a different set of privileges. In this case the role WookieeRead has read access to voc:Wookie objects but does not have any access to voc:Droid objects or voc:Hutt or voc:Droid objects.

      description: "Can read all Wookiee properties and Species name. Nothing else.."
      actions: [

Again you may try out the same query with a different set of RBAC restrictions here:

query wookieeCharacters { character(where: {OR: [{species: {name: {EQ: “Droid”}}}, {species: {name: {EQ: “Hutt”}}}, {species: {name: {EQ: “Wookiee”}}}]} orderBy: {name: ASC}) { name species { name } } }



You will now notice that the permission warnings indicate access can only be granted to objects of type voc:Wookie. Thus voc:Droid and voc:Hutt objects are removed.

The Platform makes use of an open source identity service, namely Fusion Auth. For this blog post the Platform is deployed using the OAuth protocol authentication flow. This authentication process provides JWT tokens that include role claims used downstream by the Semantic Objects RBAC constraint and restriction logic.

If you want to try any of the Platform services, they can be downloaded from Ontotexts Docker Hub, then orchestrated and deployed to a Kubernetes cluster using the provided Helm charts. Once the containers are deployed, spinning up and provisioning users, roles and schemas is as simple as running the Platforms command line tool OPCTL.

You may want to avoid using this blog posts hardwired embedded GraphiQL instances and instead try out the complete authentication and authorisation flow. It is included within the Platforms extended GraphiQL service allowing you to swap users, authenticate, and invoke GraphQL queries and mutations by using credentials, such as:

Try these credentials to read voc:Droid and voc:Hutt objects

password: 1234567890

Or perhaps retreive some voc:Droid objects using these credentials:

password: 1234567890

You can login and test this out by clicking here:

The Platforms RBAC can also control access to particular object properties and indeed nested object properties.

For example, the following GraphiQL IDE is hardwired with the role DroidHomePlanetNotEyesRead that grants access to voc:Droid objects, voc:Species voc:name and voc:Droid voc:homeWorld properties linking it to voc:Planet objects. But does not grant access to voc:Droid voc:eyeColor|voc:hairColor|voc:skinColor properties:

      description: "Can read Wookiee"
      actions: [
      notActions: [

You can try out this RBAC constrained query here:

query droidsAndHomeWorld { droid(orderBy: {name: ASC}) { name eyeColor homeworld { name gravity } species { name } } }



You will notice the permission warnings indicate that properties voc:Droid voc:eyeColor and voc:Planet voc:gravity are removed because the `role` DroidHomePlanetEyesRead does not have access to read those properties.

GraphQL Mutation with RBAC

SOML role definitions grant write (create|update) and delete action privileges using a RBAC grammar as follows (object-regex)/(property-regex)/(write|delete).

RBAC’s ensure that the data GraphQL mutations are able to modify are controlled by JWT token role claims.

Before using your lightsaber to blast and vaporize all of the StarWars data it seemed appropriate to augment the schema and indeed data with some additional classes, properties, and WikiData individuals.

The data model now introduces voc:FilmRole that joins a StarWars voc:Character (such as Luke Skywalker) and a voc:Person (such as Mark Hamil) with a voc:role (cast) to a particular voc:Film (such as A New Hope). In addition introducing location data in the form ofvoc:Country and voc:Location.


The Star Wars RDFS/OWL schema is avalible for download here and the RDF instance data is also available

The OWL2SOML generated Semantic Objects schema can be downloaded here. Be sure to refer to the SOML reference guide to learn more.

But, before you go ahead and create/update voc:Person, voc:Country and voc:Location instances, first, you may want to take a look at the GraphQL representation of Mark Hamils role within the film A New Hope:

query LukeSkyWalkerPersonInNewHope { filmRole(where: {AND: [{character: {name: {IRE: “luke.*walk.*”}}}, {film: {name: {IRE: “.*Hope.*”}}}]}) { person { id name birthPlace { id name } citizenOf { id name } } character { name } film { name } } }



By now you may also want to create and update your own StarWars data. I have added the following PersonCountryLocation role limiting GraphQL mutations as follows:

      description: "Can read and write People, Locations, and Countries.
      nothing else.."
      actions: [

The following GraphQL mutation will create a new voc:Person “Jem Rayfield” with a nested voc:Country and voc:Location.

mutation createJemRayfield { create_Person (objects: [ { id: “″ rdfs_label: {value:”Jem Rayfield”, lang: “en-GB”} birthDate: “2020-01-01” birthPlace: { location: { id: “″ rdfs_label: {value:”Arcadia”, lang: “en-GB”} } } citizenOf: { country: { id: “” rdfs_label: {value: “Mountains of Solace”, lang: “en-GB”} } } } ]) { person { id name birthDate birthPlace { id name } citizenOf { id name } } affected_objects { kind ids } } }



Don’t be surprised if the dark side of the force removes your freshly curated data. A mouse droid has been programmed to perform data cleansing tasks, (from time to time) across the blog posts Platform facilities. They beep to themselves as they perform small data repairs, removing RBAC controlled data so that blog readers are less likely to be embarrassed by data defacing.

You can try out your own RBAC’d GraphQL mutations using the following credentials and referring to the GraphQL mutations tutorial

password: 1234567890

The Platform’s semantic object service provides an autogenerated and controlled GraphQL mutation API that supports:

  • Semantic Object creation
  • Nested Semantic Object creation
  • Nested Semantic Object creation with filter expressions
  • Semantic Object updates
  • Nested Semantic Object updates
  • Nested Semantic Object updates with filter expressions
  • Semantic Object deletion
  • Multiple Mutations (and indeed Queries) per GraphQL request

However, this blog post has not provided any delete privileges or write privileges to other object types. So, if you want to get creative with your data and try out your own GraphQL mutations, I suggest requesting a license from here to start playing with the docker images and then following the Semantic Objects quick start guide and the GraphQL mutation tutorial.

RBAC with Value filters (Roadmap)

We are currently implementing SOML RBAC grammar extensions that will allow one to declare data value action constraints. These constraints will use the Platform’s rich GraphQL filter syntax.

For example, the following role definition grants GraphQL queries to retrieve voc:Human objects if they have blue voc:eyeColor property values.

  actions: [
    'Human/*/read/(where: {eyeColor: {EQ: "blue"}})'


Mutation Constraints (Roadmap)

In addition, richer (SHACL based) closed world Semantic object constraints are currently under development. The work involves adding advanced SHACL features within Ontotext’s GraphDB, and at the same time generating richer SHACL shapes from SOML declarations in order that we can introduce GraphQL mutation restrictions such as:

  • Object and property cardinality
  • Object declarative referential integrity
  • Object property value constraints
  • Etc…

GraphQL Federation

The Platform introduces GraphQL federation to allow Platform users to compose and aggregate multiple GraphQL schemas.


To get the most out of GraphQL, your organization should expose a single data graph that provides a unified interface for querying all of your backing data sources. This allows clients to fetch data from any number of sources simultaneously, without needing to know which data comes from which source


GraphQL schema federation allows one to spread the definition of a particular object type across service boundaries, which aligns well with microservice bounded context architectural approaches. Allowing object types to be declared in this way provides a lot of flexibility, it also gives a federation gateway (such as Apollo) the information it needs to join services without forcing developers to handcraft remote join logic.

The Platform’s Semantic Objects service implements the Apollo GraphQL Federation specification to support a single composite, controlled (rbac) lense across your data. The Platform provides an extended Apollo GraphQL federation gateway, that provides some notable extensions:

  • RBAC participation
  • transaction/log aggregation and correlation
  • health, good to go status checks and monitoring
  • declarative federation configuration

The Platform provided gateway is responsible for aggregating and consolidating GraphQL schemas that conform to the federation specifications. The Semantic Objects service automatically adds all the necessary GraphQL directives into its auto-generated GraphQL schema including object @keys, object resolution, and schema definition language introspection queries in order that it can be composed. The federation gateway will merge objects across schemas using federation directives, it is then able to keep track of which services a particular object or property resolves from. The gateway service automatically splits and joins a single GraphQL query across multiple GraphQL services to resolve object property values across a set of federated endpoints.

The following diagram intends to depict GraphQL federation across the Platform’s Semantic Object service and a simple example of an Apollo JS GraphQL service.

The Semantic Object service declares the Planet object type and its ID as its federation @key (automatically). The example service extends the Planet object type adding a Planet.mass property and a calculated Planet.calculatedGravity property. The calculation makes use of Planet object property values such as Planet.diameter that are marked as (@requires and @external and served/retrieved from the Semantic Objects service.

You can find a very simple example Apollo GraphQL server illustrating this schema extension and federation capability at Ontotexts GitHub Repository. The guts of the service are contained in this Javascript file. Please give it a try, to simplify things. You can also download and play with a docker image availible here.

The following RBAC role definition grants GraphQL query privileges to all voc:Planet object properties except for the voc:gravity property, which has been restricted and indeed superseded by the calculated/federated voc:calculateGravity property served from the example service.

      description: "Can read all Planet object properties, 
      except for the non-calculated gravity valuey. nothing else.."
      actions: [
      notActions: [

You can examine the example services GraphQL schema by running the following query. This GraphQL query follows the Apollo GraphQL _service.sdl query specification, which returns the full GraphQL SDL including all the required federation directives such as @requires, @key and @external

query { _service { sdl } }



You can try out a federated GraphQL query across both the Semantic Objects service and the example Apollo GraphQL service below. The voc:calculatedGravity property value is calculated and extended within the Example service Javascript where the code makes use of an @external property value voc:diameter served from the Semantic Objects service.

query planetGravityCalc { planet(where: {diameter: {GT: 10}}) { id name diameter mass calculatedGravity } }



This Platform release allows object types declared within a SOML schema to be extended in federated services. We are currently working to improve this with object property extensions and calculations (JS functions) applied as SOML declarations and augmented directly within Semantic Objects.

SOML and GraphQL Schema from RDFS/OWL

Web Ontology Language (OWL) and SOML are two very different languages that have a similar purpose – to provide a language and grammar for describing and modeling data.

SOML the Platform’s primary modeling language was designed so that it can target various technologies (RDFS/OWL/SHACL/GraphQL/etc), this allows the Platform to innovate freely, adding features (such as RBAC) that may not be supported or expressed easily within source or target meta-languages.

A lot of Platform users already have OWL ontologies describing their data. With this in mind the Semantic Objects service has now introduced OWL2SOML endpoints in order that you can transform existing ontologies into SOML schemas. Once transformed these schemas can then be augmented easily with Platform features such as RBAC or constraints.

When you are ready with your SOML (transformed and possibly augmented), you can bind the schema to the Semantic Objects service to generate a GraphQL schema and API automatically.

The OWL2SOML endpoint accepts a set of ontology files for transformation. The files must be in one of the following RDF formats [Turtle, Trig, RDF/XML, or JSON-LD]. RDF schemas require appropriate prefixes so that the transformation process can obtain sensible GraphQL class and property names. You can find out more information about the OWL requirements and the OWL2SOML transformation process here.

Please give it a try. You can transform the StarWars RDFS/OWL into SOML, by first, downloading the StarWars Ontology

If you are a Postman user, you can then make use of this Postman collection to authenticate and transform the OWL into SOML, subsequently binding as a GraphQL API.

Alternatively, you can use some command-line yoda, with curl and jq. First, get an authorisation token by using the following curl command:

TOKEN=$(curl --location --request POST \ 
   "" \       
   --header 'Content-Type: application/json' \
   --data-raw '{
     "loginId": "",
     "password": "1234567890",
     "applicationId": "672ca7b3-c372-4df3-82d8-9a1a0d7d68c1"
  }' | jq -r '.token'

Then, POST the StarWars Ontology schema to the OWL2SOML endpoint to transform it by using this curl command:

curl --location --request POST '' \
     --header 'Content-Type: multipart/form-data' \
     --header "Authorization: Bearer ${TOKEN}" \
     --form 'files=@starwars-ontology.ttl' \
     --form 'dryrun=true' \

As you can see the StarWars Ontology, Classes, subClassOf, domain, range, etc are transformed into a SOML YAML schema. A SOML that contains Objects and properties representing the StarWars Ontology. Additional declarations such as RBAC can then be added before binding to Semantic Objects for an auto-generated GraphQL API.

Unfortunately, the user credentials provided do not grant access to bind the generated SOML schema as a GraphQL API, because the Star Wars Demo GraphQL endpoint and indeed this blog post would most likely get vaporized by overly enthusiastic modeling attempts!

So, if you want to get creative with your RDFS/OWL to SOML and GraphQL API generation, I suggest requesting a license from here then start playing with the docker images and then follow the OWL2SOML guide

Docker Hub, Helm Charts and provisioning

Ontotext Platform is available on Docker Hub, the largest container community, to make it very easy to deploy the Platform Docker containers. The images are fully supported by Ontotext, with automated builds, to ensure that you have the latest stable updates and builds.

Docker, Kubernetes and Helm charts, make Platform deployment easy, standardized and reusable. We introduce these tools to improve developer productivity, reduce deployment complexity, enhance operational readiness, and speed up the adoption of the Platform and indeed knowledge graphs within your organisation.

Helm Charts are provided, along with our Ontotext Platform provisioning CLI OPCTL so that you have the ability to leverage the Platforms Kubernetes packages, and default configurations through the click of a button or a single CLI command. This avoids a lot of wasted effort deploying and maintaining a Kubernetes application ― and the complexity involved, managing components such as pods, namespaces, RBAC policies, and deployments.


Deploying the Ontotext Platform to Google Cloud is as simple as running a helm install. The default helm chart will deploy the platform to Google Cloud Kubernetes Engine as follows:

But of course, it is simple enough to use and deploy the platform on AWS EKS or Azure EKS.

So, if you want to get creative with your data and try out your own GraphQL over RDF I suggest requesting a license from here to start playing with the docker images.


Faults that give rise to sometimes critical situations may appear. To detect, prevent and react to failures, and indeed understand performance, it is very convenient to have a good monitoring tool.

Ontotext Platform monitoring is able to monitor all Platform infrastructure/resources, services, and even query metrics.

The Platform gathers metrics from all of the services via Telegraf and stores the collated time series data in InfluxDB. In this way, the Platform’s performance, and health can be monitored in near real-time via Grafana dashboards.


To simplify the understanding of metrics and alerts, the Platform provides a set of preconfigured monitoring, health-check, and alerting dashboards that are provisioned by the Platform deployment tooling.

X-Wing Dashboard


Monitoring GraphQL Query performance

It may be useful to examine the Platform’s GraphQL query or mutation execution patterns to understand performance bottlenecks or perhaps resource constraints. A dashboard is provided for examining the phases of named GraphQL query invocations, allowing you to examine the performance and latency of the various phases of execution, including parsing, validation, transformation, compilation/transpile, and execution.

Please take a look and log into Grafana using the following credentials.

password: 1234567890

WARNING: Make sure you test out some GraphQL queries, whilst taking a look at the graphs otherwise you may not see any statistics at all!

Please navigate to this Query Execution Dashboard or click on the chart image below:

Service Resource Metrics

Service Resource Monitoring allows you to monitor the Platform’s service system resources such as CPU Usage, Memory Consumption, I/O, Network, Disk Usage, Process, etc. Helping you understand the Platform’s system resource usage enabling effective capacity planning.

When used in conjunction with monitoring such as query metrics you get a good insight into the Platform. Out of the box, provisioned dashboards include:

Further information about these dashboards can be found here

Healthchecks and Alerting

Application health is at the core of most businesses. Lost revenue and negative customer experiences come with application or service downtime. Therefore it is important that a Platform provides application and service health checks and effective Platform monitoring to allow you to detect issues before they become full-fledged outages.

All Platform services provide a standard health check and good to go endpoint that is continuously monitored, used to auto-restart or scale, and recorded for visualisation and alerting within Grafana.

All health alerts can easily be configured to send emails/slack/SMS messages when something goes wrong.

You can take a look at a pre-packaged Platfom health dashboard here

May the force be with you

We have introduced GraphQL federation so that you can access all of your organization’s data as a knowledge graph using aggregate GraphQL queries, even if your data lives in separate places.

RBAC so that you have declarative access control across a single knowledge graph lens and entry point.

GraphQL mutation to provide a flexible, simple controlled way for you to modify data within your knowledge graph.

Monitoring dashboards and alerts so you are informed and alerted when things go wrong or performance becomes latent.

Docker images, helm charts, and automated provisioning so that you can spin up the Platform very quickly with minimal effort.

OWL2SOML to transform your existing OWL models into Semantic Object GraphQL APIs.

But we are not finished yet…watch this space force for more galactical features in the near future.

Request Ontotext Platform!

Article's content

Head Of Architecture at Allen & Overy

Jem is an experienced software practitioner, architect, and director of development. He has proven himself as one of the best semantic technology solution architects previously working at the BBC and the FT. As Chief Solution Architect, he is helping Ontotext to deliver a comprehensive analytics and publishing platform.

Declarative Knowledge Graph APIs

Stop wasting time, manually building data access code. Let the Ontotext platform auto-generate a fast, flexible, and scalable GraphQL API over your RDF knowledge graph.

Star Wars: Knowledge Graph Federation

Read how you can use Ontotext Platform’s GraphQL federation capabilities to provide a unified interface for querying all of your data sources in context and allow clients to fetch data from any number of data sources simultaneously, without needing to know which data comes from which source.

Return of the Jedi: Ontotext Platform Metamorphosis

Read how we armed the Ontotext Platform with new tools to make navigating through the Star Wars knowledge graph data even easier

A New Hope: The Rise of the Knowledge Graph

Read about how Ontotext Platform utilizes its potential to lower the entry barrier to knowledge graph data in an exploration of the Star Wars universe.

Ontotext Platform: A Global View Across Knowledge Graphs and Content Annotations

Jem Rayfield provides insights into the Ontotext Platform and how GraphDB’s MongoDB connector unifies the platform’s knowledge graph and annotation RDF stores.

Ontotext Platform: Semantic Annotation Quality Assurance & Inter-Annotator Agreement

Jem Rayfield, Chief Solution Architect at Ontotext, provides technical insights into the Ontotext Platform and in particular the role of its Curation Tool.

Ontotext Platform: Knowledge Quality via Efficient Annotation at Scale

Jem Rayfield, Chief Solution Architect at Ontotext, provides technical insights into the Ontotext Platform and its design choices.