Skip to main content

Tonto Language Reference

Welcome to the Tonto language reference! Tonto is a textual modeling language designed for creating well-founded ontologies based on the Unified Foundational Ontology (UFO). It combines the rigor of ontological modeling with the developer-friendly benefits of a textual DSL.

Introduction​

Why Tonto?

  • UFO-Based: Built-in support for ontological concepts like Kinds, Roles, Relators, and Events.
  • Textual: Works great with Git, diffs, and standard text editors.
  • Tooling: Enjoy syntax highlighting, validation, and auto-completion in VS Code.

1. Getting Started​

File Structure​

A Tonto file (.tonto) typically follows this structure:

  1. Imports: Bring in types from other packages.
  2. Package Declaration: Define the namespace for your elements.
  3. Declarations: Your classes, relations, and other elements.
import core.people

package university.students

role Student specializes core.people.Person {
    studentId: string
}

Packages​

Packages are the primary way to organize your ontology. Every file belongs to a package.

package my.ontology.core

You can also declare a global package which makes its contents available everywhere without imports (useful for core primitive types), but standard packages are recommended for most code.

Imports​

To use elements from another package, you must import that package first.

import university.professors
import university.courses as Courses // You can use aliases!

package university.schedules

// Now you can use types from the imported packages
relation university.professors.Professor [1] -- teaches -- [*] Courses.Course

2. Modeling Fundamentals​

Classes​

Classes are the building blocks of your ontology. In Tonto, you rarely use the generic class keyword. Instead, you use stereotypes that define the ontological nature of the entity.

Basic Syntax:

<Stereotype> <Name> {
    <AttributeName>: <Type>
    <Relation>
}

Example:

kind Person {
    name: string
    birthDate: date
}

Attributes​

Attributes define the data properties of your classes.

Syntax: name: type [cardinality]

  • Types: string, number, boolean, date, datetime, or custom datatype/enum.
  • Cardinality:
    • [1] (Default): Exactly one.
    • [0..1]: Optional.
    • [*] or [0..*]: Zero or more.
    • [1..*]: One or more.

Example:

kind Car {
    vin: string { const }       // Immutable identifier
    nickname: string [0..1]     // Optional
    previousOwners: string [*]  // List of names
}

Basic Relations​

Relations connect your entities. You can define them inside a class (Internal) or outside (External).

Internal Relation (Recommended for simple links):

kind Person {
    // "I have a relation 'owns' to 'Car'"
    [0..*] -- owns -- [0..*] Car
}

3. Ontological Stereotypes​

Choosing the right stereotype is the most important part of modeling in Tonto. Here is a guide to the most common ones.

Sortals (Identity Providers)​

These types provide the principle of identity for their instances.

  • kind: The fundamental type of an object. An object cannot stop being its kind without ceasing to exist.
    • Examples: Person, Dog, Car, Organization.
  • collective: A collection of parts that plays a uniform role.
    • Examples: Team, Forest, DeckOfCards.
  • quantity: A portion of matter.
    • Examples: Water, Sand, Gold.
  • relator: An entity that connects other entities (the "glue" of a relationship).
    • Examples: Marriage, Employment, Enrollment.
  • mode: An intrinsic property that is not a simple value.
    • Examples: Skill, Belief, Headache.
  • quality: A property that can be measured or compared.
    • Examples: Weight, Height, Color.

Specializations (Inherit Identity)​

These types specialize a Sortal.

  • subkind: A rigid specialization. If you are this type, you are always this type.
    • Examples: Man (specializes Person), Truck (specializes Vehicle).
  • role: A contingent specialization based on a relationship. You play this role in a context.
    • Examples: Student, Employee, Husband.
  • phase: A contingent specialization based on an intrinsic state. You are in this phase for a time.
    • Examples: Child, Adult, Caterpillar, Butterfly.

Non-Sortals (Mixins)​

These types classify instances of different Kinds. They define properties but not identity.

  • category: Rigid. Essential properties shared by multiple kinds.
    • Examples: PhysicalObject (covers Car and Person), SentientBeing.
  • mixin: Semi-rigid. Essential to some, accidental to others.
    • Examples: Insurable (Car is insurable, House is insurable).
  • roleMixin: Anti-rigid. Defines a role played by different kinds.
    • Examples: Customer (can be Person or Company).

4. Relations in Depth​

Part-Whole Relations​

Tonto supports Aggregation and Composition to model "has-part" relationships.

  • Aggregation (<>--): The part can exist independently or be shared.
    • Syntax: Whole <>-- Part (Diamond on the Whole side)
    • Example: Team [1] <>-- hasMembers -- [*] Person
  • Composition (<o>--): The part depends on the whole for existence (exclusive).
    • Syntax: Whole <o>-- Part (Filled diamond on the Whole side)
    • Example: Car [1] <o>-- hasEngine -- [1] Engine

Relation Stereotypes​

Just like classes, relations have meanings.

  • @material: A physical connection, usually derived from a Relator.
  • @mediation: Connects a Relator to the entities it mediates. Crucial for Relator patterns. 
    relator Marriage {
        @mediation [1] -- [1] Husband
        @mediation [1] -- [1] Wife
    }
  • @componentOf: Functional part-whole relationship.
  • @memberOf: Membership in a collective.
  • @subCollectionOf: Part of a collection.

External Relations​

Useful when defining relations between classes in different packages or to keep class definitions clean.

@material relation Person [1] -- worksFor -- [1..*] Company

5. Advanced Modeling​

Generalization Sets​

Generalization sets (gensets) group subclasses and define constraints.

  • disjoint: An instance can be only one of the subclasses.
  • complete: An instance must be one of the subclasses.

Example:

// A Vehicle is either a Car or a Truck, never both, and nothing else.
disjoint complete genset VehicleType {
    general Vehicle
    specifics Car, Truck
}

Multi-Level Modeling​

Tonto supports higher-order types (types of types).

  1. Define a Higher-Order Type: 
    type Species
  2. Instantiate it: 
    // Dog is a Kind of entity, but it is also an instance of the type 'Species'
    kind Dog (instanceOf Species)

Powertypes: A powertype is a type whose instances are all possible subtypes of a base type.

6. Project Organization​

Best Practices​

  • One Package per File: Keep your file structure logical.
  • Use tonto.json: This file at your root defines your project metadata and dependencies.
  • Use tpm: The Tonto Package Manager handles external dependencies.

Example Folder Structure​

my-project/
├── tonto.json
└── src/
    ├── core/
    │   ├── people.tonto      (package core.people)
    │   └── places.tonto      (package core.places)
    └── domain/
        └── university.tonto  (package domain.university)

Happy Modeling!