OWL2SOML

Note

This feature is still experimental and we are improving it. Please provide feedback!

SOML and OWL are two completely different languages that have a similar purpose - to provide a way of describing and modeling data. As a lot of Platform users already have OWL ontologies describing their data, the need for a conversion from OWL to SOML is obvious.

The Platform supports this conversion using a feature called OWL2SOML. We first prototyped it in Perl as the OWL2SOML tool, then implemented it in Java as part of the Platform. The results from the OWL2SOML tool may differ slightly from the results of the Platform, although in general, they are similar. The tool is still under development, so there might be some delay implementing its latest features in the Platform. See section Differences for details.

All of the below actions and examples can also be executed from the Platform web-based administration interface, the Workbench.

Generate and Upload a Schema

To generate and upload a schema from the Workbench, follow the steps described here.

To generate and upload a schema, the regular endpoint should be used but with a different Content-Type - multipart/form-data.

curl --location --request POST '{SOAAS_ADDRESS}/soml/' \
--header 'Content-Type: multipart/form-data' \
--form 'files=@{ONTOLOGY_FILE}' \

This endpoint supports the following parameters used especially for the OWL2SOML conversion:

files
Description: Ontology files. Any RDF format is supported. An automatic attempt to extract the main ontology_iri and the vocab_prefix will be performed only from the first (main) ontology.
Required: true
Default value: none
vocPfx
Description: Specifies a vocab_prefix for the schema. The namespace for this prefix should be declared in one of the ontology files. If not specified explicitly, one will be extracted automatically. Setting it to NONE will set a default namespace http://example.com/. Use this option if there is no main ontology to be used.
Required: false
Default value: none
id
Description: Specifies an id for the schema.
Required: false, unless vocPfx is set to NONE. In that case there is no other way to determine the schema id as no main ontology will be used.
Default value: none
label
Description: Specifies a label for the schema. This is to be used only with the id parameter. Otherwise the label will be extracted from the main ontology automatically.
Required: false
Default value: none
lang
Description: Specifies the schema-level lang spec to control how language strings are handled. The supported format is either a string with no spaces (which sets fetch), or key1: val1, key2: val2, ... where the keys are fetch, validate, and implicit, and the values include no spaces. For example: lang=fetch: en~,de,ANY, validate: en~,de~,fr~, implicit: en-GB. For more information about the lang configuration, see Language configurations.
Required: false
Default value: none
stringMode
Description: Provides means for controlling the way of emitting string-related datatypes. Possible values are stringOrLangString, langString, and string. For details on the output that each datatype produces, check the table below.
Required: false
Default value: stringOrLangString

Datatype

stringOrLangString(default)

langString

string

rdf:langString

langString

langString

string

rdf:PlainLiteral, rdfs:Literal, schema:Text, undefined

stringOrLangString

langString

string

xsd:string

string

string

string

dryrun
Description: Performs a schema transformation without actually uploading the SOML schema. Useful for testing purposes. Applicable only for generate (POST) requests.
Required: false
Default value: false

Generate and Update a Schema

To update a schema from the Platform Workbench, follow the schema generation steps described here.

Similarly to the upload, the regular update endpoint is used with multipart/form-data Content-Type:

curl --location --request PUT '{SOAAS_ADDRESS}/soml/{SOML_SCHEMA_ID}' \
--header 'Content-Type: multipart/form-data' \
--form 'files=@{ONTOLOGY_FILE}'

This endpoint supports all of the upload endpoint parameters except id and `dryrun. dryrun is not supported for update (PUT), use upload (POST) instead. id is taken from the Path parameter of the endpoint.

Example

In this section, we will take a look at a simple example of how to convert an OWL ontology to SOML using the Platform. For more details on how exactly the conversion works, refer to the OWL2SOML documentation.

We will generate a SOML schema from the SKOS ontology.

First, download the skos.rdf ontology.

Second, download the skos-fix.ttl. This file contains RDF that will help us build a richer schema.

For this example, both files must be uploaded to the Platform at once using any preferred approach. In the examples to follow, we use cURL to execute a POST multipart/form-data request to perform the files upload:

curl --location --request POST 'localhost:9995/soml/' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer JWT_TOKEN' \
--form 'files=@/home/user/data/skos.rdf' \
--form 'files=@/home/user/data/skos-fix.ttl' \

The endpoint accepts multiple RDF file formats and will parse the files depending on their extensions.

We will try to extract the main owl:Ontology from the first RDF file provided, so it is important to upload the skos.rdf file first. Also depending on the main owl:Ontology, we will determine the vocab_iri and vocab_prefix of the schema. If you want to specify an explicit vocab_prefix, you could just add the following optional vocPfx parameter:

curl --location --request POST 'localhost:9995/soml/' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer JWT_TOKEN' \
--form 'files=@/home/user/data/skos.rdf' \
--form 'files=@/home/user/data/skos-fix.ttl' \
--form 'vocPfx=skos' \

In this case, the vocab_iri will be determined by the namespaces defined in the RDF files. However, for our case this is not necessary as the main ontology and the vocab data are extracted automatically:

specialPrefixes:
  ontology_iri: http://www.w3.org/2004/02/skos/core
  vocab_iri: http://www.w3.org/2004/02/skos/core#
  vocab_prefix: skos

If you want to only test what SOML schema will be generated, you can use the following dryrun optional parameter:

curl --location --request POST 'localhost:9995/soml/' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer JWT_TOKEN' \
--form 'files=@/home/user/data/skos.rdf' \
--form 'files=@/home/user/data/skos-fix.ttl' \
--form 'vocPfx=skos' \
--form 'dryrun=true'

This way, you can test how your ontologies get converted without storing them in the database.

This will generate a result like the following schema:

id: /soml/skos
label: SKOS Vocabulary
creator: Alistair Miles, Sean Bechhofer
prefixes:
  dct: http://purl.org/dc/terms/
  owl: http://www.w3.org/2002/07/owl#
  rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
  rdfs: http://www.w3.org/2000/01/rdf-schema#
  schema: http://schema.org/
  skos: http://www.w3.org/2004/02/skos/core#
specialPrefixes:
  vocab_prefix: skos
  ontology_iri: http://www.w3.org/2004/02/skos/core
  vocab_iri: http://www.w3.org/2004/02/skos/core#
properties:
  altLabel:
    descr: An alternative lexical label for a resource. The range of skos:altLabel
      is the class of RDF plain literals. skos:prefLabel, skos:altLabel and skos:hiddenLabel
      are pairwise disjoint properties
    kind: literal
    label: alternative label
    max: inf
    range: stringOrLangString
    rdfProp: skos:altLabel
  broadMatch:
    descr: skos:broadMatch is used to state a hierarchical mapping link between two
      conceptual resources in different concept schemes
    inverseOf: narrowMatch
    kind: object
    label: has broader match
    max: inf
    range: Concept
    rdfProp: skos:broadMatch
  broader:
    descr: Broader concepts are typically rendered as parents in a concept hierarchy
      (tree). By convention, skos:broader is only used to assert an immediate (i.e.
      direct) hierarchical link between two conceptual resources. Relates a concept
      to a concept that is more general in meaning
    inverseOf: narrower
    kind: object
    label: has broader
    max: inf
    range: Concept
    rdfProp: skos:broader
  broaderTransitive:
    descr: By convention, skos:broaderTransitive is not used to make assertions. Rather,
      the properties can be used to draw inferences about the transitive closure of
      the hierarchical relation, which is useful e.g. when implementing a simple query
      expansion algorithm in a search application. skos:broaderTransitive is a transitive
      superproperty of skos:broader
    inverseOf: narrowerTransitive
    kind: object
    label: has broader transitive
    max: inf
    range: Concept
    rdfProp: skos:broaderTransitive
  changeNote:
    descr: A note about a modification to a concept
    kind: literal
    label: change note
    max: inf
    range: stringOrLangString
    rdfProp: skos:changeNote
  closeMatch:
    descr: skos:closeMatch is used to link two concepts that are sufficiently similar
      that they can be used interchangeably in some information retrieval applications.
      In order to avoid the possibility of "compound errors" when combining mappings
      across more than two concept schemes, skos:closeMatch is not declared to be
      a transitive property
    kind: object
    label: has close match
    max: inf
    range: Concept
    rdfProp: skos:closeMatch
    symmetric: true
  definition:
    descr: A statement or formal explanation of the meaning of a concept
    kind: literal
    label: definition
    max: inf
    range: stringOrLangString
    rdfProp: skos:definition
  editorialNote:
    descr: A note for an editor, translator or maintainer of the vocabulary
    kind: literal
    label: editorial note
    max: inf
    range: stringOrLangString
    rdfProp: skos:editorialNote
  exactMatch:
    descr: skos:exactMatch is disjoint with each of the properties skos:broadMatch
      and skos:relatedMatch. skos:exactMatch is used to link two concepts, indicating
      a high degree of confidence that the concepts can be used interchangeably across
      a wide range of information retrieval applications. skos:exactMatch is a transitive
      property, and is a sub-property of skos:closeMatch
    kind: object
    label: has exact match
    max: inf
    range: Concept
    rdfProp: skos:exactMatch
    symmetric: true
  example:
    descr: An example of the use of a concept
    kind: literal
    label: example
    max: inf
    range: stringOrLangString
    rdfProp: skos:example
  hasTopConcept:
    descr: Relates, by convention, a concept scheme to a concept which is topmost
      in the broader/narrower concept hierarchies for that scheme, providing an entry
      point to these hierarchies
    inverseOf: topConceptOf
    kind: object
    label: has top concept
    max: inf
    range: Concept
    rdfProp: skos:hasTopConcept
  hiddenLabel:
    descr: A lexical label for a resource that should be hidden when generating visual
      displays of the resource, but should still be accessible to free text search
      operations. The range of skos:hiddenLabel is the class of RDF plain literals.
      skos:prefLabel, skos:altLabel and skos:hiddenLabel are pairwise disjoint properties
    kind: literal
    label: hidden label
    max: inf
    range: stringOrLangString
    rdfProp: skos:hiddenLabel
  historyNote:
    descr: A note about the past state/use/meaning of a concept
    kind: literal
    label: history note
    max: inf
    range: stringOrLangString
    rdfProp: skos:historyNote
  inScheme:
    descr: A concept may be a member of more than one concept scheme. Relates a resource
      (for example a concept) to a concept scheme in which it is included
    kind: object
    label: is in scheme
    max: inf
    range: ConceptScheme
    rdfProp: skos:inScheme
  mappingRelation:
    descr: Relates two concepts coming, by convention, from different schemes, and
      that have comparable meanings. These concept mapping relations mirror semantic
      relations, and the data model defined below is similar (with the exception of
      skos:exactMatch) to the data model defined for semantic relations. A distinct
      vocabulary is provided for concept mapping relations, to provide a convenient
      way to differentiate links within a concept scheme from links between concept
      schemes. However, this pattern of usage is not a formal requirement of the SKOS
      data model, and relies on informal definitions of best practice
    kind: object
    label: is in mapping relation with
    max: inf
    range: Concept
    rdfProp: skos:mappingRelation
  member:
    descr: Relates a collection to one of its members
    kind: object
    label: has member
    max: inf
    range: CollectionInterface
    rdfProp: skos:member
  memberList:
    descr: |-
      For any resource, every item in the list given as the value of the
            skos:memberList property is also a value of the skos:member property. Relates an ordered collection to the RDF list containing its members
    kind: object
    label: has member list
    range: rdf:List
    rdfProp: skos:memberList
  narrowMatch:
    descr: skos:narrowMatch is used to state a hierarchical mapping link between two
      conceptual resources in different concept schemes
    inverseOf: broadMatch
    kind: object
    label: has narrower match
    max: inf
    range: Concept
    rdfProp: skos:narrowMatch
  narrower:
    descr: By convention, skos:broader is only used to assert an immediate (i.e. direct)
      hierarchical link between two conceptual resources. Narrower concepts are typically
      rendered as children in a concept hierarchy (tree). Relates a concept to a concept
      that is more specific in meaning
    inverseOf: broader
    kind: object
    label: has narrower
    max: inf
    range: Concept
    rdfProp: skos:narrower
  narrowerTransitive:
    descr: By convention, skos:narrowerTransitive is not used to make assertions.
      Rather, the properties can be used to draw inferences about the transitive closure
      of the hierarchical relation, which is useful e.g. when implementing a simple
      query expansion algorithm in a search application. skos:narrowerTransitive is
      a transitive superproperty of skos:narrower
    inverseOf: broaderTransitive
    kind: object
    label: has narrower transitive
    max: inf
    range: Concept
    rdfProp: skos:narrowerTransitive
  notation:
    descr: A notation, also known as classification code, is a string of characters
      such as "T58.5" or "303.4833" used to uniquely identify a concept within the
      scope of a given concept scheme. By convention, skos:notation is used with a
      typed literal in the object position of the triple
    kind: literal
    label: notation
    max: inf
    range: stringOrLangString
    rdfProp: skos:notation
  note:
    descr: A general note, for any purpose. This property may be used directly, or
      as a super-property for more specific note types
    kind: literal
    label: note
    max: inf
    range: stringOrLangString
    rdfProp: skos:note
  prefLabel:
    descr: |-
      A resource has no more than one value of skos:prefLabel per language tag, and no more than one value of skos:prefLabel without language tag. The preferred lexical label for a resource, in a given language. The range of skos:prefLabel is the class of RDF plain literals. skos:prefLabel, skos:altLabel and skos:hiddenLabel are pairwise
            disjoint properties
    kind: literal
    label: preferred label
    max: inf
    range: stringOrLangString
    rdfProp: skos:prefLabel
  related:
    descr: Relates a concept to a concept with which there is an associative semantic
      relationship. skos:related is disjoint with skos:broaderTransitive
    kind: object
    label: has related
    max: inf
    range: Concept
    rdfProp: skos:related
    symmetric: true
  relatedMatch:
    descr: skos:relatedMatch is used to state an associative mapping link between
      two conceptual resources in different concept schemes
    kind: object
    label: has related match
    max: inf
    range: Concept
    rdfProp: skos:relatedMatch
    symmetric: true
  scopeNote:
    descr: A note that helps to clarify the meaning and/or the use of a concept
    kind: literal
    label: scope note
    max: inf
    range: stringOrLangString
    rdfProp: skos:scopeNote
  semanticRelation:
    descr: Links a concept to a concept related by meaning. This property should not
      be used directly, but as a super-property for all properties denoting a relationship
      of meaning between concepts
    kind: object
    label: is in semantic relation with
    max: inf
    range: Concept
    rdfProp: skos:semanticRelation
  topConceptOf:
    descr: Relates a concept to the concept scheme that it is a top level concept
      of
    inverseOf: hasTopConcept
    kind: object
    label: is top concept in scheme
    max: inf
    range: ConceptScheme
    rdfProp: skos:topConceptOf
objects:
  Collection:
    descr: A meaningful collection of concepts. Labelled collections can be used where
      you would like a set of concepts to be displayed under a 'node label' in the
      hierarchy
    inherits: CollectionInterface
    label: Collection
    type: skos:Collection
  CollectionInterface:
    descr: Abstract superclass of Collection
    kind: abstract
    props:
      member: {}
  Concept:
    descr: An idea or notion; a unit of thought
    label: Concept
    props:
      altLabel: {}
      broadMatch: {}
      broader: {}
      broaderTransitive: {}
      changeNote: {}
      closeMatch: {}
      definition: {}
      editorialNote: {}
      exactMatch: {}
      example: {}
      hiddenLabel: {}
      historyNote: {}
      inScheme: {}
      mappingRelation: {}
      narrowMatch: {}
      narrower: {}
      narrowerTransitive: {}
      notation: {}
      note: {}
      prefLabel: {}
      related: {}
      relatedMatch: {}
      scopeNote: {}
      semanticRelation: {}
      topConceptOf: {}
    type: skos:Concept
  ConceptScheme:
    descr: A concept scheme may be defined to include concepts from different sources.
      A set of concepts, optionally including statements about semantic relationships
      between those concepts
    label: Concept Scheme
    props:
      hasTopConcept: {}
      prefLabel: {}
    type: skos:ConceptScheme
  OrderedCollection:
    descr: An ordered collection of concepts, where both the grouping and the ordering
      are meaningful. Ordered collections can be used where you would like a set of
      concepts to be displayed in a specific order, and optionally under a 'node label'
    inherits: CollectionInterface
    label: Ordered Collection
    props:
      memberList: {}
    type: skos:OrderedCollection
  rdf:List:
    type: rdf:List

The /soml/ endpoint will also return any warnings that have been raised during the conversion.

If you want to set up the language preference support of the conversion as well, you can use the lang param like this:

curl --location --request POST 'localhost:9995/soml' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer JWT_TOKEN' \
--form 'files=@/home/user/data/skos.rdf' \
--form 'files=@/home/user/data/skos-fix.ttl' \
--form 'vocPfx=skos' \
--form 'dryrun=true' \
--form 'lang=fetch: en~,de,ANY, validate: en~,de~,fr~, implicit: en-GB'

This will result in adding the following to the config section of the yaml schema (For more information about the lang configuration, see Language configurations):

config:
  lang:
    fetch: en~,de,ANY
    validate: en~,de~,fr~
    implicit: en-GB

For more examples of ontology conversions, please see the OWL2SOML example section.

Differences

The Platform differs from the OWL2SOML tool as follows:

The Platform uses HTTP parameters, whereas the tool is command-line and uses different options:

Platform

OWL2SOML tool

files

input files are listed after all options

dryrun

prints warnings/errors on STDERR, generated SOML on STDOUT

vocPfx

-voc

id

-id

label

-label

lang

-lang

stringMode

-string 0,1,2: same functionality, but the values are integers

always generates interfaces

-super 0,1: generate or don’t generate interfaces for superclasses

not supported

-name prop1,prop2: designate props as class “name” characteristics

  • If a property has multiple range-s, SOaaS will try to find such a range that is already defined as an object. The OWL2SOML tool picks the first range encountered, and may declare a new object class if it is used as range but not declared.

  • SOaaS assigns properties to classes based on owl:allValuesFrom and owl:someValuesFrom. This is described as a restriction in the OWL2SOML tool.

  • SOaaS handles :propA owl:qualifiedCardinality X. by setting :propA: {min: X, max: X}.

Limitations

SKOS is a simple example, and the conversion is relatively straightforward. However, for more complex examples there are multiple challenges that are yet to be addressed. For a full list of the currently known transformation limitations, please visit the limitations section of the OWL2SOML tool.