A Mini-Tutorial in SADL Version 2

Last revised 06/28/2011 by A. W. Crapo.

Introduction

This mini-tutorial will lead you through some of the basic features of SADL Version 2. It will familiarize you with the basics of SADL and introduce you to some of the authoring environment helps such as statement completion and templates by leading you through the construction of a simple genealogical model. This example domain is chosen so that the concepts will be familiar and you can focus on the modeling process and language.

See also SADL: What, Why, and How and SADL Architecture.

Build a Simple Model

Build a New Resources Project

  1. Select File->New->Project... from the menu bar (or use the toolbar icon dropdown menu)
  2. In the New Project dialog, open General and select Project, then click Next>
  3. Enter a Project name, e.g., MyFamily, and click Finish

Create a New SADL File

  1. Right-click on your new project in the Package Explorer or select File from the menu bar. In either case select New->File.
  2. In the resulting dialog box, enter a new file name ending in ".sadl", e.g., "Concepts.sadl". Note that the ".sadl" extension is necessary for the SADL nature to be given to the project and the SADL editor to be used.
  3. The first time you create a SADL file in a new project you will be asked if you wish to add the Xtext nature to the project. Say Yes.

Important Note

Each statement in a SADL model ends with a period. However, the period is also used for other things such as the decimal in a decimal number. Therefore the period at the end of a statement must be followed by white space (space, tab, newline, ...) or an error will be generated.

Every SADL Model File Needs a Unique Name (Content Assistance)

  1. To see how content assist works, hold down the Ctrl key and press the space bar. This is the request for content assist. (The focus must be in the editor window.) In this case the only thing that can start a valid model is the keyword "uri" so you can select "uri" or you can use the template for "model name". Either choice will lead you through naming the model. The default is derived from the file name given. If you choose "uri" from the menu, add a space to indicate that the word is complete before asking for content assistance again
  2. .
  3. Ask for completion assistance again (Ctrl-space). This time there is more than one choice so a pop-up menu appears. Select the Uri option with a double click or a single click and the Enter key.
  4. Make the URI unique to this model by adding some model-specific ending, e.g, ".../myfamily/concepts".
  5. At this point you can end the statement with a period or you may again request assistance (Ctrl-space), in which case your choices will be to add an End of Sentence (period) or to add version.

    For now, let's end this sentence with a period.
  6. Press the Enter key to go to the next line. Note: a SADL model must always end in a space, a tab,  or a New Line. This is because the period is a legal part of a name and the language parser does not know if the period is an end-of-sentence marker unless it is followed by white space.

The Model Name Can Have Version Information (Quick Fix)

  1. At this point you will have a warning marker, identified by a yellow exclamation point and a light bulb (), in the margin to the left of the first statement in your model.

    This small light bulb behind the exclamation point indicates that there are one or more Quick Fixes available for the warning.
  2. Placing the mouse cursor over the marker will cause the cursor to change to a hand and an explanation of the warning to be displayed.

    (The cursor isn't shown in this screen shot.) This message indicates that while it isn't required (this is not an error), including model version information may be desirable.
  3. Clicking on the marker will cause a list of fixes to the warning to be displayed.
  4. Double-clicking a fix will cause the action to be taken. Double-click on Add Model Version.

    The CVS keywords ($Revision: 1.1 $, $Date: 2013/08/06 17:06:20 $) will be augmented with revision number and last modification date as soon as the model is checked into CVS. For example, the version information in this case becomes a string like "$Revision: 1.1 $ Last modified on $Date: 2010/08/06 14:00:16 $".

    Note: In SVN, keywords are not necessarily automatically enabled. You may need to modify the SVN properties of a project or, if you prefer, specific files in the project to set the SVN keywords you wish to enable. You can do this from within Eclipse.

Defining Classes and Properties (Templates)

  1. Let's begin by declaring the Person concept. With the cursor at the beginning of a new line, ask for content assistance (Ctrl-space). The menu of options will be quite long and will include completions such as we've see above (marked with the icon) and templates (marked with the icon). In this case we wish to select the template for declaring a top-level class.

    A template menu item includes a name and a description. You can type the first letter of the name to get a reduced list of options. Once a template is selected in the menu the syntax of the template is shown in a window to the left of the menu. Select the "class" template by double clicking or selecting (single-click or down arrow to) and pressing Enter.
  2. The class declaration statement will be inserted into the model and the text "ClassName" will be highlighted ready for the user to type in the name of the new class.


    Type "Person" as the name of the new class.

  3. Let's think about the attributes and relationships that might be important for the Person class. We will call properties that take data values (numbers, strings, dates) attributes. We will call properties that relate one instance to another instance relationships. If we place the cursor in front of the period at the end of our new statement and ask for content assistance, we get this menu:

    Note that the options include adding an attribute and adding a relationship, single-valued or multi-valued. A Person can have a birthdate, and usually only one, so let's select single-valued attribute. After selecting the template the grammar for the attribute is inserted into the model and the "PropertyName" is selected ready for replacement by the name typed. After typing "birthdate" as the property name, press the Tab key to go to the range and select "date". The resulting class declaration should look like this:
  4. Let's add two new subclasses of Person. We can do this in a single statement by going to a new line and asking for assistance. Pressing the "c" key will cause only class-related templates to be shown.

    Note that even though the "c" is entered in the model (the cause of the error marker a that line), selecting a template from the list will replace the "c" with the correct grammar. We want to select "class-subtypes". After replacing "Class1Name" with Man press the Tab key to move the cursor to next subclass name and replace "Class2Name" with Woman.
  5. Now let's go back and add some more information to the Person class. Place the cursor after "date" and before the period and ask for assistance.

    Depending on how you define the "mother" and "father" relationships, you may wish to select relationship-sv or relationship-mv. We'll take a biological view in the tutorial and select single-valued relationship. The range of "mother" will be Woman and the range of "father" will be Man. We'll also insert a comma, a new-line, and a tab before each of the added clauses to shorten the length of the line.

    Note that you may click on the icon front of Person to hide the detail and make more of the model visible in a given window. If you do so you can still see the complete definition of Person by moving the mouse cursor over the icon in front of Person.
  6. Finally, let's add some more classes and properties to round out our basic model.
    Using the "class" template, create a class named Gender. Place the cursor before the period at the end of the statement, request help, and select the "mustBe" template. Fill in Male as the first name, press tab, fill in Female as the second name, and delete the extra comma.
           
            Gender
    is a class must be one of {Male,Female}.

    Place the cursor before the period at the end of the Person definition, request help, and select the "described by, relationship-sv" template. Fill in "gender" as the property name and accept Gender as the range.

New SADL Constructs for Classes

  1. Now lets add a restriction that Man and Woman are disjoint, meaning that an single instance of Person cannot be a member of both classes. At the beginning of a new line request help and select the "disjoint" template. Type "M" and press Enter or select Man from the menu, press tab, then similarly select Woman.

            Man and Woman are disjoint.
     
  2. Define {Parent, Father, Mother} as types of Person. Further define a Parent as a Person with at least one child. We can then define Father as the intersection of Man and Parent and Mother as the intersection of Woman and Parent. You can do this using the "same as" template, entering Father, and replacing the single-class range with an intersection; same for Mother.

            {Parent, Father, Mother} are types of Person.
               A
    Person is a Parent only if child has at least 1 value.
               Father
    is the same as {Man and Parent}.
               Mother
    is the same as {Woman and Parent}.
     
  3. Define {Child, Adult} as types of Person. Now you can define Child as anyone who is not an Adult. You may use the "same as not" template.

            {Child, Adult} are types of Person.
               Child
    is the same as not Adult.

New SADL Constructs for Properties

  1. Let's define a new relationship called "spouse". Use the "relationship-single-valued" template, filling in Person as the domain and the range of the relationship. With the cursor before the ending period of the statement (and after a comma perhaps), request help and select the "symmetric" template.

            spouse describes Person with a single value of type Person, is symmetric.

    By making "spouse" symmetric, we allow an OWL reasoner to conclude that if Eve is the spouse of Adam then Adam is the spouse of Eve. Note that the "with a single value" phrase places a maximum cardinality restriction on the spouse property on class Person. To say that spouse is functional (can only have a single value regardless of the subject class), one would say:
       
            spouse describes Person with values of type Person, is symmetric, has a single value.
     
  2. Another useful relationship type in OWL is the "inverse of" relationship between two properties. At the beginning of a new line, ask for help and select the "inverse of" template. This relationship allows an OWL reasoner to conclude that if Adam is the parent of Cain, then Cain is the child of Adam, and vice versa.

           parent describes Person with values of type Person.
             parent
    is the inverse of child.
     
  3. Yet another useful relationship type in OWL is the transitive property. Consider this addition to our model.

            Location is a class, described by latitude with a single value of type double,
                       
    described by longitude with a single value of type double,
                       
    described by description with values of type string.
               locatedIn
    describes Location with values of type Location, is transitive.

    By making "locatedIn" a transitive property, we allow an OWL reasoner to conclude that if Atlanta is locatedIn Georgia, and Georgia is locatedIn the USA, then Atlanta is locatedIn the USA.

New SADL Constructs for Instances

  1. To better illustrate some of the new instance support in SADL V2, we will first refactor our model (not an uncommon practice in the early stages of a modeling project). We will move information which was previously associated directly with a Person, specifically the "birthdate" and "mother", into a subtype of Event called Birth. Here's the revised definition of Person:

            Person is a class described by birth with a single value of type Birth,
                       
    described by father with a single value of type Man,
                       
    described by gender with a single value of type Gender.

    Here's the Event and Birth definitions:

              Event is a class, described by location with a single value of type Location,
                       
    described by when with a single value of type date.
             
    Birth is a type of Event described by mother with a single value of type Person,
                       
    described by child with values of type Person.

    Note that our definition of "parent" as the inverse of "child" no longer makes sense so we remove it from the model. Since we didn't do anything with "parent" other than illustrate the concept of an inverse relationship, we also remove it. Note also that since Birth is a type of Event, Birth is also described by "location" and "when" properties. Note that "child" is not restricted to a single value--a Birth can have multiple children.

  2. We will create a new file (model) to populate with instance data relating to a particular group of people. (It wouldn't make much sense to define the general concepts of a genealogy model and put some very specific instance data in the same model.) We create a new file George.sadl with this initial content:

            uri "http://sadl.org/myfamily/george" version "$Revision: 1.1 $ Last modified on $Date: 2013/08/06 17:06:20 $" .

              
    import "Concepts.sadl" as cpt.

    Note that our new model imports our Concepts model so that we can use the classes and properties we've already defined.
  3. Now we are ready to illustrate one of the new instance data features of Version 2. Note that many (most) of the instances of things in the real world are not given unique names. This is even more true of instances of non-physical concepts. We identify these by their relationship to something else: "Mary's car", "John's party", "my address". Even when something has a name, we may wish to identify it in the context of something else. Consider this instance declaration.

            George is a Person has birth
                      (
    a Birth with mother (a Person Mary), with location
                               (
    a Location with latitude 38.186111, with longitude -76.930556, with description "Pope's Creek Estate"),
                              
    with when "1732-02-22").

    Note that we have not had to give a name to the Birth--it's George's Birth; we have not had to give a name to the Location, although it has a human-readable description which is not a legal URI name; and note that Mary is defined as a Person in-line rather than somewhere else in the model.
  4. SADL V2 allows instance data statements to be in several different formats. For example, the following are all equivalent statements:

            George spouse Martha.
              George
    has spouse Martha.
              Martha
    is the spouse of George.
              The
    spouse of George is Martha.
              George
    with spouse Martha.

    Furthermore, these various orderings of subject, predicate, and object and various optional connective words are consistently available in rules, queries, and tests as well as in instance data declarations.
  5. OWL assumes an Open World, meaning that just because I don't know something is true doesn't mean that I can conclude that it is false. In other words, I don't assume that I know everything there is to know. Therefore we may sometimes wish to express that we know that two instances are not the same instance. For example,

           
    George is not the same as Mary.
     
  6. Similarly, we might wish to state that two instances are, in fact, the same instance, meaning that the instance has two different names. This is particularly useful if we are using two ontologies that have different names for the identical instance. For example,

           
    GeorgeWashington is the same as George.

    Note that we can also say a similar thing about two classes or two properties. In SADL "is the same as" is used for instances, classes, and properties although the OWL translation is to different OWL constructs.

Summary and Conclusion

This version of the SADL V2 Quick Start Tutorial does not cover all of SADL functionality. Rather it is meant to illustrate two key additions to SADL V2 and assumes some familiarity with SADL V1. These key additions are: 1) much richer assistance for model authors including statement completion, templates, hyper linking to definitions, etc., and 2) full support of OWL-DL. The tutorial will be expanded as the rest of SADL functionality is implemented in V2. Yet to be implemented and included are:

  1. Rules and expressions
  2. Queries
  3. Explanations
  4. Tests and test suites