Administration

What’s in this document?

This section will show you how to upload your own SOML schema into the Semantic Objects and perform operations such as activate/deactivate, update, or read it.

Operations

Below you will find information about the available SOML endpoints, as well as the functionalities each of them provides, the parameters they accept, and what the expected common responses are. For consistency, the endpoint addresses are bound to the localhost, and they should be the same as in the Quick Start guide.

Create

The creating of a SOML schema is done via POST request to the /soml endpoint:

curl "http://localhost:9995/soml" -X POST -H "Content-Type: text/yaml" -T "/path/to/schema.yaml"

If the request is successful and the provided schema is valid, the response will have status 201 Created and look like this:

{"@context":{
      "@vocab":"http://ontotext.com/ontology/status/",
      "@base":"http://data.ontotext.com/",
      "xsd":"http://www.w3.org/2001/XMLSchema#",
      "hydra":"http://www.w3.org/ns/hydra/core#"
   },
   "@type":"SOML",
   "@id":"/soml/simpleStarWars",
   "input":"id:          /soml/simpleStarWars\r\nlabel:       Star Wars\r\ncreator:     http://ontotext.com\r\ncreated:     2019-06-15\r\nupdated:     2019-06-16\r\nversionInfo: 0.1\r\n\r\nprefixes:\r\n  rdf: \"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\r\n  rdfs: \"http://www.w3.org/2000/01/rdf-schema#\"\r\n  xsd: \"http://www.w3.org/2001/XMLSchema#\"\r\n\r\nspecialPrefixes:\r\n  base_iri:          https://starwars.org/resource/\r\n  vocab_iri:         https://starwars.org/vocabulary/\r\n  vocab_prefix:      voc\r\n\r\nobjects:\r\n\r\n  Character:\r\n    kind: abstract\r\n    descr: \"A character in a film\"\r\n    typeProp: \"rdf:type\"\r\n    props:\r\n      voc:name: {label: \"Name\"}\r\n      descr: {label: \"Description\"}\r\n      friend: {descr: \"Character's friend\", max: inf, range: Character}\r\n      homeWorld: {label: \"Home World\", descr: \"Characters home world (planet)\", max: 1, range: Planet}\r\n      \r\n  Human:\r\n    prefix: \"human/\"\r\n    descr: \"A Homo Sapiens\"\r\n    inherits: Character\r\n    props:\r\n      height: {descr: \"Height in meters\", range: decimal}\r\n      mass: {descr: \"Mass in kilograms\", range: decimal}\r\n\r\n  Planet:\r\n    prefix: \"planet/\"\r\n    # type voc:Planet default\r\n    descr: \"A planet\"\r\n    name: voc:name\r\n    props:\r\n      descr: {label: \"Description\"}\r\n\r\nrbac:\r\n  roles:\r\n    Admin:\r\n      description: \"Administrator role, can read, write and delete objects and schema\"\r\n      actions: [\r\n        \"*/*/*\",\r\n      ]\r\n"}

The produced response is in JSON-LD format, and contains the type of the schema, the id, and the inputted schema.

Note

If the schema does not provide its own id, the service will generate and assign one. The id is important, because it is used for all other operations.

If a schema with the same id already exists, the response will be:

{"@context":{
   "@vocab":"http://ontotext.com/ontology/status/",
   "@base":"https://data.ontotext.com/resource/status/",
   "xsd":"http://www.w3.org/2001/XMLSchema#"
},
"@type":"Error",
"code":"4090001",
"message":"SOML id already exists!",
"@id":"fe136c54-0316-53d1-b3ca-d0183be7b955"}

Notice that every error response contains a code property, which is unique for the different types of errors that the service may return.

Another common type of error responses that might be produced when creating or updating SOML are validation errors. Their code is 4000001, and they contain detailed information about the encountered error and its type, i.e., whether it is a validation or a syntax error.

Update

The update operation allows you to modify any aspect of an existing SOML schema except for its id. Also, there is no need to re-bind the schema if the updated one is the currently bound schema, as it will be automatically replaced with the new one. Update requests looks like this:

curl "http://localhost:9995/soml/{id}" -X PUT -H "Content-Type: text/yaml" -T "/path/to/schema.yaml"

If the request is successful and the schema is valid, the response will look like shown below, and the returned status will again be 201 Created:

{"@context":{
   "@vocab":"http://ontotext.com/ontology/status/",
   "@base":"http://data.ontotext.com/",
   "xsd":"http://www.w3.org/2001/XMLSchema#",
   "hydra":"http://www.w3.org/ns/hydra/core#"
},
"@type":"SOML",
"@id":"/soml/simpleStarWars",
"input":"id:          /soml/simpleStarWars\r\nlabel:       Star Wars\r\ncreator:     http://ontotext.com\r\ncreated:     2019-06-15\r\nupdated:     2019-06-16\r\nversionInfo: 0.2\r\n\r\nprefixes:\r\n  # common prefixes\r\n  so: \"http://www.ontotext.com/semantic-object/\"\r\n  dct: \"http://purl.org/dc/terms/\"\r\n  gn: \"http://www.geonames.org/ontology#\"\r\n  owl: \"http://www.w3.org/2002/07/owl#\"\r\n  puml: \"http://plantuml.com/ontology#\"\r\n  rdf: \"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\r\n  rdfs: \"http://www.w3.org/2000/01/rdf-schema#\"\r\n  skos: \"http://www.w3.org/2004/02/skos/core#\"\r\n  void: \"http://rdfs.org/ns/void#\"\r\n  wgs84: \"http://www.w3.org/2003/01/geo/wgs84_pos#\"\r\n  xsd: \"http://www.w3.org/2001/XMLSchema#\"\r\n\r\nspecialPrefixes:\r\n  base_iri:          https://starwars.org/resource/\r\n  vocab_iri:         https://starwars.org/vocabulary/\r\n  vocab_prefix:      voc\r\n\r\nobjects:\r\n\r\n  Character:\r\n    kind: abstract\r\n    descr: \"A character in a film\"\r\n    # type: voc:Character default\r\n    typeProp: \"rdf:type\"\r\n    props:\r\n      voc:name: {label: \"Name\"}\r\n      descr: {label: \"Description\"}\r\n      friend: {descr: \"Character's friend\", max: inf, range: Character}\r\n      homeWorld: {label: \"Home World\", descr: \"Characters home world (planet)\", max: 1, range: Planet}\r\n\r\n  Droid:\r\n    prefix: \"droid/\"\r\n    # type voc:Droid: default\r\n    descr: \"A droid/robot with Artificial Intelligence\"\r\n    inherits: Character\r\n    regex: \"^https://starwars.org/resource/\\\\w+/\"\r\n    props:\r\n      primaryFunction: {label: \"primary function\", descr: \"e.g translator, cargo\"}\r\n      droidHeight: {descr: \"Height in meters\", range: decimal}\r\n\r\n  Human:\r\n    prefix: \"human/\"\r\n    # type voc:Human: default\r\n    descr: \"A Homo Sapiens\"\r\n    inherits: Character\r\n    props:\r\n      height: {descr: \"Height in meters\", range: decimal}\r\n      mass: {descr: \"Mass in kilograms\", range: decimal}\r\n      enemies: {descr: \"The enemy of humanity\", range: Droid, max: 3}\r\n\r\n  Planet:\r\n    prefix: \"planet/\"\r\n    # type voc:Planet default\r\n    descr: \"A planet\"\r\n    name: voc:name\r\n    props:\r\n      descr: {label: \"Description\"}\r\n      \r\n  Pilot:\r\n    prefix: \"pilot/\"\r\n    descr: \"A pilot\"\r\n    inherits: Character\r\n    props:\r\n      descr: {label: \"The driver\"}\r\n\r\nrbac:\r\n  roles:\r\n    Admin:\r\n      description: \"Administrator role, can read, write and delete objects and schema\"\r\n      actions: [\r\n        \"*/*/*\",\r\n      ]\r\n    ROLE_Admin:\r\n      # An Admin role used in some unit tests where the spring security prepends the ROLE prefix when role is set through a mock user annotation.\r\n      description: \"Administrator role, can read, write and delete objects and schema\"\r\n      actions: [\r\n        \"*/*/*\",\r\n      ]\r\n"}

Possible errors that may occur here are:

  • Schema not found - when attempting to update schema that does not exist. The returned error code is 4040001.
  • Schema id mismatch - when the {id} path parameter does not match the one in the actual schema definition. The returned error code will be 4000007.
  • Validation errors - when there are syntax or other types of errors in the schema definition that are invalid.

Read

There are two endpoints for reading SOML information. The first one retrieves the data of a single schema as follows:

curl "http://localhost:9995/soml/{id}" -X GET

If a schema with id simpleStarWars is available, it will be returned as a response in YAML format.

id:          /soml/simpleStarWars
label:       Star Wars
creator:     http://ontotext.com
created:     2019-06-15
updated:     2019-06-16
versionInfo: 0.1

prefixes:
  rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  rdfs: "http://www.w3.org/2000/01/rdf-schema#"
  xsd: "http://www.w3.org/2001/XMLSchema#"

specialPrefixes:
  base_iri:          https://starwars.org/resource/
  vocab_iri:         https://starwars.org/vocabulary/
  vocab_prefix:      voc

objects:

  Character:
    kind: abstract
    descr: "A character in a film"
    typeProp: "rdf:type"
    props:
      voc:name: {label: "Name"}
      descr: {label: "Description"}
      friend: {descr: "Character's friend", max: inf, range: Character}
      homeWorld: {label: "Home World", descr: "Characters home world (planet)", max: 1, range: Planet}

  Human:
    prefix: "human/"
    descr: "A Homo Sapiens"
    inherits: Character
    props:
      height: {descr: "Height in meters", range: decimal}
      mass: {descr: "Mass in kilograms", range: decimal}

  Planet:
    prefix: "planet/"
    descr: "A planet"
    name: voc:name
    props:
      descr: {label: "Description"}

rbac:
  roles:
    Admin:
      description: "Administrator role, can read, write and delete objects and schema"
      actions: [
        "*/*/*",
      ]

Note

If the requested schema does not exist, the response will be a code 4040001 error.

The second request that can be made to retrieve information about the available SOML schemas is:

curl "http://localhost:9995/soml" -X GET

It will retrieve all currently available SOML schemas. The response will look like this:

{"@context":{
    "@vocab":"http://ontotext.com/ontology/status/",
    "@base":"http://data.ontotext.com/",
    "xsd":"http://www.w3.org/2001/XMLSchema#",
    "hydra":"http://www.w3.org/ns/hydra/core#"
 },
 "@type":"hydra:Collection",
 "@id":"http://localhost:8080/soml?page=0&size=1",
 "hydra:member":[
    {
       "@type":"SOML",
       "@id":"/soml/simpleStarWars",
       "input":"id:          /soml/simpleStarWars\r\nlabel:       Star Wars\r\ncreator:     http://ontotext.com\r\ncreated:     2019-06-15\r\nupdated:     2019-06-16\r\nversionInfo: 0.1\r\n\r\nprefixes:\r\n  rdf: \"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\r\n  rdfs: \"http://www.w3.org/2000/01/rdf-schema#\"\r\n  xsd: \"http://www.w3.org/2001/XMLSchema#\"\r\n\r\nspecialPrefixes:\r\n  base_iri:          https://starwars.org/resource/\r\n  vocab_iri:         https://starwars.org/vocabulary/\r\n  vocab_prefix:      voc\r\n\r\nobjects:\r\n\r\n  Character:\r\n    kind: abstract\r\n    descr: \"A character in a film\"\r\n    typeProp: \"rdf:type\"\r\n    props:\r\n      voc:name: {label: \"Name\"}\r\n      descr: {label: \"Description\"}\r\n      friend: {descr: \"Character's friend\", max: inf, range: Character}\r\n      homeWorld: {label: \"Home World\", descr: \"Characters home world (planet)\", max: 1, range: Planet}\r\n      \r\n  Human:\r\n    prefix: \"human/\"\r\n    descr: \"A Homo Sapiens\"\r\n    inherits: Character\r\n    props:\r\n      height: {descr: \"Height in meters\", range: decimal}\r\n      mass: {descr: \"Mass in kilograms\", range: decimal}\r\n\r\n  Planet:\r\n    prefix: \"planet/\"\r\n    # type voc:Planet default\r\n    descr: \"A planet\"\r\n    name: voc:name\r\n    props:\r\n      descr: {label: \"Description\"}\r\n\r\nrbac:\r\n  roles:\r\n    Admin:\r\n      description: \"Administrator role, can read, write and delete objects and schema\"\r\n      actions: [\r\n        \"*/*/*\",\r\n      ]\r\n"
    }
 ],
 "hydra:totalItems":1,
 "hydra:view":{
    "@type":"hydra:PartialCollectionView",
    "hydra:first":"http://localhost:8080/soml?page=0&size=1",
    "hydra:last":"http://localhost:8080/soml?page=0&size=1"
 }}

Tip

The endpoint supports pagination. This is useful when using the service over a longer time period, as without proper limitations, you might end up with a lot of schemas. This could potentially result in the transferring of large amount of data over HTTP.

Bind

Bind requests are used to activate a given SOML schema for the service. As the service may contain multiple schemas at a time, it is important to have a way to tell it which schema to use while executing queries. You can bind a specific schema by executing:

curl "http://localhost:9995/soml/{id}/soaas" -X PUT

This will produce the response below, meaning that the schema is successfully bound and ready for use:

{"@context":{
    "@vocab":"http://ontotext.com/ontology/status/",
    "@base":"http://data.ontotext.com/",
    "xsd":"http://www.w3.org/2001/XMLSchema#",
    "hydra":"http://www.w3.org/ns/hydra/core#"
 },
 "@type":"SOML",
 "@id":"/soml/simpleStarWars",
 "input":"id:          /soml/simpleStarWars\r\nlabel:       Star Wars\r\ncreator:     http://ontotext.com\r\ncreated:     2019-06-15\r\nupdated:     2019-06-16\r\nversionInfo: 0.1\r\n\r\nprefixes:\r\n  rdf: \"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\r\n  rdfs: \"http://www.w3.org/2000/01/rdf-schema#\"\r\n  xsd: \"http://www.w3.org/2001/XMLSchema#\"\r\n\r\nspecialPrefixes:\r\n  base_iri:          https://starwars.org/resource/\r\n  vocab_iri:         https://starwars.org/vocabulary/\r\n  vocab_prefix:      voc\r\n\r\nobjects:\r\n\r\n  Character:\r\n    kind: abstract\r\n    descr: \"A character in a film\"\r\n    typeProp: \"rdf:type\"\r\n    props:\r\n      voc:name: {label: \"Name\"}\r\n      descr: {label: \"Description\"}\r\n      friend: {descr: \"Character's friend\", max: inf, range: Character}\r\n      homeWorld: {label: \"Home World\", descr: \"Characters home world (planet)\", max: 1, range: Planet}\r\n      \r\n  Human:\r\n    prefix: \"human/\"\r\n    descr: \"A Homo Sapiens\"\r\n    inherits: Character\r\n    props:\r\n      height: {descr: \"Height in meters\", range: decimal}\r\n      mass: {descr: \"Mass in kilograms\", range: decimal}\r\n\r\n  Planet:\r\n    prefix: \"planet/\"\r\n    # type voc:Planet default\r\n    descr: \"A planet\"\r\n    name: voc:name\r\n    props:\r\n      descr: {label: \"Description\"}\r\n\r\nrbac:\r\n  roles:\r\n    Admin:\r\n      description: \"Administrator role, can read, write and delete objects and schema\"\r\n      actions: [\r\n        \"*/*/*\",\r\n      ]\r\n"}

Delete

The delete operation removes a SOML schema from the store and unbinds it, i.e., deactivates it. If the removed schema is the currently bound one, this request should be followed by a bind request for another schema, otherwise the service will be left in a state in which it cannot be used due to the absence of a schema.

The request and the response should look as follows:

curl "http://localhost:9995/soml/{id}" -X DELETE
{"@context":{
    "@vocab":"http://ontotext.com/ontology/status/",
    "@base":"http://data.ontotext.com/",
    "xsd":"http://www.w3.org/2001/XMLSchema#",
    "hydra":"http://www.w3.org/ns/hydra/core#"
 },
 "@type":"SOML",
 "@id":"/soml/simple-StarWars",
 "input":"id:          /soml/simpleStarWars\r\nlabel:       Star Wars\r\ncreator:     http://ontotext.com\r\ncreated:     2019-06-15\r\nupdated:     2019-06-16\r\nversionInfo: 0.1\r\n\r\nprefixes:\r\n  # common prefixes\r\n  so: \"http://www.ontotext.com/semantic-object/\"\r\n  dct: \"http://purl.org/dc/terms/\"\r\n  gn: \"http://www.geonames.org/ontology#\"\r\n  owl: \"http://www.w3.org/2002/07/owl#\"\r\n  puml: \"http://plantuml.com/ontology#\"\r\n  rdf: \"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\r\n  rdfs: \"http://www.w3.org/2000/01/rdf-schema#\"\r\n  skos: \"http://www.w3.org/2004/02/skos/core#\"\r\n  void: \"http://rdfs.org/ns/void#\"\r\n  wgs84: \"http://www.w3.org/2003/01/geo/wgs84_pos#\"\r\n  xsd: \"http://www.w3.org/2001/XMLSchema#\"\r\n\r\nspecialPrefixes:\r\n  base_iri:          https://starwars.org/resource/\r\n  vocab_iri:         https://starwars.org/vocabulary/\r\n  vocab_prefix:      voc\r\n\r\nobjects:\r\n\r\n  Character:\r\n    kind: abstract\r\n    descr: \"A character in a film\"\r\n    # type: voc:Character default\r\n    typeProp: \"rdf:type\"\r\n    props:\r\n      voc:name: {label: \"Name\"}\r\n      descr: {label: \"Description\"}\r\n      friend: {descr: \"Character's friend\", max: inf, range: Character}\r\n      homeWorld: {label: \"Home World\", descr: \"Characters home world (planet)\", max: 1, range: Planet}\r\n\r\n  Droid:\r\n    prefix: \"droid/\"\r\n    # type voc:Droid: default\r\n    descr: \"A droid/robot with Artificial Intelligence\"\r\n    inherits: Character\r\n    regex: \"^https://starwars.org/resource/\\\\w+/\"\r\n    props:\r\n      primaryFunction: {label: \"primary function\", descr: \"e.g translator, cargo\"}\r\n      droidHeight: {descr: \"Height in meters\", range: decimal}\r\n\r\n  Human:\r\n    prefix: \"human/\"\r\n    # type voc:Human: default\r\n    descr: \"A Homo Sapiens\"\r\n    inherits: Character\r\n    props:\r\n      height: {descr: \"Height in meters\", range: decimal}\r\n      mass: {descr: \"Mass in kilograms\", range: decimal}\r\n      enemies: {descr: \"The enemy of humanity\", range: Droid, max: 3}\r\n\r\n  Planet:\r\n    prefix: \"planet/\"\r\n    # type voc:Planet default\r\n    descr: \"A planet\"\r\n    name: voc:name\r\n    props:\r\n      descr: {label: \"Description\"}\r\n      \r\n  Pilot:\r\n    prefix: \"pilot/\"\r\n    descr: \"A pilot\"\r\n    inherits: Character\r\n    props:\r\n      descr: {label: \"The driver\"}\r\n\r\nrbac:\r\n  roles:\r\n    Admin:\r\n      description: \"Administrator role, can read, write and delete objects and schema\"\r\n      actions: [\r\n        \"*/*/*\",\r\n      ]\r\n    ROLE_Admin:\r\n      # An Admin role used in some unit tests where the spring security prepends the ROLE prefix when role is set through a mock user annotation.\r\n      description: \"Administrator role, can read, write and delete objects and schema\"\r\n      actions: [\r\n        \"*/*/*\",\r\n      ]\r\n"}

Note

A code 4040001 error may occur if you try to delete a schema that does not exist.