Schema Storage & Management¶
What’s in this document?
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 schemasGET /soml/{schema-id}: Retrieve a particular schemaPOST /soml/{schema-id}: Create a particular schemaPUT /soml/{schema-id}: Update a particular schemaDELETE /soml/{schema-id}: Delete a particular schemaGET /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-rbacthe schema RBACs (only accessible for users/role SchemaRBACAdmin)Update:
PUT /soml-rbacupdate 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.