Skip to main content

Demo

With the wizard functionality users go through a series of steps to design message schemas and API specifications based on a shared domain ontology. Ontologies are globally shared, conceptual models that describe a specific domain, with the intention of sharing data. They can be re-used and can be used in combination with other ontologies. Because of the open nature of ontologies it is very likely that already an ontology exists for your specific problem domain, luckily. In this demo we will create a message specification about a person based on an ontology, specifically the FOAF Friend of a Friend ontology for representing information about people.

At the core of the FOAF ontology is the Person class, which defines the basic structure for representing individuals within the ontology. The class Person includes multiple incoming and outcoming properties, which may be relevant for the to-be-created message specification. In this example, we are only interested in creating a message model that addresses a person and their friends. The wizard offers an intuitive interface, that allows you to easily create and modify elements of the message specification (e.g. the naming of the person). Detailed information about the individual elements, such as their description and cardinality, can be adjusted to create a snapshot from the ontology information.

A demo video tutorial was created to demonstrate how to create your message specification based on the FOAF ontology. In order to do that, the video will start by uploading the FOAF ontology into the Semantic Treehouse environment, and then proceed to create a message specification for a person. The following steps - explained in detail in the next sections - are demonstrated in the video below:

1. Uploading the ontology​

The first tutorial video demonstrates how to upload an ontology, the FOAF Ontology, in a Semantic Treehouse environment. More textual information can be found in the section Ontologies.

2. Creating a message specification​

The video provided in this section demonstrates the creation of an ontology-based message specification. The to-be-created message specification is based on the FOAF ontology. The message specification describes one person and their acquantainces. Sharing these models allows one to build a social network of people who know each other. We choose to identify people by first and last name. The video includes the following steps for creating a message specification:

Step 1 of the wizard

  • Select ontologies to import
  • Select root class for message specification
    • The namespace of the ontology is: http://xmlns.com/foaf/0.1/
    • The URI of the root class is: http://xmlns.com/foaf/0.1/Person
  • Adding namespaces and namespace prefixes

Step 2 of the wizard

  • Structuring: Adding sub elements
  • Customizing elements: Changing the cardinality

3. Checking and adding constraints​

The wizard is able to use OWL constraints from the ontology as cardinality constraints in the message treeview, but there are no OWL constraints in this particular example. Instead, the wizard looks at the SHACL shapes of the ontology (and prefers SHACL constraints over OWL constraints where they might conflict). The section OWL constraints and the section SHACL constraints provide more information about OWL and SHACL constraints.

In this demo, we use SHACL constraints (minCount and maxCount) to determine the cardinalities of the elements in our message specification. These constraints can be incorporated into an ontology and uploaded to Semantic Treehouse, allowing for the utilization of SHACL shapes as an input for message specifications. The video provided uses the following SHACL file.

foaf:Person
rdf:type sh:NodeShape ;
sh:property [
rdf:type sh:PropertyShape ;
sh:path foaf:firstName;
sh:maxCount 1 ;
sh:minCount 1 ;
];
sh:property [
rdf:type sh:PropertyShape ;
sh:path foaf:surname ;
sh:maxCount 1 ;
sh:minCount 1 ;
].

4. Generating output

Wizard step 3

The message seems good, so we'll proceed to the output generation phase to see if the output matches what we expect. The wizard can generate several outputs, like message schemas in different languages and example messages. These outputs are generated dynamically and freely, so you can check the output, alter the message and try again. The provided demo video shows the several outputs from the wizard, including XML and JSON schema as well as Open API specifications. For more information about step 3 of the Wizard, please consult section Wizard step 3.