Ontology: Planning Your Data Model

DarkLight operates on a data model (a way to describe reality in a way a computer can use it). Before you start to put data into the system you should have a good understanding of how it utilizes different kinds of information. DarkLight refers to data in a structured way called an Ontology.

DarkLight needs to have data described to it in a way that it can work with. It does this by using an ontology, which is a way to name and define the relationships between entities in a particular domain. In a nutshell, you'll describe your data in an abstract way (e.g., Class → Employee and Property → First Name) and then later apply that to specific things (e.g., Object → John).

  • Class is a basic unit of something that optionally (typically) has properties that define it.
    • For example: Employees, Computers, Offices, Buildings, etc.
  • Property defines the entities represented in a class, and can represent different types of data as well as objects.
    • For example: First Name, Last Name, Office Number, Start Date
    • Data Properties are different types of data including text, number, date, etc.
      • For example: First Name would be text, Office Number is probably a number, and Start Date is a date.
    • Object Property is a special type of property because it's a property of a class but also has data properties of its own.
      • For example: Manager
  • Object is a specific instance of one or more classes.
    • For example: John, Smith, 345, 09/11/2003.

Naming Conventions

Looking at the example above, we could say that (class) employee has (properties) First Name, Last Name, Office Number, etc., so we represent them conventionally as hasFirstName, hasLastName hasOfficeNumber, etc. Typically, class names are capitalized (UpperCamelCase) and property names are lowerCamelCase.

  • Classes in DarkLight are represented by a circle icon .
  • Data Properties have a square icon .
  • Object Properties are represented by a circle in a square .
Invalid Link
Diagram of an Object – an instance of the Class "Employee" showing its properties as arrows pointing to the property values.

TIP: Friendly Labels

DarkLight can either show ontology items in the prefix:propertyName URI style or using the Property Name friendly label. The friendly name is defined with the Label value of the ontology item. To turn Friendly Names on or off system-wide, visit the preferences at Window→Preferences and toggle the "Use Friendly Labels" checkbox. See also: Using Friendly Labels

Superpowers

Part of the power of using an ontology is that you can connect things together so the reasoner can make assertions automatically.

Sub-Property Of (Sub Of)

Let's say you are using log data that has destination_ip and source_ip fields. Both of these are IP Addresses, but they have different meanings. Sometimes you'll want to create operations that use any IP Address and sometimes you'll want to be more specific. By making the destination and source ip fields sub-properties of hasIPAddress you can refer to something with hasDestinationIPAddress and the reasoner can infer that it is also an IP address.

Equivalent To

If you have two things which are the same but perhaps they are from different ontologies, you can link them together by using the Equivalent To field. For example, here's what it would look like if you made the "enterprise" ontology's IP address ent:hasIPAddress equivalent to the "user" ontology's IP address usr:hasIPAddress.

Invalid Link
Modifying the ontology is done on the Create perspective, using the Ontology Class, Ontology Data Property, and Ontology Object Property views. Each of these views has a corresponding Details view that shows properties of the selected item and allows for editing. Each of the three sets of views operate the same way, as described above. (See Managing Windows for information on views and perspectives).

Adding a Class in DarkLight

To add a new class, first decide where it will go in the tree. If it should be a top-level class, select owl:Thing at the top of the tree and then click the Create Sub Class icon. A window will open up with fields to fill out.

  • Name: The name of the class. By convention, classes start with a capital letter and use CamelCase. All characters except < > " space { } | \ ^ ` are allowed. Numbers can be used but not as the first character in the name. The name will be combined with the ontology prefix to form what shows up in the rest of the system. The example above would be usr:MyNewClass.
  • Label: An optional field that can be used to present a nicer format of the name. The Label name is shown when the "Friendly Labels" preference is on.
  • Description: An optional field that can be used to document what the class is for.
  • Image: An optional icon can be chosen from a pre-configured list. The icon will show up in the Results Graph if this class is linked as a Type for an event or other object.
  • SubClass Of: Automatically contains the selected class when the Create button was clicked, but can be changed to any other class if desired. Top-level classes are always sub-classes of owl:Thing.
  • Ontology: Each class must be a member of an ontology. Choose an ontology from the list. The User (usr) ontology will always be available, and new ontologies can be created from the Ontology Manager.

Adding a Data Property in DarkLight

To add a new data property, first decide where it will go in the tree. If it should be a top-level data property, select owl:topDataProperty at the top of the tree and then click the Create Sub Data Property icon. A window will open up with fields to fill out.

  • Name: The name of the data property. By convention, data properties start with a lowercase letter (and typically with the word "has" and then use CamelCase. All characters except < > " space { } | \ ^ ` are allowed. Numbers can be used but not as the first character in the name. The name will be combined with the ontology prefix to form what shows up in the rest of the system. The example above would be usr:hasDataProperty.
  • Label: An optional field that can be used to present a nicer format of the name.The Label name is shown when the “Friendly Labels” preference is on.
  • Description: An optional field that can be used to document what the property is for.
  • Range: Tells the system what kind of data the property holds. See below for details.
  • Sub Data Property Of: Automatically contains the selected property when the Create button was clicked, but can be changed to any other class if desired. Top-level properties are always sub-classes of owl:topDataProperty.
  • Ontology: Each property must be a member of an ontology. Choose an ontology from the list. The User (usr) ontology will always be available, and new ontologies can be created from the Ontology Manager.

Data Property Ranges

Although the process for creating ontology items is very similar, data properties require one more piece of information to be fully useful. Each data property should be assigned a range that tells the system what kind of data it holds.

  • boolean: for values that are either on or off (yes/no, on/off, 0/1)
  • date: for values that contain just a date with no time component (12/30/2016)
  • dateTime: for values that contain both a date and a time (12/30/2016 00:14:34)
  • double: for numbers with decimal points
  • int: for whole numbers up to 2^32
  • long: for whole numbers up to 2^64
  • string: for text or anything that should be represented literally as it is in the data (Mike, 123abc, 127.0.0.1)
  • time: for values that contain a time with no date (00:14:34)

Adding an Object Property in DarkLight

To add a new data property, first decide where it will go in the tree. If it should be a top-level object property, select owl:topObjectProperty at the top of the tree and then click the Create Sub Object Property icon. A window will open up with fields to fill out.

  • Name: The name of the object property. By convention, object properties start with a lowercase letter (and typically with the word "has") and then use CamelCase. All characters except < > " space { } | \ ^ ` are allowed. Numbers can be used but not as the first character in the name. The name will be combined with the ontology prefix to form what shows up in the rest of the system. The example above would be usr:hasObjectProperty.
  • Label: An optional field that can be used to present a nicer format of the name. The Label name is shown when the “Friendly Labels” preference is on.
  • Description: An optional field that can be used to document what the property is for.
  • Sub Object Property Of: Automatically contains the selected property when the Create button was clicked, but can be changed to any other class if desired. (Note: A known bug of this version prevents the Sub Object Property change from taking effect. The new property will always be a sub of whatever is selected in the tree.) Top-level properties are always sub-classes of owl:topObjectProperty.
  • Ontology: Each property must be a member of an ontology. Choose an ontology from the list. The User (usr) ontology will always be available, and new ontologies can be created from the Ontology Manager.

Managing Ontologies

These descriptions are gathered together in a structured format called an ontology. DarkLight can utilize multiple ontologies at the same time, and comes preloaded with a few ontologies that you can use to help describe your data.

To see a list of the ontologies DarkLight has available, open the Ontology Manager view. By default, this view is on the Create perspective, but if it's not open you can open it by choosing Window→Show View and picking it from the list.

Ontologies are typically named with a Universal Resource Locator (URL) because the original intent was that they would live on the internet and be universally available. In practice, however, not all ontologies have resolvable addresses so things can get a bit confusing. DarkLight uses the Internationalized Resource Identifier (IRI) specification. This allows an ontology to have either an http:// or a tag: syntax.

Regardless of their full IRI, to make statements made with ontologies much easier to read, DarkLight uses a prefix to represent the ontology's address. For example, if you wanted to refer to an Employee class in the enterprise ontology, you could either use tag:champtc:enterprise#Employee or just ent:Employee.


DarkLight can create ontology owl files from the Ontology Manager. This is useful if you want to keep your classes and properties in separate files for ease of sharing with others. To add a new ontology to DarkLight, click the + button in the Ontology Manager.

URI: The long name of the ontology. Any form of term:term will technically be valid, but using the forms of http://mycompany.com/name or tag:mycompany:name is recommended. Using your company name in an ontology name allows for help in attribution if you share it with others.

Prefix: The short name the system will prepend to objects specified in the ontology. For example, a class of Test in the example shown above would be listed as name:Test. Prefixes are typically short and do not contain special characters.

Filename: The name of the file that will be created. DarkLight will add the .owl extension. The file is stored in <your workspace>/configuration/domain.cybersetics/ontologies/user

Adding a New Ontology from an External Source

To add an external ontology to DarkLight:

  1. Shut down DarkLight
  2. Put the .owl file(s) into the folder at <your workspace>/config/ontologies/user
  3. Start DarkLight again.

The Ontology Manager will show the new ontology and give it a prefix of "ns1". To change the prefix to something more customized, double-click the ontology name (or click the ontology name to highlight and then choose the Edit Prefix icon from the view tools) and enter in the new prefix in the dialog that opens. Note that not all external ontologies will work perfectly in DarkLight. You may need to make some edits in an external editor. Check the Log View for errors when using an external ontology.

NOTE

DarkLight uses the OWL API to transform ontologies into usable components. Due to the open-world nature of ontologies, not all aspects of all ontologies are successfully used by DarkLight. For some imported ontologies, especially those that contain individuals or collections, you may see an error in the Log view like, Server reports problem: Lexical error at line 223, column 536. Encountered: "93" (93), after : "en". Errors like this in the Log indicate a problem loading in the ontology, and DarkLight will not load any ontologies that have issues. Please send any owl files you would like to use but cause errors to support@darklightcyber.com so we can evaluate it.
  • help/planning
  • Last modified: 2019/03/28 20:34