Nemo Ufes Tonto Tonto

Tonto Ontology Modeling

Tonto is a textual modeling language for creating well-founded ontologies based on the Unified Foundational Ontology (UFO). It is the textual counterpart to OntoUML, bringing ontological rigor into a code-like syntax that supports version control, modularization, and automated processing.

Task Routing

When working with a Tonto project, identify what the user needs and read the appropriate reference file:

For basic syntax questions, CLI usage, or project structure, the information below is sufficient.

Important workflow rule: Before executing any significant change, plan your approach step-by-step and present it to the user for confirmation. Only proceed after they approve or suggest modifications.

Core Syntax Reference

Package and Imports

Every .tonto file defines exactly one package. Imports come before the package declaration.

import core.persons
import core.organizations as orgs

package events.academic

// ... declarations ...

A package is defined by its file, not its directory. The folder structure is organizational only.

Class Declarations

<stereotype> <ClassName> (of <nature1>, <nature2>)? (specializes <Super1>, <Super2>)? (instanceOf <HigherOrderType>)? {
    label { @en "..." @pt-br "..." }
    description { @en "..." @pt-br "..." }
    // attributes
    // internal relations
}

Stereotypes

Choosing the correct stereotype is the most important modeling decision. It reflects the ontological nature of the concept according to UFO.

Ultimate Sortals (provide identity principle — every sortal must ultimately specialize one):

Sortals (inherit identity from an ultimate sortal):

Non-Sortals (classify instances across multiple kinds):

Perdurants:

Neutral: class — use only when undecided; the editor will warn.

Ontological Natures

For non-sortals, constrain what kinds of instances they can have:

category PhysicalObject of objects
roleMixin Borrowable of functional-complexes, collectives

Available natures: objects, functional-complexes, collectives, quantities, relators, intrinsic-modes, extrinsic-modes, qualities, events, situations, types, abstract-individuals.

Attributes

kind Person {
    name: string [1]
    age: number { derived }
    nicknames: string [*] { ordered }
    ssn: string [0..1] { const }
}

Built-in types: string, number, boolean, date, time, datetime.

Cardinalities: [1] (default), [0..1], [*] (= [0..*]), [1..*], [2..5].

Meta-properties: ordered, const, derived.

Reserved Keywords — Cannot Be Used as Attribute Names

The following words are reserved in Tonto and must not be used as attribute or datatype field names. If you need to express a concept that would naturally use one of these words, prefix it with an underscore or choose a synonym.

Declaration/stereotype keywords: kind, collective, quantity, quality, mode, relator, type, powertype, subkind, phase, role, historicalRole, category, mixin, phaseMixin, roleMixin, historicalRoleMixin, event, situation, process, class, datatype, enum, relation, genset, intrinsicMode, extrinsicMode

Structural keywords: label, description, specializes, instanceOf, of, import, package, disjoint, complete, general, specifics, categorizer, where, inverseOf

Common pitfalls and fixes:

Example:

// BAD — will cause parse errors:
kind Metric {
    value: number        // "value" conflicts with reserved usage
    description: string  // "description" is a reserved block keyword
}

// GOOD — use prefixed or alternative names:
kind Metric {
    _value: number
    summary: string
}

Datatypes and Enumerations

datatype Address {
    street: string
    city: string
    zipCode: string [0..1]
}

enum EyeColor { Blue, Green, Brown, Black }

Relations

Connectors:

• -- : general association
• <>-- : aggregation (shared part-whole, diamond at source)
• <o>-- : composition (exclusive part-whole, diamond at source)

Relation stereotypes (prefix with @): @mediation, @componentOf, @memberOf, @subCollectionOf, @material, @formal, @characterization, @instantiation, @termination, @participational, @participation, @historicalDependence, @creation, @manifestation, @bringsAbout, @triggers, @externalDependence, @subQuantityOf.

Internal relations (inside a class body — the class is the source):

kind University {
    @componentOf [1] <o>-- hasDepartments -- [1..*] Department
}

relator Employment {
    @mediation [1..*] -- [1] Employee
    @mediation [1..*] -- [1] Employer
}

External relations:

@material relation Person [0..*] -- enrolledIn -- [0..*] Course

End meta-attributes:

({ ordered, subsets previousContracts } formerContracts)

Generalization Sets

Short syntax:

disjoint complete genset PersonPhases where Child, Teenager, Adult specializes Person

Expanded syntax (with categorizer):

type PersonAgePhaseType
disjoint complete genset PhasesOfPerson {
    general Person
    categorizer PersonAgePhaseType
    specifics Child, Teenager, Adult
}

• disjoint: instance of superclass can belong to at most one subclass in the set.
• complete: instance of superclass must belong to at least one subclass in the set.
• Both together = partition.

Multi-Level Modeling

Powertype (all possible specializations of a base type):

powertype CarModel specializes Car
subkind Sedan (instanceOf CarModel) specializes Car

Categorizer (specific subset based on a criterion):

type PropulsionType specializes CarModel
disjoint complete genset CarPropulsion {
    general Car
    categorizer PropulsionType
    specifics ElectricCar, GasolineCar, HybridCar
}

Project Structure

my-ontology/
├── src/           # .tonto source files
├── lib/           # External packages (managed by tpm)
├── generated/     # Output artifacts (JSON, GUFO)
└── tonto.json     # Project manifest

CLI Commands

• tonto-cli init — Initialize new project
• tonto-cli validate <dir> — Validate (add --with-api for API-based checks)
• tonto-cli generate <dir> — Generate JSON representation
• tonto-cli transform <dir> — Transform to GUFO (Turtle/TTL)
• tonto-cli import <file.json> — Generate .tonto from JSON
• tpm install — Install dependencies
• tpm add <package> — Add a dependency

Best Practices

• Modular design: Use separate .tonto files for distinct conceptual domains. Use imports to connect them.
• Accurate stereotyping: The stereotype choice is the most consequential decision. Understand UFO distinctions (rigidity, sortality, identity, dependence) before choosing. Avoid using generic class when the ontological nature is clear.
• Clear naming: PascalCase for types, camelCase for attributes and relation ends. Relators are nouns representing the relationship; roles reflect the role played.
• Precise cardinalities: Define them carefully for both attributes and relation ends.
• Ontological natures for non-sortals: Use the of <nature> clause to constrain instances.
• Meaningful gensets: Structure taxonomies explicitly with disjoint and complete.
• Always check linter errors: They surface ontological inconsistencies.

Source: nemo-ufes/Tonto — distributed by TomeVault.