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!

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:

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

You can try out this RBAC constrained query here:

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.

    WookieeRead:
      description: "Can read all Wookiee properties and Species name. Nothing else.."
      actions: [
        "Wookiee/*/read",
        "Species/name/read"
      ]

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

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

username: droidhuttread@example.com
password: 1234567890


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

username: wookieeread@example.com
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:

    DroidHomePlanetNotEyesRead:
      description: "Can read Wookiee"
      actions: [
        "Droid/*/read",
        "Planet/name/read",
        "Species/name/read"
      ]
      notActions: [
        "Droid/eyeColor/read",
        "Droid/hairColor/read",
        "Droid/skinColor/read"
      ] 

You can try out this RBAC constrained query here:

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:

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:

      PersonCountryLocation:
      description: "Can read and write People, Locations, and Countries.
      nothing else.."
      actions: [
        "Person/*/write",
        "Person/*/read",
        "Location/*/read",
        "Location/*/write",
        "Country/*/write",
        "Country/*/read"
      ]  

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

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


username: peoplelocation@example.com
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.

ReadBlueEyedHuman:
  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.

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

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

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.

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 \ 
   "https://swapi-platform.ontotext.com/api/login" \       
   --header 'Content-Type: application/json' \
   --data-raw '{
     "loginId": "vocschemamanager@example.com",
     "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 'https://swapi-platform.ontotext.com/soml/' \
     --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.

Monitoring

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.

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.


username: monitoring@example.com
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:

• Semantic Objects Service Metrics
• GraphDb Service Metrics
• MongoDb Service Metrics
• Kubernetes Cluster Metrics

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!