Schema Storage & Management

Overview

The Semantic Objects Service manages a collection of Semantic Object schemas. It also manages access to these schemas using Role-Based Access Controls.

This section of the documentation does not discuss the SOML language and syntax, but rather the management of these schemas and the Role-Based Access Controls that constrain access to the schemas.

A collection of SOML schemas is shared amongst instances of the Semantic Objects service. A Semantic Object service instance can bind any one of these Semantic Object schemas to generate a GraphQL endpoint. Thus allowing client applications to perform GraphQL queries and mutations.

The Semantic Object service manages and stores schemas within MongoDB.

Schema management is achieved by using the Semantics Objects /soml REST API.

RBACs are applied to the collection of schemas. These controls ensure those roles that can create/update/delete or bind a particular schema. RBACs are managed by using the Semantics Objects /soml-rbac REST API.

Quick Start

Hint

You can perform all of the below actions from the Platform web-based administration interface, the Workbench.

You will need to install docker-compose on the machine on which you wish to run the Semantic Object service and the MongoDB database.

Please follow the docker-compose installation guide.

A docker-compose.yaml is required to ensure all mandatory components are started correctly before you can manage SOML schemas.

This docker-compose.yaml configuration will download and start the important containers on a single machine.

The Ontotext Platform is available under a commercial time-based license. To obtain an evaluation license, please contact the Ontotext team and see the documentation on Setting up Licenses.

Use this environment file .env to configure the location of the Ontotext Platform license.

SOML Schema Creation

To create a schema from the Platform Workbench, follow the steps described here (generate a schema from an existing ontology file) and here (create a new schema).

To create the SWAPI schema within Semantic Objects as service with the identifier /soml/swapi, first download the Semantic Object schema.yaml definition.

You can invoke the following cURL request:

curl --location -X POST 'http://localhost:9995/soml' \
    -H 'Content-Type: text/yaml' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Accept: application/ld+json' \
    -T schema.yaml

SOML Schema Validation

To validate a SOML schema from the Workbench as part of the schema generation workflow without creating it, follow the steps described here.

To validate a SOML schema via cURL without creating it, you can use the following cURL request:

curl --location -X POST 'http://localhost:9995/soml/validate' \
    -H 'Content-Type: text/yaml' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Accept: application/ld+json' \
    -T schema.yaml

The validation consists of two phases:

  • SOML schema validation: the same check performed during SOML schema creation or update

  • SOML schema binding: checks if the SOML schema can be transformed to a GraphQL schema, and, optionally (if SHACL is enabled), to SHACL shapes

SOML Schema List

To view all currently existing SOML schemas managed within the Semantic Objects Service (and MongoDB) from the Workbench, follow the instructions here.

To retrieve a list of all the SOML schemas managed within the Semantic Objects Service (and MongoDB), invoke the following cURL request:

curl --location --request GET 'http://localhost:9995/soml' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Accept: application/ld+json'

SOML Schema Retrieval

To open a particular SOML schema managed within the Semantic Objects Service (and MongoDB) from the Workbench, follow the instructions here.

To retrieve a particular SOML schema (in this case the SWAPI schema) managed within the Semantic Objects Service (and MongoDB), invoke the following cURL request:

curl --location -X GET 'http://localhost:9995/soml/swapi' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Accept: text/yaml'

You can also request a response in application/ld+json format:

curl --location -X GET 'http://localhost:9995/soml/swapi' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Accept: application/ld+json'

SOML Schema Updates

To update a SOML schema from the Workbench, follow the instructions here.

To update the SWAPI schema within the Semantic Objects Service with the identifier /soml/swapi, invoke the following cURL request:

curl --location -X PUT 'http://localhost:9995/soml/swapi' \
    -H 'Content-Type: text/yaml' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Accept: application/ld+json' \
    -T schema.yaml

SOML Schema Binding

To bind (i.e., activate) a SOML schema to the Semantic Objects Service from the Workbench, follow the instructions here.

To bind the SWAPI schema to the Semantic Objects Service, and generate the GraphQL endpoint/schema from it, invoke the following cURL request:

curl --location -X PUT 'http://localhost:9995/soml/swapi/soaas' \
    -H 'X-Request-ID: some-uuid-correlation-id'

SOML Schema Deletion

You can delete a SOML schema from the Workbench only if it is not bound (i.e., activated). This can be done from the Schema Registry and the Manage Schema views.

To delete the schema and unbind one from the Semantic Objects Service (if it is bound), invoke the following cURL request:

curl --location -X DELETE 'http://localhost:9995/soml/swapi' \
    -H 'X-Request-ID: some-uuid-correlation-id' \

Note

The above examples are with security ON, meaning that -H 'X-Request-ID: some-uuid-correlation-id' should be removed if the Platform is started without security.

SOML Schema Statistics

You can see schema statistics from the Workbench by clicking on the schema ID in the Schema Registry list. The Workbench home screen will display statistics only for the currently active schema.

To retrieve SOML schema statistics, use the following cURL request:

curl --location -X GET 'http://localhost:9995/soml/swapi/stats?limit=10' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Accept: application/ld+json'

This will return the top 10 shapes in the SOML schema.

Note

SOML schema statistics are available only for the active schema.

Administration

Schema Management API

Please see the Quick Start cURL examples for create, read, update, delete, and bind operation examples.

Schema Management RBAC

Only users with a role claim schema-rbac-admin are able to modify the schema rbac (read/write/delete). RBACs authorize access to schema endpoints:

  • GET /soml: Retrieve all schemas

  • GET /soml/{schema-id}: Retrieve a particular schema

  • POST /soml/{schema-id}: Create a particular schema

  • PUT /soml/{schema-id}: Update a particular schema

  • DELETE /soml/{schema-id}: Delete a particular schema

  • GET /soml/{schema-id}/boaas: Bind a particular schema to Semantic Object service

Schema RBAC Endpoints

The Semantic Object service provides the following endpoints to manage the schema RBAC:

  • Read: GET /soml-rbac the schema RBACs (only accessible for users/role SchemaRBACAdmin)

  • Update: PUT /soml-rbac update the schema RBACs (only accessible for users/role SchemaRBACAdmin)

An example schema RBAC is as follows:

id:          /soml-rbac
label:       Schema Management Role-Based Access Control
creator:     http://ontotext.com
created:     2019-06-15
updated:     2019-06-16
versionInfo: 0.1

rbac:
    roles:
        # Default role which does not need to be configured or declared. Included for completeness.
        Default:
        description: "Default role, which does not need to be declared restricts all schema management access read, write and delete"
        notActions: ["*/*"]
        # Example role definitions which need to be declared by the SOML user:
        SchemaRBACAdmin:
        description: "Administrator role, can read, write and delete objects and schema"
        actions: ["*/*"]
        ReadOnlyUser:
        description: "User which can read all schema"
        actions: ["*/read"]
        SwapiSchemaManager:
        description: "User which has admin access (read, write and delete on the swapi schema only"
        actions: ["swapi/*"]
Reading the Schema RBACs

The following cURL request (with a valid JWT token containing a role claim == SchemaRBACAdmin) will retrieve the schema RBAC:

curl --location -X GET 'http://localhost:9995/soml-rbac' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Accept: text/yaml'
Updating the Schema RBACs

The following cURL request (with a valid JWT token containing a role claim == SchemaRBACAdmin) will update the schema RBAC with the contents of the rbac.yaml file:

curl --location -X PUT 'http://localhost:9995/soml-rbac' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Content-Type: text/yaml' \
    -H 'Accept: application/ld+json' \
    -T rbac.yaml
Getting Schema RBAC roles

The following cURL request will return the RBAC roles for the currently authenticated user.

curl --location -X GET 'http://localhost:9995/soml-rbac/roles' \
    -H 'X-Request-ID: some-uuid-correlation-id' \
    -H 'Accept: application/ld+json'

MongoDB

The Platform’s MongoDB docker container can be accessed at http://localhost:9997.

For more information on how to administer a MongoDB instance, see the Mongo Administration page.

MongoDB Compass

There is no GUI included within the MongoDB container, but it is possible to use one of the popular clients such as MongoDB Compass.