Introduction

What is Dolfin?

Dolfin is a language for modelling knowledge.

You use it to describe the concepts in a domain, the relationships between them, the constraints they must satisfy, and the rules that can be inferred from them. The result is an ontology: a precise, human-readable definition of what exists in your world and how the pieces fit together.

Dolfin is not tied to any particular storage backend or runtime. The model you write is independent of whether your data lives in a graph database, a relational database, a document store, or something else entirely. Dolfin describes what your data means; the implementation decides where and how it is stored and queried.

This separation is what makes ontologies powerful. The same model can drive validation in one system, feed a reasoning engine in another, and serve as shared vocabulary across a team, all without being rewritten.

What is an ontology?

The word ontology comes from philosophy. It’s the study of what exists. In software, an ontology is a formal description of the concepts in a domain and the relationships between them.

Think of it like a schema, but with more expressive power:

Dolfin lets you express all of that in a clean, readable file.

What you will build

This tutorial follows Dr. Helen Portbridge as she designs the data model for her new veterinary clinic, Happy Paws. Over fourteen chapters, starting from a blank file, you will build a complete ontology that:

• Describes animals, owners, appointments, and veterinary staff
• Enforces rules like “a surgeon must be on call for any surgery”
• Automatically flags at-risk or overdue patients
• Connects to external registries using standard IRIs

By the end, you will have touched every major feature of the language.

What Dolfin looks like

Here is a small taste. Don’t worry about the details, each piece will be introduced step by step.

concept Animal:
  has name: one string
  has species: one Species
  has owner: optional Owner
  has vaccinations: Vaccination

concept Dog:
  sub Animal
  has breed: optional string
  has neutered: one boolean

rule flag_unvaccinated:
  match:
    ?animal a Animal
    ?animal vaccinations 0
  then:
    ?animal a UnvaccinatedAnimal

Dolfin is designed to be readable without training. A domain expert, a developer, and a data architect can all look at the same file and understand it.

How to read this tutorial

The tutorial is structured as a story. Each chapter opens with a short scene from the clinic, poses a new modelling problem, introduces the Dolfin feature that solves it, and ends with a prompt for the next problem.

You can read it cover to cover, or use it as a reference. The Reference section at the end is a complete description of the language.

Ready? The clinic opens in Chapter 1.

Chapter 1: Opening Day

Chapter 1: Opening Day

Dr. Helen Portbridge had been dreaming of this day for years. The sign on the door read Happy Paws Veterinary Clinic, the smell of fresh paint still lingered, and the reception desk was empty except for a brand-new laptop. Before any patient walked in, she needed a system. A way to describe every animal, every owner, every appointment that would ever pass through these doors.

She opened a text editor and typed:

Every Dolfin project begins with a package. Think of a package as the identity card of your ontology: its name, its version, who made it, and what it’s for.

package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

Let’s unpack this line by line.

The package name

package <http://happypaws.com/clinic>:

The name uses IRI-notation. If Dr. Portbridge later builds a separate ontology for her research lab, she could call it http://happypaws.com/research and there would be no collision.

The colon (:) at the end is important. It opens an indented block. Everything that belongs to this package declaration must be indented underneath it, exactly like Python.

Metadata

  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

dolfin_version "1" tells the parser which grammar to expect. Right now there is only version 1, but including it means your file will still work when the language evolves.

Try it

Change the author to your own name and hit Check:

package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

Common mistakes

Forgetting the colon:

package <http://happypaws.com/clinic>
  dolfin_version "1"

Dolfin will tell you: “Did you forget a : after the package name?”

Inconsistent indentation:

package <http://happypaws.com/clinic>:
  dolfin_version "1"
    version "0.1.0"   # ← too deep!

All lines inside a block must be at the same indentation level.

Where it lives

A Dolfin project is a folder. package.dlf holds the package declaration above and nothing else. Concepts, properties, rules and facts go in other .dlf files next to it, and the path of each file decides its namespace: a file clinic.dlf in the package http://happypaws.com/clinic lives in http://happypaws.com/clinic/clinic. From the next chapter on, every listing is labelled with the file it belongs in, package.dlf or clinic.dlf.

Dr. Portbridge saved the file as package.dlf. A package with no concepts is like a clinic with no exam rooms, technically it exists, but it can’t do anything yet. She needed to describe the things that would populate her world.

Chapter 2: Meet the Animals

The first patient arrived before the furniture did: a nervous-looking golden retriever named Biscuit, dragged in by an equally nervous owner. Dr. Portbridge grabbed a pen and a napkin and started writing down what she needed to know. Name? Biscuit. Owner? Some guy. Species? Dog. Age? Maybe five?

She looked at the napkin and thought: “I can do better than this.”

A concept is the core building block of any Dolfin ontology. It describes a category of things, not a specific individual, but the shape that all individuals of that kind share.

Your first concept

concept Animal:
  has name: string
  has species: string
  has age: int

This says three things:

1. There is a concept called Animal.
2. An Animal can have a name, which is text.
3. An Animal can have a species (also text) and an age (a whole number).

The keyword has introduces an attribute, a piece of data that instances of this concept can carry. After has comes the attribute name, then a colon, then its type.

No constraints yet. Right now, every attribute has cardinality “any”: zero values, one value, or fifty values are all legal. That’s intentional for a first sketch, but it does mean nothing prevents an Animal with no name or three species. In a later chapter, we’ll learn how to say “exactly one name” or “at most one owner.”

Primitive types

Dolfin ships with four primitive types:

Adding the owner

An animal doesn’t walk into a clinic alone (well, cats might). We need an owner:

concept Owner:
  has firstName: string
  has lastName: string
  has phone: string

Concepts can reference other concepts

Here’s the interesting part. An attribute’s type doesn’t have to be a primitive, it can be another concept:

concept Animal:
  has name: string
  has species: string
  has age: int
  has owner: Owner

has owner: Owner means: an Animal can be linked to an Owner. Not to a string containing the owner’s name, to the actual Owner concept, with all its attributes. This is how you build a graph of interconnected data, not just flat tables.

The story so far

Here’s what we have after this chapter:

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Animal:
  has name: string
  has species: string
  has age: int
  has owner: Owner
  
concept Owner:
  has firstName: string
  has lastName: string
  has phone: string

Try it

Add a weight attribute (as a float) to the Animal concept:

concept Animal:
  has name: string
  has species: string
  has age: int
  has owner: Owner
  
concept Owner:
  has firstName: string
  has lastName: string
  has phone: string

Dr. Portbridge looked at the model and felt a little proud. But as she started typing in Biscuit’s details, she realized something: an appointment isn’t just an animal and an owner. It has a date, a reason, a diagnosis. The animal and the owner exist before the appointment and after it. She needed something to represent the visit itself.

Chapter 3: The Appointment Book

By noon, Dr. Portbridge had seen three patients. She’d scribbled notes on separate napkins, but already she couldn’t remember whether the cat with the limp came before or after the parrot with the cough. She needed a concept for the visit itself, something that ties an animal, a date, and a reason together.

Modeling the appointment

concept Appointment:
  has animal: Animal
  has `date`: string
  has reason: string
  has diagnosis: string
  has treatment: string

Notice that animal is of type Animal, a reference to the concept we defined earlier. This is how relationships emerge naturally in Dolfin. You don’t need a separate “relationship” syntax for simple ownership; has does the job.

Why is date a string? Just to keep this chapter to the basics. Dolfin does have real temporal types (date, time, date_time, and duration) that understand calendars and clocks. We’ll upgrade this string to a proper date_time in Chapter 9: Marking Time.

Standalone properties

So far, we’ve defined relationships inside concepts using has. But some relationships are important enough to deserve their own definition, especially when they could apply to multiple concepts or when you want to give them metadata.

A property is a standalone, reusable relationship:

property treatedBy: Animal -> string

This reads: “treatedBy is a relationship from Animal to a string.” The arrow (->) separates the domain (what has the property) from the range (what values it takes).

That string is a placeholder. In reality, we’d want a Veterinarian concept. Let’s make one:

concept Veterinarian:
  has name: string
  has licenseNumber: string

property treatedBy: Animal -> Veterinarian

Now treatedBy is a first-class relationship between Animal and Veterinarian, defined separately from either concept.

When to use has vs property

Both compile to OWL properties. The difference is readability and intent.

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Animal:
  has name: string
  has species: string
  has age: int
  has owner: Owner
  
concept Owner:
  has firstName: string
  has lastName: string
  has phone: string

concept Appointment:
  has animal: Animal
  has `date`: string
  has reason: string
  has diagnosis: string
  has treatment: string

concept Veterinarian:
  has name: string
  has licenseNumber: string

property treatedBy: Animal -> Veterinarian

Try it

Add a standalone property owns that goes from Owner to Animal. Then add a property scheduledWith from Appointment to Veterinarian:

concept Animal:
  has name: string
  has species: string
  has age: int
  has owner: Owner
  
concept Owner:
  has firstName: string
  has lastName: string
  has phone: string

concept Appointment:
  has animal: Animal
  has `date`: string
  has reason: string
  has diagnosis: string
  has treatment: string

concept Veterinarian:
  has name: string
  has licenseNumber: string

property treatedBy: Animal -> Veterinarian

# Add your properties here

The appointment book was taking shape. But as Dr. Portbridge typed species: string for the tenth time, she winced. “Dog” could be typed as “dog”, “Dog”, “DOG”, “canine”, or “golden retriever”. A free-text field was an invitation for chaos. She needed a fixed list.

Chapter 4: Species and Breeds

The receptionist had entered “dgo” as the species for a patient. Then “Feline (domestic shorthair)”. Then just “bird”. Dr. Portbridge realized that a string field for species was a liability, it offered infinite freedom where she needed a closed list.

The problem with strings

When a field accepts any string, you get inconsistency:

• "Dog" vs "dog" vs "Canine"
• "Cat" vs "Feline" vs "feline (domestic)"

Queries break. Reports are nonsense. You need a controlled vocabulary.

Closed concepts

A closed concept defines a fixed, exhaustive set of allowed values:

concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

Now replace the string in Animal:

concept Animal:
  has name: string
  has species: Species
  has age: int
  has weight: float
  has owner: Owner

species can only be one of the six values listed in the enum. No typos, no ambiguity, no “dgo”.

Multiple closed concepts

The clinic also needs to categorize appointment urgency:

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

And appointment status:

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

Now Appointment becomes:

concept Appointment:
  has animal: Animal
  has `date`: string
  has reason: string
  has urgency: Urgency
  has status: AppointmentStatus
  has diagnosis: string
  has treatment: string

Enums vs concepts

Enums and concepts are very different things:

Use enums for things that won’t change or change rarely (statuses, categories, units). Use concepts for things that live and breathe (patients, people, appointments).

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: string
  has lastName: string
  has phone: string

concept Veterinarian:
  has name: string
  has licenseNumber: string

concept Animal:
  has name: string
  has species: Species
  has age: int
  has weight: float
  has owner: Owner

concept Appointment:
  has animal: Animal
  has `date`: string
  has reason: string
  has urgency: Urgency
  has status: AppointmentStatus
  has diagnosis: string
  has treatment: string

property treatedBy: Animal -> Veterinarian

Try it

Add an enum PaymentMethod with values Cash, Card, Insurance, and Pending. Then add a payment attribute to Appointment:

concept PaymentMethod:
  one of:
    Cash

concept Appointment:
  has animal: Animal
  has `date`: string
  has reason: string
  has urgency: Urgency
  has status: AppointmentStatus

The enums solved the typo problem. Then a cardboard box appeared on the exam table. Inside was a tiny stray kitten, no collar, no owner, no known age. Dr. Portbridge named her Pixel on the spot and tried to enter her into the system: species Cat, name “Pixel”, and… that was it. No owner to reference, no age to record. The system accepted Pixel without complaint. In fact, it would have accepted an Animal with no name at all, or one with five species. Every attribute had cardinality “any”: no minimum, no maximum, no constraints whatsoever. That was fine for a first sketch, but now she needed precision. “Every animal MUST have exactly one name. An owner might not have an email. A phone number is required.” She needed cardinality.

Chapter 5: Tightening the Rules

Dr. Portbridge had been entering patient data all morning. Then she noticed: the system had accepted an Animal with no name. Another had two species. An Appointment existed with zero dates. Nothing prevented nonsense because every attribute had cardinality “any”, zero or more, no questions asked. The sketch had been useful, but now she needed precision.

The problem

So far, every has declaration is unconstrained. The default cardinality is “any”, meaning zero to infinity. That’s great for rapid prototyping, but a real system needs rules:

• An animal must have exactly one name
• A species is required, and there’s only one
• An age might be unknown (strays, for instance)
• An owner is not always present (think of Pixel, the stray kitten)

Dolfin lets you tighten these rules with cardinality keywords placed between the colon and the type.

Cardinality keywords

The keyword goes after the colon and before the type:

has <attribute>: <cardinality> <Type>

Applying cardinality to Animal

Let’s revisit our Animal concept with proper constraints:

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner

Now:

• name and species are required: exactly one value, always present
• age, weight, and owner are optional: they can be absent

Choosing the right cardinality

This is a modeling decision, not a technical one. Ask yourself: “How many of this attribute can an entity reasonably have? And how many must it have?”

Applying cardinality to Owner and Appointment

Let’s apply the same thinking to Owner:

concept Owner:
  has firstName: one string
  has lastName: one string
  has phone: one string
  has email: optional string
  has address: optional string

And to Appointment:

concept Appointment:
  has animal: one Animal
  has `date`: one string
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatment: optional string
  has notes: string

A diagnosis and treatment are unknown when the appointment is first scheduled: they only get filled in during or after the visit.

Leaving an attribute unconstrained

If you omit the cardinality keyword, you get the default: any (zero or more, no upper limit). This is useful for attributes where you genuinely don’t know the bounds yet, or where any number of values is acceptable:

concept Appointment:
  has notes: string

Here notes has no constraint: an Appointment can have zero notes, one note, or a hundred. That’s sometimes exactly what you want.

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: one string
  has lastName: one string
  has phone: one string
  has email: optional string
  has address: optional string

concept Veterinarian:
  has name: one string
  has licenseNumber: one string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner

concept Appointment:
  has animal: one Animal
  has `date`: one string
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatment: optional string
  has notes: optional string

property treatedBy: Animal -> Veterinarian

Try it

The Veterinarian concept currently requires name and licenseNumber. Add an optional specialization attribute (as a string) and an optional phone:

concept Veterinarian:
  has name: one string
  has licenseNumber: one string

The model finally rejected nonsense. An Animal without a name? Error. An Appointment with no date? Error. Pixel, the stray kitten, was registered with no owner and no known age, and the system accepted her gracefully.

A week later, the clinic ran a vaccination drive. Thirty animals in one day. Dr. Portbridge needed to record which vaccines each animal had received, not one, not two, but a variable number. She tried adding has vaccine: one string but that only held one. She needed a list.

Chapter 6: How Many Vaccines?

Biscuit the golden retriever needed three vaccines: rabies, distemper, and bordetella. Dr. Portbridge tried has vaccine: one string, but that could only hold one value. She tried adding three separate fields, vaccine1, vaccine2, vaccine3, and immediately hated herself for it. What about animals that need five? Or none?

The problem

Sometimes an attribute holds more than one value. A single has vaccine: one string gives you exactly one. The real world isn’t that tidy.

Multi-valued cardinality

In the previous chapter, you learned one and optional. But Dolfin has richer cardinality keywords for multi-valued attributes:

Combined with the keywords from Chapter 5, here’s the full cheat sheet:

Cardinality cheat sheet

Applying cardinality to the clinic

Let’s think about what needs multi-valued cardinality:

Animals can have multiple vaccines, and might have multiple allergies:

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccines: string
  has allergies: string

Here vaccines and allergies use the default “any” that is zero or more strings, no upper limit.

Owners must have at least one phone number but could have several:

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional string

Appointments might involve multiple treatments:

concept Appointment:
  has animal: one Animal
  has `date`: one string
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatments: string
  has notes: string

A concept for vaccines

Actually, a vaccine isn’t just a string. It has a name, a date administered, and a batch number. Let’s promote it to a concept:

concept Vaccination:
  has vaccineName: one string
  has dateAdministered: one string
  has batchNumber: optional string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

Now each vaccination is a rich object, not just a name. And because vaccinations uses the default cardinality (“any”), an animal can have zero, one, or many vaccinations.

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional string

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Vaccination:
  has vaccineName: one string
  has dateAdministered: one string
  has batchNumber: optional string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

concept Appointment:
  has animal: one Animal
  has `date`: one string
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatments: string
  has notes: optional string

property treatedBy: Animal -> Veterinarian

Try it

A Veterinarian can have multiple certifications (at least one) and speaks one or more languages. Add these attributes:

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

The vaccination records looked clean. Biscuit had three entries; Pixel had none yet. The system handled both gracefully.

But then a colleague, Dr. Reyes, joined the practice. He was a surgeon, not a general vet. And Dr. Portbridge realized her model treated every Veterinarian identically. She needed a way to say “a Surgeon is a Veterinarian, but with extra capabilities.” She needed inheritance.

Chapter 7: The Specialist Problem

Dr. Reyes could do everything Dr. Portbridge could, checkups, vaccinations, prescriptions. Plus surgery. Modeling him as a plain Veterinarian would lose the surgery part. Creating a completely separate Surgeon concept would duplicate all the shared fields. Neither option felt right.

The problem

You have two kinds of things that share most of their structure but differ in some aspects. Duplicating attributes across concepts is fragile: change one, forget the other. You need inheritance.

#sub: concept inheritance

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

The keyword sub says: “A Surgeon is a specialization of Veterinarian.” A Surgeon automatically has name, licenseNumber, and specialization (inherited from Veterinarian), plus its own surgeryCount and certifiedProcedures.

In OWL terms, this is rdfs:subClassOf. In object-oriented terms, it’s inheritance. In plain English: every Surgeon is a Veterinarian, but not every Veterinarian is a Surgeon.

Building a hierarchy

Let’s extend this further. The clinic is growing and has different roles:

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

concept Dentist:
  sub Veterinarian
  has dentalCertification: one string

concept Intern:
  sub Veterinarian
  has university: one string
  has year: one int

All four concepts share name, licenseNumber, and specialization. Each adds its own details.

Inheritance for animals too

The Species enum tells us what kind of animal something is, but it doesn’t let us attach species-specific attributes. With inheritance, we can:

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

concept Dog:
  sub Animal
  has breed: optional string
  has neutered: one boolean

concept Cat:
  sub Animal
  has indoor: one boolean

concept Bird:
  sub Animal
  has wingspan: optional float
  has canFly: one boolean

A Dog is an Animal with breed and neuter status. A Bird is an Animal with a wingspan and flight ability. The shared core (name, species, age, etc.) is defined once and inherited everywhere.

Ordering convention

Inside a concept body, put sub first, then has declarations. This isn’t enforced by the parser, but it’s the standard Dolfin style:

concept Surgeon:
  sub Veterinarian            # ← parent first
  has surgeryCount: one int  # ← then own attributes

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional string

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

concept Dentist:
  sub Veterinarian
  has dentalCertification: one string

concept Intern:
  sub Veterinarian
  has university: one string
  has year: one int

concept Vaccination:
  has vaccineName: one string
  has dateAdministered: one string
  has batchNumber: optional string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

concept Dog:
  sub Animal
  has breed: optional string
  has neutered: one boolean

concept Cat:
  sub Animal
  has indoor: one boolean

concept Bird:
  sub Animal
  has wingspan: optional float
  has canFly: one boolean

concept Appointment:
  has animal: one Animal
  has `date`: one string
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatments: string
  has notes: optional string

property treatedBy: Animal -> Veterinarian

Try it

The clinic just hired a Radiologist (a specialized Veterinarian). They have a machineCertifiedOn attribute (a string, the machine name) and a readingsPerformed count. Add the concept:

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

# Add Radiologist here

The model now captured the difference between Dr. Portbridge (general practice), Dr. Reyes (surgeon), and the new dental specialist who started on Tuesdays. The schema was rich enough to describe every living thing that would walk through the clinic’s door.

And then the first patient walked through the door. Biscuit the golden retriever, nervous as ever, dragged in by John Smith. Dr. Portbridge opened the system to register him, and realized she had no way to record a specific dog. The schema described the shape of a Dog. It said nothing about this particular dog, with this particular owner, these particular vaccines. She needed to enter actual data.

Chapter 8: Populating the Clinic

The model had grown up. Dr. Portbridge now had concepts for animals, owners, vets, and appointments, with cardinality constraints, enums, and a full inheritance hierarchy. But the system was still abstract: no actual dogs, no actual owners, no actual appointments. Biscuit, the nervous golden retriever, the first patient of the morning, was sitting in the waiting room. It was time to enter some real data.

The problem

So far, your Dolfin file contains descriptions of categories: what an Animal looks like, what an Appointment requires. It contains no individuals: no specific dog named Biscuit, no actual appointment on a Tuesday afternoon. This is the gap between a schema and a database.

Dolfin fills this gap with facts.

Your first fact

fact DrPortbridge a Veterinarian
  name "Helen Portbridge"
  licenseNumber "VET-2025-001"

The structure mirrors the schema:

• fact introduces an instance declaration.
• DrPortbridge is the instance’s identifier, you can reference it elsewhere as DrPortbridge.
• a Veterinarian asserts that this instance is of type Veterinarian.
• The indented block lists property assertions, one per line: the property name, then the value.

This is the same indentation-based style you already know from concept, rule, and package declarations. No new punctuation to learn.

Primitive values

Facts support all the same primitive types you use in has declarations:

fact Biscuit a Dog
  name "Biscuit"
  species Dog
  age 5
  weight 32.4
  neutered true
  allergies "pollen"

Enum values are written without quotes; the parser resolves them against the property’s declared type.

Referencing other facts

When a property’s type is a concept (not a primitive), the value is a reference to another fact, written with its identifier:

fact JohnSmith a Owner
  firstName "John"
  lastName "Smith"
  phoneNumbers "555-1234"
  preferredVet DrPortbridge

fact Biscuit a Dog
  name "Biscuit"
  species Dog
  age 5
  weight 32.4
  neutered true
  owner JohnSmith

DrPortbridge and JohnSmith refer to the facts declared elsewhere in the file. Order doesn’t matter. The parser resolves identifiers after reading the whole file, so forward references work.

A bare identifier looks for the fact in the current file first, then in the one other file of the package that declares it. To point at a fact in a specific file, use its dotted path (people.customers.alice).

Don’t write :JohnSmith. As in Turtle, a leading colon is the package’s default prefix: :JohnSmith is the IRI <http://happypaws.com/clinic#JohnSmith>, not the JohnSmith fact of clinic.dlf (which is clinic:JohnSmith). package.dlf declares no facts, so the analyzer warns that :JohnSmith points at the package namespace, where JohnSmith is not declared.

Anonymous blocks

Some properties hold a value that is a structured object rather than a primitive or a reference. Biscuit’s vaccination record is a good example: it’s a Vaccination instance that only belongs to Biscuit, with no need for its own global identifier.

Use an anonymous block (square brackets) for this:

fact Biscuit a Dog
  name "Biscuit"
  species Dog
  age 5
  weight 32.4
  neutered true
  owner JohnSmith
  vaccinations [
    vaccineName "Rabies"
    dateAdministered "2024-03-15"
    batchNumber "RB-2024-0042"
  ]

The block’s type (Vaccination) is inferred from the property’s declared range. If the range is an abstract parent concept and you need to specify a subtype, you can add a SubType as the first line of the block:

animal [
  a Dog
  name "Rex"
]

Multi-valued properties

For properties with cardinality some, any, or at least N, simply repeat the property name on multiple lines:

fact JohnSmith a Owner
  firstName "John"
  lastName "Smith"
  phoneNumbers "555-1234"
  phoneNumbers "555-5678"
  preferredVet DrPortbridge

Or write them as a comma-separated list:

fact JohnSmith a Owner
  firstName "John"
  lastName "Smith"
  phoneNumbers "555-1234", "555-5678"
  preferredVet DrPortbridge

Both forms are equivalent. The first reads like structured records; the second saves space when the values are short.

Multiple anonymous blocks work the same way. Biscuit received three vaccines:

fact Biscuit a Dog
  name "Biscuit"
  species Dog
  age 5
  weight 32.4
  neutered true
  owner JohnSmith
  vaccinations [
    vaccineName "Rabies"
    dateAdministered "2024-03-15"
  ]
  vaccinations [
    vaccineName "Distemper"
    dateAdministered "2024-03-15"
  ]
  vaccinations [
    vaccineName "Bordetella"
    dateAdministered "2024-03-15"
  ]

Multiple types

A fact can assert membership in more than one concept, separated by commas:

fact Pixel a Cat, UnvaccinatedAnimal
  name "Pixel"
  species Cat
  indoor true

This is useful when an instance simultaneously belongs to a base concept and a flag concept. Here, Pixel is both a Cat and (currently) an UnvaccinatedAnimal. In practice, flag concepts like UnvaccinatedAnimal are usually derived by rules rather than asserted directly, but the syntax supports both.

A day at the clinic

Here are the facts for opening day at Happy Paws:

# --- Staff ---

fact DrPortbridge a Veterinarian
  name "Helen Portbridge"
  licenseNumber "VET-2025-001"

fact DrReyes a Surgeon
  name "Carlos Reyes"
  licenseNumber "VET-2025-042"
  surgeryCount 0
  certifiedProcedures "Soft tissue"
  certifiedProcedures "Orthopaedic"

# --- Owners ---

fact JohnSmith a Owner
  firstName "John"
  lastName "Smith"
  phoneNumbers "555-1234"
  preferredVet DrPortbridge

# --- Animals ---

fact Biscuit a Dog
  name "Biscuit"
  species Dog
  age 5
  weight 32.4
  neutered true
  owner JohnSmith
  vaccinations [
    vaccineName "Rabies"
    dateAdministered "2024-03-15"
  ]
  vaccinations [
    vaccineName "Distemper"
    dateAdministered "2024-03-15"
  ]
  vaccinations [
    vaccineName "Bordetella"
    dateAdministered "2024-03-15"
  ]

fact Pixel a Cat
  name "Pixel"
  species Cat
  indoor true

# --- Appointments ---

fact Appt001 a Appointment
  animal Biscuit
  `date` "2025-01-15"
  reason "annual checkup"
  urgency Routine
  status Completed
  diagnosis "Healthy"
  treatments "Bordetella booster"

Notice:

• Biscuit in the appointment refers back to the Biscuit fact.
• Pixel has no owner, she’s the stray kitten. The optional Owner cardinality allows this.
• urgency Routine and status Completed are enum values without quotes.

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "1.0.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# ============================================================
#  clinic.dlf: Schema + Opening Day Facts
# ============================================================

# --- Schema (chapters 1–7) ---

concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional string
  has preferredVet: optional Veterinarian

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

concept Vaccination:
  has vaccineName: one string
  has dateAdministered: one string
  has batchNumber: optional string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

concept Dog:
  sub Animal
  has breed: optional string
  has neutered: one boolean

concept Cat:
  sub Animal
  has indoor: one boolean

concept Appointment:
  has animal: one Animal
  has `date`: one string
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatments: string
  has notes: optional string

property treatedBy: Animal -> Veterinarian

# --- Facts (chapter 8) ---

fact DrPortbridge a Veterinarian
  name "Helen Portbridge"
  licenseNumber "VET-2025-001"

fact DrReyes a Surgeon
  name "Carlos Reyes"
  licenseNumber "VET-2025-042"
  surgeryCount 0
  certifiedProcedures "Soft tissue"
  certifiedProcedures "Orthopaedic"

fact JohnSmith a Owner
  firstName "John"
  lastName "Smith"
  phoneNumbers "555-1234"
  preferredVet DrPortbridge

fact Biscuit a Dog
  name "Biscuit"
  species Dog
  age 5
  weight 32.4
  neutered true
  owner JohnSmith
  vaccinations [
    vaccineName "Rabies"
    dateAdministered "2024-03-15"
  ]
  vaccinations [
    vaccineName "Distemper"
    dateAdministered "2024-03-15"
  ]
  vaccinations [
    vaccineName "Bordetella"
    dateAdministered "2024-03-15"
  ]

fact Pixel a Cat
  name "Pixel"
  species Cat
  indoor true

fact Appt001 a Appointment
  animal Biscuit
  `date` "2025-01-15"
  reason "annual checkup"
  urgency Routine
  status Completed
  diagnosis "Healthy"
  treatments "Bordetella booster"

Try it

Register a new patient: a rabbit named Clover, owned by Maria Garcia (phone "555-9900"). Clover is 3 years old, weighs 1.8 kg, and has had one vaccination ("RHDV2", administered "2024-11-01").

fact MariaGarcia a Owner
  firstName "Maria"
  lastName "Garcia"
  phoneNumbers "555-9900"

# Add Clover here

The system was no longer just a blueprint. It knew who worked at Happy Paws, who owned which animals, which vaccines had been given, and which appointments had been completed. Biscuit’s record showed three vaccinations and a clean checkup. Pixel’s record showed none at all.

Dr. Portbridge stared at Pixel’s entry. She was manually scanning for unvaccinated animals, overdue checkups, interns assigned to emergencies. Every check was a thing she had to remember to do. “What if the system could notice these things automatically?” she wondered. She needed the system to reason, to look at the facts and draw its own conclusions.

Chapter 9: Marking Time

Biscuit was due for a booster. Dr. Portbridge was sure of it, but the appointment book fought her every step. One entry read "15/03/2025", another "March 15", a third "2025-03-15". To her they were the same afternoon; to the computer they were three unrelated strings. She couldn’t ask “which vaccinations are overdue?” because a string doesn’t know it’s a date. It was time to give dates real meaning.

The problem with string dates

Back in Chapter 3 we stored a date as a string and promised a better way later. This is later.

A string like "15/03/2025" is opaque. Nothing stops a typo ("2025-13-40"), nothing agrees on the format, and, worst of all, the date carries no meaning the machine can compute with. Dolfin now has four temporal types that fix this:

The value inside the parentheses is a smart literal: you write the date the way a human would, and Dolfin parses it into the exact form an RDF datastore expects (xsd:date, xsd:time, xsd:dateTime, xsd:duration).

Writing dates

The most natural way is to spell it out. Month names are case-insensitive, and the ordinal ending (st, nd, rd, th) is optional:

date(March 15th 2025)     # → 2025-03-15
date(15 March 2025)       # → 2025-03-15
date(Mar 15 2025)         # → 2025-03-15

You can also write it numerically. But 01/06/2025 is ambiguous (is it June 1st or January 6th?), so Dolfin makes you say which order the fields are in with an as mask:

date(15/03/2025 as d/m/y) # → 2025-03-15
date(2025-03-15 as y-m-d) # → 2025-03-15

The separator (/, -, or .) must match on both sides.

Set the locale once

Typing as d/m/y on every date gets old fast. The @locale directive, placed at the top of the file, sets the default field order for the whole file:

@locale d/m/y

fact rabies_shot a Vaccination
  givenOn date(15/03/2025)   # no mask needed the file already knows

Times and timestamps

A time is 24-hour by default; add AM/PM for the 12-hour clock. An appointment slot pairs a day with a time in a date_time:

time(14:30)                          # → 14:30:00
time(2:30 PM)                        # → 14:30:00
date_time(June 1st 2026, 2:30 PM)    # → 2026-06-01T14:30:00

Clinics keep local time, so you can pin a timezone, either inline, or file-wide with @timezone:

@timezone Europe/Brussels

fact checkup a Appointment
  scheduledFor date_time(June 1st 2026, 9:00 AM)  # → …T09:00:00+01:00

An inline offset (time(9:00 AM +02:00)) always overrides the file default.

Durations

A duration measures a span, how long a vaccine stays valid, how far ahead to send a reminder. Write one or more <number><unit> terms in any order:

duration(3y)          # → P3Y      a rabies shot good for three years
duration(2w)          # → P2W      send the reminder two weeks ahead
duration(1h 30min)    # → PT1H30M  a long surgery slot

(The month unit is mo, so it never collides with minutes.)

Upgrading the clinic

Now the appointment book earns its keep. The Appointment gets a real date_time, and a new Vaccination concept records when a shot was given and how long it lasts:

concept Appointment:
  has animal: one Animal
  has scheduledFor: one date_time   # was: has `date`: string
  has reason: string

concept Vaccination:
  has animal: one Animal
  has vaccineName: one string
  has givenOn: one date
  has validFor: one duration

With that, Biscuit’s booster is now a date the system understands, paired with a validity span:

fact rabies_shot a Vaccination
  animal biscuit
  vaccineName "Rabies"
  givenOn date(March 15th 2025)
  validFor duration(3y)

Because givenOn is a real date and validFor a real duration, the machine can now do what Dr. Portbridge couldn’t do by squinting at napkins: compare them, and work out exactly when the protection runs out. That arithmetic is the seed of the alerts we build next chapter.

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Animal:
  has name: string
  has species: string
  has age: int
  has owner: Owner
  
concept Owner:
  has firstName: string
  has lastName: string
  has phone: string

concept Vaccination:
  has animal: one Animal
  has vaccineName: one string
  has givenOn: one date
  has validFor: one duration

fact biscuit a Animal
  name "Biscuit"
  species "Dog"
  age 5

fact rabies_shot a Vaccination
  animal biscuit
  vaccineName "Rabies"
  givenOn date(March 15th 2025)
  validFor duration(3y)

Try it

Add an Appointment fact for Biscuit’s booster with a real date_time, and give the Vaccination a reminderLead of two weeks:

@locale d/m/y

concept Animal:
  has name: string
  has species: string
  has age: int
  has owner: Owner
  
concept Owner:
  has firstName: string
  has lastName: string
  has phone: string

concept Vaccination:
  has animal: one Animal
  has vaccineName: one string
  has givenOn: one date
  has validFor: one duration
  # add: has reminderLead: optional duration

# Add your booster appointment and vaccination facts here

Dr. Portbridge closed the appointment book (the real one, the one in the computer) and smiled. Every date now knew it was a date. But knowing the dates wasn’t the same as being warned in time. What she really wanted was for the system to speak up on its own: “Biscuit’s rabies protection expires next month.” For that, the clinic would have to start thinking.

Chapter 10: Automatic Alerts

It was 8 PM. Dr. Portbridge was still at the clinic, manually cross-referencing vaccination records with appointment dates to find overdue animals. “There has to be a way to automate this,” she muttered. She needed the system to reason, to look at data and draw conclusions.

The problem

So far, our ontology describes things but doesn’t infer anything. If an animal hasn’t been vaccinated in over a year, a human has to notice. If an appointment is marked as an emergency but assigned to an intern, nobody catches it. We want the system to derive new facts from existing ones.

Rules

A rule defines an if-then inference: if certain patterns hold in the data, then new facts follow.

rule flag_unvaccinated:
  match:
    ?animal a Animal
    ?animal vaccinations 0
  then:
    ?animal a UnvaccinatedAnimal

Note: This is a simplified example. Real vaccine-overdue logic would compare the givenOn date and validFor duration from Chapter 9, date arithmetic. The important thing here is the pattern: match conditions, then assert conclusions.

Let’s unpack the syntax.

Variables

Variables start with ?. They bind to values during pattern matching:

• ?animal: binds to any Animal instance

Patterns

Each line in the match: block is a pattern:

Patterns are combined with implicit AND. All must hold simultaneously.

Assertions

Each line in the then: block is an assertion, a new fact to create:

A more practical example

Let’s flag emergency appointments that are assigned to interns:

concept UnsafeAssignment

rule flag_intern_emergency:
  match:
    ?appt a Appointment
    ?appt urgency Emergency
    ?appt animal [ treatedBy [ a Intern ] ]
  then:
    ?appt a UnsafeAssignment

This says: “If an appointment is an Emergency, and the treating vet is an Intern, flag it as an UnsafeAssignment.”

Inferring new relationships

Rules don’t just classify, they can create relationships:

rule assign_primary_vet:
  match:
    ?animal a Animal
    ?animal owner [ preferredVet ?vet ]
  then:
    ?animal treatedBy ?vet

“If an animal’s owner has a preferred vet, assign that vet to the animal.”

(This requires adding preferredVet to Owner, we’ll do that below.)

Weight-based alerts

Here’s a rule using numeric comparison:

concept OverweightAnimal

rule flag_overweight_dog:
  match:
    ?dog a Dog
    ?dog weight [ > 40.0 ]
  then:
    ?dog a OverweightAnimal

Worked example

Suppose the clinic records two dogs:

fact rex a Dog
  name "Rex"
  species Dog
  weight 45.0
  neutered true

fact buddy a Dog
  name "Buddy"
  species Dog
  weight 22.0
  neutered true

When the rules run, the reasoner walks every Dog, checks the weight constraint, and derives one new fact:

rex   a OverweightAnimal      # 45.0 > 40.0  → flagged
# buddy is left untouched     # 22.0 > 40.0  → does not match

The derived rex a OverweightAnimal triple is added to the graph alongside the data you wrote. Nothing in the original facts changes. A rule only ever adds facts.

Classifying by an exact value

Comparisons aren’t the only test. A pattern can match an attribute against a literal value directly (a boolean, an enum member, a string, a date, or a date-time):

concept NeedsNeutering

rule flag_unneutered_dog:
  match:
    ?dog a Dog
    ?dog neutered false
  then:
    ?dog a NeedsNeutering

“Any dog whose neutered flag is false is tagged NeedsNeutering.”

Where rules run

These rules aren’t just documentation. When a Dolfin package is deployed in Agrafe, its rules are compiled and handed to the reasoner (retox). Every time data is written, the reasoner forward-chains the rules to a fixpoint, and the derived triples (rex a OverweightAnimal, …) become queryable through the deployment’s SPARQL API right next to the data you wrote.

Not available yet: aggregators. Rules match and compare individual values. They cannot yet count, sum, or average over a collection (e.g. “an animal with zero vaccinations” or “an owner with more than 5 animals” are aggregations and are not supported in rules today). Stick to attribute matches, comparisons, nested patterns, and relationships, which run end-to-end now.

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional string
  has preferredVet: optional Veterinarian

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

concept Dentist:
  sub Veterinarian
  has dentalCertification: one string

concept Intern:
  sub Veterinarian
  has university: one string
  has year: one int

concept Vaccination:
  has vaccineName: one string
  has dateAdministered: one string
  has batchNumber: optional string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

concept Dog:
  sub Animal
  has breed: optional string
  has neutered: one boolean

concept Cat:
  sub Animal
  has indoor: one boolean

concept Bird:
  sub Animal
  has wingspan: optional float
  has canFly: one boolean

concept Appointment:
  has animal: one Animal
  has scheduledFor: one date_time
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatments: string
  has notes: optional string

property treatedBy: Animal -> Veterinarian

# Derived concepts (created by rules)
concept UnvaccinatedAnimal
concept UnsafeAssignment
concept OverweightAnimal

# Rules
rule flag_unvaccinated:
  match:
    ?animal a Animal
    ?animal vaccinations 0
  then:
    ?animal a UnvaccinatedAnimal

rule flag_intern_emergency:
  match:
    ?appt a Appointment
    ?appt urgency Emergency
    ?appt animal [ treatedBy [ a Intern ] ]
  then:
    ?appt a UnsafeAssignment

rule flag_overweight_dog:
  match:
    ?dog a Dog
    ?dog weight [ > 40.0 ]
  then:
    ?dog a OverweightAnimal

rule assign_primary_vet:
  match:
    ?animal a Animal
    ?animal owner [ preferredVet ?vet ]
  then:
    ?animal treatedBy ?vet

Try it

Write a rule that classifies a Cat as a SeniorCat if its age is greater than or equal to 10:

concept SeniorCat

rule flag_senior_cat:
  match:
    # your patterns here
  then:
    # your assertion here

The alerts were a revelation. The system caught an intern assigned to an emergency before it became a problem. It flagged three overweight dogs whose owners hadn’t noticed the gradual change. But when Dr. Portbridge looked closely at that last rule, weight [ > 40.0 ], a doubt crept in. Forty what? A number with no unit was a number she couldn’t trust, and one threshold couldn’t possibly fit a parakeet and a mastiff alike. Before she added any more rules, the weights themselves needed to mean something.

Chapter 11: A Matter of Weight

The overweight-dog alert had been firing for a week, and Dr. Portbridge was starting to distrust it. It flagged Rex, a 45-kilo Labrador, fair enough. But it had also flagged nothing at all for a visiting Great Dane that clearly needed a diet, and it had thrown an alarm for a Chihuahua whose owner recorded its weight in grams. She looked at the rule again: weight [ > 40.0 ]. Forty. Forty what? And why would one number fit a parrot and a mastiff? The rule wasn’t wrong so much as it didn’t know what it was talking about.

The problem with a bare number

In Chapter 10 we wrote our first numeric comparison:

rule flag_overweight_dog:
  match:
    ?dog a Dog
    ?dog weight [ > 40.0 ]
  then:
    ?dog a OverweightAnimal

That 40.0 is a bare float, and a bare float carries no meaning. Is it forty kilograms? Forty pounds? Whoever writes a fact has to remember the convention and stick to it, and the moment one owner records weight 45.0 meaning 45 kg while another records weight 20.0 meaning 20 lb, the numbers lie to us. It is the same trouble string dates gave us in Chapter 9: a value the machine can store but cannot understand.

What we actually mean is a physical quantity: a number and a unit, together, as one indivisible thing.

Quantities

Dolfin writes a quantity as a smart literal, the same shape as the temporal values from Chapter 9, a keyword and human-friendly notation in parentheses:

quantity(45 kg)      # forty-five kilograms
quantity(4500 g)     # four and a half kilograms, written in grams
quantity(90 lb)      # ninety pounds
quantity(55 g)       # a small parakeet

The unit lives inside the value. Nothing is left to convention. And because Dolfin understands the units, it can do the one thing a bare number never could: compare measurements written in different units. Ninety pounds and forty kilograms are no longer two unrelated numbers, Dolfin knows that 90 lb is about 40.8 kg, and can tell you which is heavier.

Quantities are not just for weight. quantity(42 km/h), quantity(9.81 m/s^2), quantity(10 N/m^2) all work, Dolfin has a whole SI unit system built in. The Units & Quantities reference covers compound units, prefixes, arithmetic, and as conversions. Here we only need weight.

Weighing the patients properly

The Animal concept already has a weight attribute. We leave its declared type as float, a quantity’s real type is its unit, which the value carries, so the attribute only has to say “a number”:

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float   # values are quantities: quantity(45 kg)
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

float accepts any quantity, quantity(45 kg) or quantity(3 s) alike, nothing here checks that a weight is actually a mass. If you want that checked, the Units & Quantities reference covers dimension-typed ranges (has weight: unit.Mass). This tutorial keeps float to focus on quantities themselves first.

Now the facts record real measurements, and each animal can use whatever unit its chart was written in. Here are this week’s patients:

fact rex a Dog
  name "Rex"
  species Dog
  weight quantity(45 kg)
  neutered true

fact bella a Dog
  name "Bella"
  species Dog
  weight quantity(90 lb)     # ≈ 40.8 kg
  neutered true

fact buddy a Dog
  name "Buddy"
  species Dog
  weight quantity(22 kg)
  neutered true

fact mittens a Cat
  name "Mittens"
  species Cat
  weight quantity(7 kg)
  indoor true

A threshold that knows its units

Now we rewrite the alert so the threshold is a quantity too:

rule flag_overweight_dog:
  match:
    ?dog a Dog
    ?dog weight [ > quantity(40 kg) ]
  then:
    ?dog a OverweightAnimal

When the reasoner runs, it does not compare the written numbers, it compares the underlying physical magnitudes:

rex    a OverweightAnimal    # 45 kg      > 40 kg   → flagged
bella  a OverweightAnimal    # 90 lb ≈ 40.8 kg > 40 kg → flagged
# buddy is left untouched    # 22 kg      > 40 kg   → does not match

Bella is the point of the whole chapter. Her weight was recorded in pounds, the threshold is in kilograms, and the rule still fires correctly, because Dolfin converts both to a common footing before comparing. The bare-number version could never have caught her.

Both sides must be quantities. The unit-aware comparison only runs when the stored value and the threshold are quantity(...). Comparing a quantity(...) weight against a bare 40.0, or vice versa, falls back to a plain numeric test with no unit reasoning, exactly the ambiguity we set out to remove. So once a value is a quantity, keep the threshold a quantity as well.

One threshold per species

Forty kilograms is a sensible line for a dog and absurd for a cat. Because the threshold is written right into each rule, every species gets its own:

concept OverweightCat

rule flag_overweight_cat:
  match:
    ?cat a Cat
    ?cat weight [ > quantity(6 kg) ]
  then:
    ?cat a OverweightCat

Mittens, the cat in our patient list above at 7 kg, is a chunky cat and gets flagged. A parakeet recorded as quantity(55 g) would sit far below any of these lines, and a threshold written in grams (quantity(60 g)) would compare against it perfectly, grams, kilograms, and pounds are all the same dimension (mass), so they are all comparable.

Comparing unlike things

What if a threshold and a value are not the same kind of measurement? Suppose someone fat-fingers a length where a weight belongs:

?dog weight [ > quantity(40 m) ]     # metres — a length, not a weight

Dolfin does not crash and does not silently coerce. Mass and length are different dimensions, so the comparison simply fails and the animal is never flagged. A comparison you cannot make is treated as one that does not hold, the same rule Dolfin uses everywhere: a condition it cannot satisfy does not match.

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional string
  has preferredVet: optional Veterinarian

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

concept Dentist:
  sub Veterinarian
  has dentalCertification: one string

concept Intern:
  sub Veterinarian
  has university: one string
  has year: one int

concept Vaccination:
  has vaccineName: one string
  has dateAdministered: one string
  has batchNumber: optional string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

concept Dog:
  sub Animal
  has breed: optional string
  has neutered: one boolean

concept Cat:
  sub Animal
  has indoor: one boolean

concept Bird:
  sub Animal
  has wingspan: optional float
  has canFly: one boolean

concept Appointment:
  has animal: one Animal
  has scheduledFor: one date_time
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatments: string
  has notes: optional string

property treatedBy: Animal -> Veterinarian

# Flag concepts and inference rules (Chapter 10)
concept UnvaccinatedAnimal
concept UnsafeAssignment
concept OverweightAnimal

rule flag_unvaccinated:
  match:
    ?animal a Animal
    ?animal vaccinations 0
  then:
    ?animal a UnvaccinatedAnimal

rule flag_intern_emergency:
  match:
    ?appt a Appointment
    ?appt urgency Emergency
    ?appt animal [ treatedBy [ a Intern ] ]
  then:
    ?appt a UnsafeAssignment

rule assign_primary_vet:
  match:
    ?animal a Animal
    ?animal owner [ preferred_vet ?vet ]
  then:
    ?animal treatedBy ?vet

# Weight thresholds, now unit-aware (this chapter)
concept OverweightCat

rule flag_overweight_dog:
  match:
    ?dog a Dog
    ?dog weight [ > quantity(40 kg) ]
  then:
    ?dog a OverweightAnimal

rule flag_overweight_cat:
  match:
    ?cat a Cat
    ?cat weight [ > quantity(6 kg) ]
  then:
    ?cat a OverweightCat

Try it

Birds are recorded in grams. Write a rule that flags a Bird heavier than 500 grams as a HeavyBird, then add a fact for a parrot that weighs quantity(1.2 kg) and check that it trips the threshold even though its weight is written in kilograms and the threshold in grams:

concept HeavyBird

rule flag_heavy_bird:
  match:
    ?bird a Bird
    # your quantity comparison here
  then:
    # your assertion here

Dr. Portbridge re-ran the alerts. Rex and Bella both surfaced, the Great Dane among them this time, and the Chihuahua-in-grams was quietly left alone. Every weight now meant exactly what it said. But catching an overweight dog after the fact was one thing. She wanted the system to refuse bad data outright, a surgery booked with an intern, a completed appointment with no diagnosis, before it was ever written down. She needed guard rails.

Chapter 12: Guard Rails

An owner brought in a hamster for dental surgery. The system accepted the appointment without complaint, it didn’t know that dental procedures require a Dentist, or that hamsters aren’t in the Species enum (they’d have to be Other). The rules we’ve written so far could flag problems after the fact, but Dr. Portbridge wanted to prevent mistakes from being recorded in the first place.

The problem

Rules infer new facts, they add information. But they don’t prevent bad data. We need a way to express expectations: “Every X must satisfy Y”, “No X should ever have Z.”

Quantifiers in rules

Dolfin provides quantifiers that express conditions over collections:

Ensuring surgical appointments have surgeons

concept InvalidSurgery

rule validate_surgery_staff:
  match:
    ?appt a Appointment
    ?appt reason "surgery"
    ?appt animal ?animal
    none ?vet:
      ?animal treatedBy ?vet
      ?vet a Surgeon
  then:
    ?appt a InvalidSurgery

This reads: “If an appointment is for surgery but no Surgeon is treating the animal, flag it as invalid.”

The none ?vet: quantifier introduces a fresh variable and a nested block; it succeeds when no binding of ?vet satisfies the sub-patterns, here, no vet who both treats the animal and is a Surgeon.

Minimum vaccination rules

Every dog should have at least one vaccination (in the real world, rabies is required by law in most places):

concept UnderVaccinatedDog

rule check_dog_vaccines:
  match:
    ?dog a Dog
    ?dog vaccinations 0
  then:
    ?dog a UnderVaccinatedDog

Comparison operators

You’ve already seen > and = in rules. Here’s the complete set:

Combining conditions

Rule patterns are combined with implicit AND. All conditions must hold for the rule to fire:

concept AtRiskAnimal

rule flag_at_risk:
  match:
    ?animal a Animal
    ?animal age [ > 15 ]
    ?animal weight [ < quantity(2 kg) ]
    ?animal vaccinations 0
  then:
    ?animal a AtRiskAnimal

“An animal older than 15, weighing less than 2 kg, with no vaccinations, is at risk.”

Validation concepts as a pattern

Notice the design pattern emerging: we create empty concepts (InvalidSurgery, UnderVaccinatedDog, AtRiskAnimal) that exist only to be assigned by rules. They act as tags or flags. Downstream systems can query for all instances of InvalidSurgery and take action.

This is a powerful idiom:

1. Define an empty concept that represents a condition
2. Write a rule that classifies instances into that concept
3. Query or display instances of the condition

Worked example: from data to flag to query

Take a single rule built only from conditions that run today:

concept SeniorCat

rule flag_senior_cat:
  match:
    ?cat a Cat
    ?cat age [ >= 10 ]
  then:
    ?cat a SeniorCat

Given this patient:

fact mittens a Cat
  name "Mittens"
  species Cat
  age 12
  indoor true

the reasoner derives mittens a SeniorCat. Because the flag is a normal concept, a downstream system finds every senior cat with an ordinary query:

SELECT ?cat WHERE { ?cat a clinic:SeniorCat }

The result includes mittens even though no one ever wrote mittens a SeniorCat by hand. The rule produced it, and it sits in the graph next to the asserted data.

Reminder: no aggregators yet. Guard rails phrased as counts (e.g. “a dog with zero vaccinations”, “an appointment with more than 3 cancellations”) are aggregations and don’t run as rules yet. Express conditions over a single value (comparisons, exact matches, nested patterns) until aggregator support lands.

The story so far

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "0.1.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# clinic.dlf
concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional string
  has preferredVet: optional Veterinarian

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

concept Dentist:
  sub Veterinarian
  has dentalCertification: one string

concept Intern:
  sub Veterinarian
  has university: one string
  has year: one int

concept Vaccination:
  has vaccineName: one string
  has dateAdministered: one string
  has batchNumber: optional string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

concept Dog:
  sub Animal
  has breed: optional string
  has neutered: one boolean

concept Cat:
  sub Animal
  has indoor: one boolean

concept Bird:
  sub Animal
  has wingspan: optional float
  has canFly: one boolean

concept Appointment:
  has animal: one Animal
  has scheduledFor: one date_time
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatments: string
  has notes: optional string

property treatedBy: Animal -> Veterinarian

# Flag concepts and inference rules (Chapter 10)
concept UnvaccinatedAnimal
concept UnsafeAssignment
concept OverweightAnimal

rule flag_unvaccinated:
  match:
    ?animal a Animal
    ?animal vaccinations 0
  then:
    ?animal a UnvaccinatedAnimal

rule flag_intern_emergency:
  match:
    ?appt a Appointment
    ?appt urgency Emergency
    ?appt animal [ treatedBy [ a Intern ] ]
  then:
    ?appt a UnsafeAssignment

rule assign_primary_vet:
  match:
    ?animal a Animal
    ?animal owner [ preferred_vet ?vet ]
  then:
    ?animal treatedBy ?vet

# Unit-aware weight thresholds (Chapter 11)
concept OverweightCat

rule flag_overweight_dog:
  match:
    ?dog a Dog
    ?dog weight [ > quantity(40 kg) ]
  then:
    ?dog a OverweightAnimal

rule flag_overweight_cat:
  match:
    ?cat a Cat
    ?cat weight [ > quantity(6 kg) ]
  then:
    ?cat a OverweightCat

# Guard rails: validation concepts and rules (this chapter)
concept SeniorCat
concept InvalidSurgery
concept UnderVaccinatedDog
concept AtRiskAnimal

rule flag_senior_cat:
  match:
    ?cat a Cat
    ?cat age [ >= 10 ]
  then:
    ?cat a SeniorCat

rule validate_surgery_staff:
  match:
    ?appt a Appointment
    ?appt reason "surgery"
    ?appt animal ?animal
    none ?vet:
      ?animal treatedBy ?vet
      ?vet a Surgeon
  then:
    ?appt a InvalidSurgery

rule check_dog_vaccines:
  match:
    ?dog a Dog
    ?dog vaccinations 0
  then:
    ?dog a UnderVaccinatedDog

rule flag_at_risk:
  match:
    ?animal a Animal
    ?animal age [ > 15 ]
    ?animal weight [ < quantity(2 kg) ]
    ?animal vaccinations 0
  then:
    ?animal a AtRiskAnimal

Try it

Write a validation rule that flags an Appointment as MissingDiagnosis when its status is Completed but diagnosis is absent (equals empty string ""):

concept MissingDiagnosis

rule check_completed_diagnosis:
  match:
    # your patterns here
  then:
    # your assertion here

The guard rails caught two problems on day one: a surgery booked with an intern and a completed appointment with no recorded diagnosis. Dr. Portbridge felt like the system was finally earning its keep.

Then the regional veterinary board called. They needed the clinic to export its data in a format compatible with the national animal health registry, which used standard OWL/RDF vocabularies. Dr. Portbridge’s concept names were fine for her clinic, but the outside world expected specific IRIs. She needed a bridge.

Chapter 13: Talking to the Outside World

*The email from the Regional Veterinary Board was blunt:

Please submit your animal health records using the National Animal Health Ontology (NAHO) vocabulary. All concepts must use IRIs from http://naho.gov/ontology/. All species must reference the FAO species classification at http://fao.org/species/.

Dr. Portbridge looked at her Dolfin file. Her concepts were called Animal and Dog. The board expected http://naho.gov/ontology/Animal and http://fao.org/species/CanineDomestic. She needed a way to map her clean, readable names to the bureaucratic world of IRIs.

The problem

Dolfin ontologies live in a clean, human-readable world. The semantic web lives in a world of IRIs (Internationalized Resource Identifiers), long URLs that uniquely identify every concept, property, and individual. To interoperate, we need to connect the two.

Prefixes

A prefix declares a short alias for an IRI namespace:

prefix <http://naho.gov/ontology/> as naho
prefix <http://fao.org/species/> as fao

A prefix is only an alias for qualified references, naho.Animal expands to http://naho.gov/ontology/Animal. Declaring a prefix does not move your own concepts into that namespace. This:

prefix <http://naho.gov/ontology/> as naho

concept Animal:
  has name: one string

still defines Animal under your package’s own namespace. The naho prefix sits unused. To bind one of your concepts to an external IRI you must say so explicitly with @iri_name (see below).

Using prefixed references

Prefixes let you reference concepts from other ontologies:

prefix <http://schema.org/> as schema

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional schema.PostalAddress

schema.PostalAddress refers to http://schema.org/PostalAddress, Schema.org’s definition of a postal address. You’re linking your clinic ontology to a globally recognized vocabulary.

The @iri_name annotation

This is how you actually bind a concept to an external IRI. The @iri_name annotation sits inside the concept body and takes the complete IRI in angle brackets. That IRI is used verbatim, it is not appended to your package namespace:

concept DomesticDog:
  @iri_name <http://fao.org/species/CanineDomestic>
  sub Animal
  has breed: optional string
  has neutered: one boolean

Here the local name DomesticDog stays clean and readable in your code, but the concept compiles to http://fao.org/species/CanineDomestic. Exactly the IRI the external system expects. This is what the board’s request required: local names mapped to bureaucratic IRIs. The annotation takes a full IRI in angle brackets only. A prefixed qualified name is not accepted here.

Multiple prefixes

A real-world ontology often bridges multiple external vocabularies:

prefix <http://naho.gov/ontology/> as naho
prefix <http://fao.org/species/> as fao
prefix <http://schema.org/> as schema
prefix <http://purl.org/dc/elements/1.1/> as dc

Each prefix is independent. You can use as many as needed.

The complete clinic

package.dlf holds only the package declaration:

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "1.0.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

The ontology goes in a second file, clinic.dlf. If it used prefixes, the prefix lines would sit at the top of that file, never in package.dlf. This listing declares none: @iri_name takes a full IRI, so DomesticDog does not need one.

# clinic.dlf
concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional string
  has preferredVet: optional Veterinarian

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

concept Dentist:
  sub Veterinarian
  has dentalCertification: one string

concept Intern:
  sub Veterinarian
  has university: one string
  has year: one int

concept Vaccination:
  has vaccineName: one string
  has dateAdministered: one string
  has batchNumber: optional string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

concept Dog:
  sub Animal
  has breed: optional string
  has neutered: one boolean

concept Cat:
  sub Animal
  has indoor: one boolean

concept Bird:
  sub Animal
  has wingspan: optional float
  has canFly: one boolean

concept Appointment:
  has animal: one Animal
  has scheduledFor: one date_time
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatments: string
  has notes: optional string

property treatedBy: Animal -> Veterinarian

# Binding to the outside world (this chapter)
concept DomesticDog:
  @iri_name <http://fao.org/species/CanineDomestic>
  sub Dog

# Flag concepts and inference rules (Chapter 10)
concept UnvaccinatedAnimal
concept UnsafeAssignment
concept OverweightAnimal

rule flag_unvaccinated:
  match:
    ?animal a Animal
    ?animal vaccinations 0
  then:
    ?animal a UnvaccinatedAnimal

rule flag_intern_emergency:
  match:
    ?appt a Appointment
    ?appt urgency Emergency
    ?appt animal [ treatedBy [ a Intern ] ]
  then:
    ?appt a UnsafeAssignment

rule assign_primary_vet:
  match:
    ?animal a Animal
    ?animal owner [ preferred_vet ?vet ]
  then:
    ?animal treatedBy ?vet

# Unit-aware weight thresholds (Chapter 11)
concept OverweightCat

rule flag_overweight_dog:
  match:
    ?dog a Dog
    ?dog weight [ > quantity(40 kg) ]
  then:
    ?dog a OverweightAnimal

rule flag_overweight_cat:
  match:
    ?cat a Cat
    ?cat weight [ > quantity(6 kg) ]
  then:
    ?cat a OverweightCat

# Guard rails (Chapter 12)
concept SeniorCat
concept InvalidSurgery
concept UnderVaccinatedDog
concept AtRiskAnimal

rule flag_senior_cat:
  match:
    ?cat a Cat
    ?cat age [ >= 10 ]
  then:
    ?cat a SeniorCat

rule validate_surgery_staff:
  match:
    ?appt a Appointment
    ?appt reason "surgery"
    ?appt animal ?animal
    none ?vet:
      ?animal treatedBy ?vet
      ?vet a Surgeon
  then:
    ?appt a InvalidSurgery

rule check_dog_vaccines:
  match:
    ?dog a Dog
    ?dog vaccinations 0
  then:
    ?dog a UnderVaccinatedDog

rule flag_at_risk:
  match:
    ?animal a Animal
    ?animal age [ > 15 ]
    ?animal weight [ < quantity(2 kg) ]
    ?animal vaccinations 0
  then:
    ?animal a AtRiskAnimal

Try it

Add a prefix for Dublin Core (http://purl.org/dc/elements/1.1/) and FOAF (http://xmlns.com/foaf/0.1/):

prefix <http://naho.gov/ontology/> as naho

# Add Dublin Core and FOAF prefixes here

Dr. Portbridge submitted the data export. The board’s system accepted it without complaint, her concepts mapped cleanly to NAHO’s IRIs, and the species references aligned with FAO’s vocabulary. Her little clinic was speaking the same language as the national registry.

She leaned back in her chair and looked at the screen. What had started as a napkin sketch was now a complete data model: concepts with inheritance, cardinality constraints, enums for controlled vocabularies, rules for automated reasoning, constraints for validation, and prefixes for interoperability. Biscuit dozed at her feet. Pixel purred on the printer.

Chapter 14: Mapping a JSON API Dump

A week after the submission, the Regional Veterinary Board wrote back. This time there was no form to fill in, just an attachment: Venue.json, an export from their API listing every place where the next vaccination campaign would run. “Please link your records to these venues.”

Dr. Portbridge opened it. It was not a table. It was nested braces, lists inside objects inside lists. Typing each venue as a fact by hand was out of the question.

The problem

Facts (Chapter 8) name one instance at a time. Real data arrives in bulk, and more and more often it arrives as JSON: nested, with no obvious “row”. A mapping declares the shape of an instance once and lets the file supply the values. For JSON it needs two things a spreadsheet never asks for: what counts as one record, and where each value sits inside it.

The file

Here is the board’s export:

{
  "venue": [
    {
      "latitude": 50.901389,
      "longitude": 4.484444,
      "location": { "continent": "EU", "country": "BE", "city": "Brussels" }
    }
  ]
}

One venue, with a position and a nested location. We want two things out of it: a city, and the coordinates the city is linked to.

The whole mapping

prefix <http://example.com/ns#> as ex

mapping from <package://Venue.json> as JSONPath
  for each "$.venue[*]"
  map:
    "$.latitude" as ?lat
    "$.longitude" as ?long
    "$.location.continent" as ?continent
    "$.location.country" as ?country
    "$.location.city" as ?city
  to:
    fact <http://loc.example.com/city/{?city}> a ex:City
      ex:countryCode ?country
      ex:latlong <http://loc.example.com/latlong/{?lat},{?long}>
      ex:onContinent ?continent
    fact <http://loc.example.com/latlong/{?lat},{?long}> a ex:latlong
      ex:lat {?lat}
      ex:long {?long}

It reads top to bottom in four steps.

1. The source

mapping from <package://Venue.json> as JSONPath names the file, relative to the package root (the directory holding package.dlf), and picks the JSON reader. Values will be addressed with JSONPath strings, where $ is the root and .name steps into an object member.

2. for each: what is a row?

for each "$.venue[*]" says: every element of the venue array is one record. The mapping runs once per element. With three venues in the array, the to: block would run three times.

Leave the line out and the whole document is a single record.

3. map:: where the values are

Each line binds a path to a variable. The paths are relative to the current venue: inside map:, $ is the venue being processed, not the whole file. So "$.latitude" reads that venue’s latitude, and "$.location.city" steps into its nested location object.

JSON values bind as plain text. The number 50.901389 binds the text "50.901389", exactly as a spreadsheet cell would. To get a typed literal, add a cast in the template ({?lat} as float), the same casts a CSV mapping uses.

4. to:: what to build

The to: block is ordinary fact syntax with {?var} holes. There are two fact templates, and both run for every venue:

• the first builds a city, named after ?city, with its country, continent and a link to a coordinates node;
• the second builds that coordinates node, named after ?lat and ?long.

The link works because both templates build the same IRI, <http://loc.example.com/latlong/{?lat},{?long}>, from the same variables.

What comes out

Building the package expands the mapping before Turtle is generated, so the venue becomes two subjects, exactly as if they had been written by hand:

<http://loc.example.com/city/Brussels> rdf:type owl:NamedIndividual
  , ex:City
  ; rdfs:isDefinedBy <http://example.org/venues/venues>
  .
<http://loc.example.com/city/Brussels> ex:countryCode "BE" .
<http://loc.example.com/city/Brussels> ex:latlong <http://loc.example.com/latlong/50.901389,4.484444> .
<http://loc.example.com/city/Brussels> ex:onContinent "EU" .

<http://loc.example.com/latlong/50.901389,4.484444> rdf:type owl:NamedIndividual
  , ex:latlong
  ; rdfs:isDefinedBy <http://example.org/venues/venues>
  .
<http://loc.example.com/latlong/50.901389,4.484444> ex:lat "50.901389" .
<http://loc.example.com/latlong/50.901389,4.484444> ex:long "4.484444" .

Each subject is typed by its template (ex:City, ex:latlong) and carries its mapped properties: three for the city, two for the coordinates. The owl:NamedIndividual and rdfs:isDefinedBy lines are added to every fact, mapped or hand-written.

When a path does not match

Real exports are messy. Suppose a second venue had no location.city. Then "$.location.city" matches nothing in that venue, and ?city is empty, exactly like an empty spreadsheet cell. Since ?city builds the city’s subject IRI, there is no sensible subject to build, so that whole venue is skipped with a diagnostic, and the other venues are unaffected.

An empty value that only feeds an optional property just drops that one property. JSON null counts as empty too. The other cases:

• a path that hits an object or an array ("$.location") skips the venue: a whole subtree is never turned into a text literal;
• a path that hits several values binds the first one and warns; to get one record per value, move that path into for each instead.

The syntax reference lists every rule.

The board’s venues landed in the system as cities and coordinates, linked to each other, without a single line typed by hand. When the board published next month’s export, Dr. Portbridge replaced the file and rebuilt. The mapping did not change.

Chapter 15: Mapping an XML Feed

The vaccination campaign needed transport. The regional bus company was happy to help, and sent its timetable feed: Transport.xml. “It’s what our ticket machines read,” the dispatcher said. “It’s XML, of course.”

Dr. Portbridge had just learned to map the board’s JSON. The tags looked different, but the question was the same one: where does one record start, and where does each value sit inside it?

The problem

Chapter 14 mapped a JSON document by pointing at its values with JSONPath. XML works the same way, with a different path language: XPath. A mapping still needs to know what counts as one record and where each value sits inside it; only the way of writing those paths changes.

The file

Here is the bus company’s feed:

<transport>
  <bus id="25">
    <route>
      <stop id="645">Central</stop>
    </route>
  </bus>
  <bus id="26">
    <route>
      <stop id="700">Harbour</stop>
    </route>
  </bus>
</transport>

Two buses, each with a route and one stop. A stop carries its number in an id attribute and its name as text. We want a bus and a stop out of each bus element, linked together.

The whole mapping

prefix <http://vocab.org/transit/terms/> as transit
prefix <http://www.w3.org/2000/01/rdf-schema#> as rdfs

mapping from <package://Transport.xml> as XPath
  for each "/transport/bus"
  map:
    "@id" as ?id
    "route/stop/@id" as ?stop_id
    "route/stop" as ?stop_label
  to:
    fact <http://trans.example.com/bus/{?id}> a transit:Bus
      transit:stop <http://trans.example.com/stop/{?stop_id}>
    fact <http://trans.example.com/stop/{?stop_id}> a transit:Stop
      transit:code {?stop_id as int}
      rdfs:label {?stop_label}

It reads top to bottom in the same four steps as the JSON mapping.

1. The source

mapping from <package://Transport.xml> as XPath names the file, relative to the package root, and picks the XML reader. Values will be addressed with XPath strings: / steps into a child element, @ reads an attribute.

2. for each: what is a row?

for each "/transport/bus" says: every bus element under the root transport element is one record. The feed has two, so the to: block runs twice.

Leave the line out and the whole document is a single record, exactly as with JSON.

3. map:: where the values are

Each line binds a path to a variable. The paths are relative to the current bus:

• "@id" reads the bus’s own id attribute;
• "route/stop/@id" steps into its route, then its stop, and reads the stop’s id;
• "route/stop" stops at the stop element itself. An element that holds only text binds that text, so this gives the stop’s name.

The same stop element therefore gives two values: its number and its name.

An XPath string literal uses single quotes, as in "stop[@kind='express']", so that it does not end the Dolfin string around it. Square brackets pick among several matches: "route/stop[2]" is the second stop of the route.

4. to:: what to build

There are two fact templates, and both run for every bus:

• the first builds the bus, named after ?id, with a link to its stop;
• the second builds the stop, named after ?stop_id, with a code and a label.

The link works because both templates build the same IRI, <http://trans.example.com/stop/{?stop_id}>, from the same variable.

XML values bind as plain text, like JSON values and CSV cells. The {?stop_id as int} cast, written inside the braces, turns the text "645" into an integer literal.

What comes out

Building the package expands the mapping before Turtle is generated, so each bus becomes two subjects:

<http://trans.example.com/bus/25> rdf:type owl:NamedIndividual
  , transit:Bus
  ; rdfs:isDefinedBy <http://example.org/transport/transport>
  .
<http://trans.example.com/bus/25> transit:stop <http://trans.example.com/stop/645> .

<http://trans.example.com/stop/645> rdf:type owl:NamedIndividual
  , transit:Stop
  ; rdfs:isDefinedBy <http://example.org/transport/transport>
  .
<http://trans.example.com/stop/645> transit:code "645"^^xsd:integer .
<http://trans.example.com/stop/645> rdfs:label "Central" .

<http://trans.example.com/bus/26> rdf:type owl:NamedIndividual
  , transit:Bus
  ; rdfs:isDefinedBy <http://example.org/transport/transport>
  .
<http://trans.example.com/bus/26> transit:stop <http://trans.example.com/stop/700> .

<http://trans.example.com/stop/700> rdf:type owl:NamedIndividual
  , transit:Stop
  ; rdfs:isDefinedBy <http://example.org/transport/transport>
  .
<http://trans.example.com/stop/700> transit:code "700"^^xsd:integer .
<http://trans.example.com/stop/700> rdfs:label "Harbour" .

Each subject is typed by its template (transit:Bus, transit:Stop) and carries its mapped properties: one for the bus, two for its stop.

When a path does not match

The rules are the ones you already know from JSON:

• a path that matches nothing gives an empty value, and if that value builds the subject IRI the whole bus is skipped with a diagnostic;
• a path that hits an element with child elements ("route") skips the bus: a whole subtree is never turned into a text literal;
• a path that hits several nodes binds the first one and warns. A route with two stops would do that with "route/stop/@id"; to get one record per stop, iterate over the stops instead with for each "/transport/bus/route/stop".

Real feeds often put their elements in an XML namespace. Declare it with an ordinary prefix line and use that prefix in the path ("/t:transport/t:bus"). The reader only understands a fixed subset of XPath, and anything outside it is an error rather than a silent empty match. The syntax reference lists every rule, including namespaces and the supported XPath subset.

The two buses, their stops and the links between them were in the system in seconds. When the company added a third line the following week, the dispatcher sent a new feed. Dr. Portbridge replaced the file and rebuilt. The mapping did not change.

Chapter 16: Mapping a Spreadsheet

The bus company’s feed covered the routes. The stops themselves lived somewhere else: in a spreadsheet the dispatcher kept on the office computer, workbook.xlsx. “Everything is in the Stops tab,” she said. “Don’t mind the title at the top.”

Dr. Portbridge opened it. A banner, an empty line, then a table: one row per stop. It looked a lot like the CSV files from earlier, only with more than one tab, and with real dates in it.

The problem

A spreadsheet is a CSV file with extras: several sheets in one file, a table that does not always start on the first row, and cells that know they hold a number, a date or a formula. The mapping still reads one row at a time and still finds each value by its column name. It only needs to be told which sheet, and which row holds the column names.

The file

The Stops sheet, as the spreadsheet application shows it:

Column opened is formatted as a date, ok holds booleans, n the number of platforms, and f a formula: a stop code computed from the id. The workbook has a second sheet, Info, before this one.

The whole mapping

prefix <http://vocab.org/transit/terms/> as transit

mapping from <package://workbook.xlsx> as XLSX
  sheet "Stops"
  header row 3
  map:
    id     as ?id
    opened as ?opened
    ok     as ?ok
    n      as ?n
  to:
    fact <http://airport.example.com/stop/{?id}> a transit:Stop
      transit:opened {?opened} as date
      transit:open {?ok} as boolean
      transit:platforms {?n} as int

mapping from <package://workbook.xlsx> as XLSX
  sheet "Stops"
  header row 3
  map:
    id as ?id
    f  as ?code
  to:
    fact <http://airport.example.com/code/{?id}> a transit:Code
      transit:value {?code}

There are two mappings over the same sheet: the first builds the stops, the second their codes.

1. The source

mapping from <package://workbook.xlsx> as XLSX names the file and picks the Excel reader. For a LibreOffice .ods file, write as ODS. The selector decides the reader, not the file name.

2. sheet and header row

sheet "Stops" picks the tab by its exact name. Without it the mapping would read the first tab, Info.

header row 3 says the column names are on row 3, numbered as the application numbers its rows. Without it the first non-empty row would be the header, and that is the banner: the mapping would then fail on mapping references unknown column 'id'. Everything above the header is ignored, and the empty row 5 is skipped.

3. map: and to:

From here on it is a CSV mapping: column names on the left of as, one fact template per row, and the usual casts.

What comes out

<http://airport.example.com/stop/6523> rdf:type owl:NamedIndividual
  , transit:Stop
  ; rdfs:isDefinedBy <http://example.org/stops/stops>
  .
<http://airport.example.com/stop/6523> transit:opened "2024-01-01"^^xsd:date .
<http://airport.example.com/stop/6523> transit:open "true"^^xsd:boolean .
<http://airport.example.com/stop/6523> transit:platforms "25"^^xsd:integer .

<http://airport.example.com/code/6523> rdf:type owl:NamedIndividual
  , transit:Code
  ; rdfs:isDefinedBy <http://example.org/stops/stops>
  .
<http://airport.example.com/code/6523> transit:value "13046" .

Look at the values:

• Dates. The date cell binds 2024-01-01, the way it is displayed, so as date gives an xsd:date. Inside the file it is the number 45292; the reader converts any cell formatted as a date.
• Numbers. A spreadsheet stores every number as a decimal, so the 25 in column n is really 25.0. It binds "25", and as int accepts it.
• Booleans. TRUE binds "true", which as boolean reads.
• Formulas. =A4*2 binds its saved result, 13046. Nothing is recalculated.

Without a cast, a cell still gives a plain string, like a CSV cell: the code is "13046", not a number.

Why row 6 is missing

Stop 6524 is in neither mapping, for two different reasons:

• its opened cell holds a date and a time. It binds 2024-01-01T12:00:00, and as date refuses it rather than drop the time without telling you: row 2: cannot cast '2024-01-01T12:00:00' to date for property transit:opened.
• its f cell is an error, #DIV/0!. A row with an error in a bound column is skipped (row 2: cell error #DIV/0! for binding ?code), even when the property is optional: an error is a broken sheet, not a missing value.

row 2 is the second data row, not the application’s row 6. These are warnings: the build goes on with the rows that worked.

The same mappings over the workbook saved as workbook.ods (as ODS) give the same triples, plus a code for 6524 with no value: OpenDocument has no error cells, and LibreOffice saves =1/0 as an empty string.

Spreadsheets are read by radeau build only. The playground and Agrafe cannot open them and report unsupported mapping format 'XLSX'. Word-processor files (.odt, .docx) are not spreadsheets and are not read at all. The syntax reference has every rule.

The dispatcher fixed the formula and changed the time to midnight. Dr. Portbridge rebuilt: two stops, two codes. When the spreadsheet grew a new tab for the night buses, it got a second sheet line, in a second mapping.

Chapter 17: Asking Questions

Friday afternoon. The board wanted numbers: how many patients of each species, which vets had no one on their list, which dog owners could be reached by email. The data was all there, typed, checked and linked. Dr. Portbridge just needed a way to ask.

The problem

Facts and mappings fill the graph. Rules add to it. But nothing so far reads it back. In Chapter 12 a downstream system found the senior cats with a SPARQL query, written by hand, in another language. Dolfin has its own way to ask: the query.

A first query

query all_cats:
  ?cat a Cat
    name ?name
    age ?age

This reads like the shape it looks for: a cat, with a name and an age. Every cat that has both gives one row, with columns cat, name and age.

A query is translated to SPARQL. This one becomes:

SELECT ?cat ?name ?age
WHERE {
  ?cat a Cat .
  ?cat name ?name .
  ?cat age ?age .
}

The indented lines all talk about the subject above them, so ?cat is written once instead of on every line. Patterns are combined with implicit AND, as in the match: block of a rule.

Choosing the columns

The board wants the five oldest cats past ten, oldest first. A constraint filters, and a return block shapes the result:

query senior_cats:
  ?cat a Cat
    name ?name
    age [?age >= 10]
  return
    ?name
    ?age
      order desc
    limit 5

• age [?age >= 10] binds the age to ?age and keeps only ages of 10 and more.
• return lists the columns. ?cat is not in it, so it is not returned.
• order desc under a column sorts on it; limit 5 keeps five rows.

Without a return block, every variable is returned. A variable that starts with ?_ is silent: it is used for matching but never returned.

Following links

Owners are not animals: they hang off the owner property. A [ … ] block opens a nested subject, without naming it:

query owners_of_dogs:
  a Dog
    name ?dogName
    owner [
      lastName ?ownerName
      optional email ?email
    ]

The dog has no variable either: a Dog alone is enough when nothing else refers to it. email is optional in the schema, so the line is marked optional: an owner without an email still gives a row, with an empty email column. Without the keyword, those owners would vanish from the result.

Links can be followed backwards. treatedBy goes from an animal to a vet; to start from the vet, read it with is … of:

?vet is treatedBy of ?animal

Something, or nothing

Which vets have no patients? This is a question about something that is not there. A none: block keeps a row only if its content never matches:

query vets_without_patients:
  ?vet a Veterinarian
    name ?name
  none:
    ?vet is treatedBy of ?_animal

some: is the opposite: the row stays if the content matches at least once. Inside both, ?vet is the same vet as outside; ?_animal is local.

And when either of two conditions will do, either … or says so:

query heavy_or_old:
  ?pet a Animal
    name ?name
    either weight [ > 30.0 ]
    or age [ > 12 ]

Counting

How many patients of each species? A group by block groups the rows and computes one value per group:

query animals_per_species:
  ?animal a Animal
    species ?species
  group by ?species
    count ?animal as ?total
    ?total >= 2
  return
    ?species
    ?total
      order desc

count ?animal as ?total counts the animals in each species. The line ?total >= 2 drops species with a single patient. sum, average, min and max work the same way as count.

To count per animal while keeping one row per animal, put the count in the body, with what it counts indented below it:

query vaccine_count:
  ?animal a Animal
    name ?name
  count ?shot as ?shots
    ?animal vaccinations ?shot

?animal appears above the count, so each animal gets its own ?shots.

Building on other queries

A query can use another one. Write the question once, reuse it:

query cats_with_vet:
  ?cat a Cat
    treatedBy ?vet
  return
    ?cat
    ?vet

query cat_vet_names:
  cats_with_vet as [
    cat ?c
    vet ?v
  ]
  ?c name ?catName
  ?v name ?vetName

cats_with_vet as [ … ] runs the first query and binds its cat and vet columns to ?c and ?v. A query with a single column binds in one line: some_query as ?x.

Summary

The syntax reference has every form, and the SPARQL each one becomes.

The board meeting lasted twenty minutes. Dr. Portbridge answered every question by running a query she had written that morning. When the treasurer asked for one more number, she wrote a new one on the spot, four lines long.

Epilogue: The Full Picture

Three months later, Happy Paws had treated 847 animals. The system had caught 23 unsafe assignments, flagged 156 overdue vaccinations, and identified 4 at-risk animals that might have been missed. Dr. Reyes had performed 31 surgeries without a single scheduling error. And Pixel, now a healthy six-month-old, had been adopted by the receptionist.

What you’ve learned

Over seventeen chapters, you’ve built a complete ontology from scratch. Here’s what each chapter introduced:

The complete ontology

Here is the full Happy Paws ontology, everything from every chapter, in two files: the package manifest and the ontology itself.

# package.dlf
package <http://happypaws.com/clinic>:
  dolfin_version "1"
  version "1.0.0"
  author "Dr. Helen Portbridge"
  description "The Happy Paws veterinary clinic data model"

# ============================================================
#  clinic.dlf: Happy Paws Veterinary Clinic, Complete Ontology
# ============================================================

# ------------------------------------------------------------
# Schema: concepts, enums, and properties (Chapters 4-9)
# ------------------------------------------------------------

concept Species:
  one of:
    Dog
    Cat
    Bird
    Rabbit
    Reptile
    Other

concept Urgency:
  one of:
    Routine
    Urgent
    Emergency

concept AppointmentStatus:
  one of:
    Scheduled
    InProgress
    Completed
    Cancelled

concept Owner:
  has firstName: one string
  has lastName: one string
  has phoneNumbers: at least 1 string
  has email: optional string
  has address: optional string
  has preferredVet: optional Veterinarian

concept Veterinarian:
  has name: one string
  has licenseNumber: one string
  has specialization: optional string

concept Surgeon:
  sub Veterinarian
  has surgeryCount: one int
  has certifiedProcedures: at least 1 string

concept Dentist:
  sub Veterinarian
  has dentalCertification: one string

concept Intern:
  sub Veterinarian
  has university: one string
  has year: one int

concept Vaccination:
  has vaccineName: one string
  has dateAdministered: one string
  has batchNumber: optional string

concept Animal:
  has name: one string
  has species: one Species
  has age: optional int
  has weight: optional float
  has owner: optional Owner
  has vaccinations: Vaccination
  has allergies: string

concept Dog:
  sub Animal
  has breed: optional string
  has neutered: one boolean

concept Cat:
  sub Animal
  has indoor: one boolean

concept Bird:
  sub Animal
  has wingspan: optional float
  has canFly: one boolean

concept Appointment:
  has animal: one Animal
  has scheduledFor: one date_time
  has reason: one string
  has urgency: one Urgency
  has status: one AppointmentStatus
  has diagnosis: optional string
  has treatments: string
  has notes: optional string

property treatedBy: Animal -> Veterinarian

# ------------------------------------------------------------
# Binding to the outside world (Chapter 13)
# ------------------------------------------------------------

concept DomesticDog:
  @iri_name <http://fao.org/species/CanineDomestic>
  sub Dog

# ------------------------------------------------------------
# Flag concepts and inference rules (Chapter 10)
# ------------------------------------------------------------

concept UnvaccinatedAnimal
concept UnsafeAssignment
concept OverweightAnimal

rule flag_unvaccinated:
  match:
    ?animal a Animal
    ?animal vaccinations 0
  then:
    ?animal a UnvaccinatedAnimal

rule flag_intern_emergency:
  match:
    ?appt a Appointment
    ?appt urgency Emergency
    ?appt animal [ treatedBy [ a Intern ] ]
  then:
    ?appt a UnsafeAssignment

rule assign_primary_vet:
  match:
    ?animal a Animal
    ?animal owner [ preferred_vet ?vet ]
  then:
    ?animal treatedBy ?vet

# ------------------------------------------------------------
# Unit-aware weight thresholds (Chapter 11)
# ------------------------------------------------------------

concept OverweightCat

rule flag_overweight_dog:
  match:
    ?dog a Dog
    ?dog weight [ > quantity(40 kg) ]
  then:
    ?dog a OverweightAnimal

rule flag_overweight_cat:
  match:
    ?cat a Cat
    ?cat weight [ > quantity(6 kg) ]
  then:
    ?cat a OverweightCat

# ------------------------------------------------------------
# Guard rails: validation concepts and rules (Chapter 12)
# ------------------------------------------------------------

concept SeniorCat
concept InvalidSurgery
concept UnderVaccinatedDog
concept AtRiskAnimal

rule flag_senior_cat:
  match:
    ?cat a Cat
    ?cat age [ >= 10 ]
  then:
    ?cat a SeniorCat

rule validate_surgery_staff:
  match:
    ?appt a Appointment
    ?appt reason "surgery"
    ?appt animal ?animal
    none ?vet:
      ?animal treatedBy ?vet
      ?vet a Surgeon
  then:
    ?appt a InvalidSurgery

rule check_dog_vaccines:
  match:
    ?dog a Dog
    ?dog vaccinations 0
  then:
    ?dog a UnderVaccinatedDog

rule flag_at_risk:
  match:
    ?animal a Animal
    ?animal age [ > 15 ]
    ?animal weight [ < quantity(2 kg) ]
    ?animal vaccinations 0
  then:
    ?animal a AtRiskAnimal