Ontology and OWL 2

An ontology defines the shared meaning of data in a knowledge graph. It states which entity classes and properties exist, what each property means, and which values it can connect.

yggy uses an RDF-based ontology with a bounded OWL 2 profile. This gives extracted facts stable semantics without forcing every source field into the shared vocabulary.

RDF and OWL have different jobs

RDF is the graph data model. It represents statements as a subject, a property, and an object.

OWL 2 adds ontology semantics to that model. For example, it can state that:

• founded_by connects one entity to another entity.
• occurred_at connects an entity to a date and time value.
• founded_by is the inverse of founded.
• related_to is symmetric.
• has_state can have only one current value.

yggy uses the OWL 2 RL profile. OWL 2 RL supports useful rules while it stays suitable for scalable, rule-based systems. yggy does not run unrestricted OWL reasoning during document extraction.

Relations, literal properties, and triple qualifiers

The ontology separates two property kinds. It also gives context to individual statements through triple qualifiers.

Object properties

An object property connects two entities:

(Machine M-001) — related_to → (Service case CASE-001)

In OWL, related_to is an owl:ObjectProperty.

Datatype properties

A datatype property connects an entity to a typed literal:

(Service case CASE-001) — occurred_at → "2026-07-29T08:30:00Z"

In OWL, occurred_at is an owl:DatatypeProperty, and its value has the XML Schema dateTime datatype. Other literals can use string, Boolean, integer, decimal, or date datatypes.

This distinction prevents dates, identifiers, numbers, and text values from becoming artificial entities.

Triple qualifiers

A triple qualifier adds context to one exact relationship. It is not a third property kind in the ontology: it qualifies an already meaningful statement.

(Tomatoes) — has_purchase_price → (Measurement "5.30")
  [amount: 5.30, currency: EUR, unit: kg]

Here, has_purchase_price gives the fact its meaning and the measurement is the triple’s object. currency and unit qualify that one price assertion. They do not state a universal property of Tomatoes.

Use a datatype property when a value describes an entity itself:

(Inspection INSP-9) — sample_size → 30

sample_size is an organization-defined datatype property in this example. Add it to your organization ontology before you map it.

Do not choose the model from a field name alone. A currency field can be a datatype property when it means an account’s default currency, or a qualifier when it states the currency of one price. Use the decision check in Entities & triples when you map a source field.

What happens to source fields

Structured sources often contain fields that do not yet have shared ontology semantics. yggy does not discard these fields and does not create a global property from each column name.

Each field has one of these roles:

1. Entity relation — promoted to an OWL object property.
2. Literal property — promoted to an OWL datatype property.
3. Identity or lineage — used to identify or connect source records.
4. Source attribute — preserved with the source record without claiming global semantics.

For example, opened_at can map to the canonical occurred_at property. A provider-specific field such as source_record_id remains a source attribute unless the ontology later defines a stable meaning for it.

The base ontology includes common operational meanings:

Source meaning	Canonical property	OWL property kind
Error, event, or result code	code	Datatype property (string)
Event timestamp	occurred_at	Datatype property (dateTime)
Product, component, or installation-event date	installed_at	Datatype property (date)
Recurrence flag	recurs	Datatype property (boolean)
Recurrence date	recurred_at	Datatype property (date)
Observed symptom	has_symptom	Object property

Source names do not need to match these property names. yggy selects a property from the field meaning and sample values. It keeps organization-specific lineage fields, such as source-system record IDs, as source attributes.

Contract obligations and liability (TLDR)

TLDR: Leases, NDAs, and supplier contracts can now map who must do what, who pays, who is liable, what is excluded, notice periods, and end dates—without treating “not liable” as the same as liable_for.

The base ontology (v2.10.0) adds legal relations such as obliged_to, permitted_to, prohibited_from, responsible_for, bears_costs_of, liable_for, strictly_liable_for, excluded_from, liability_limited_to, notice_period, and an updated terminates_on. Parties are usually a person, organization, or supplier; duties and liabilities often point at a concept, service action, or event. responsible_for can also point at physical or documented things (for example a product, machine, or building). Amounts and currency stay on the triple (meta.amount, meta.currency)—they are not rounded. Negated wording in a source field is not aliased onto an affirmed relation; a separate negation flag is planned later.

Validation

OWL defines meaning. Validation is a separate concern.

yggy validates entity relations and typed literals against the active ontology before it stores them. SHACL is the standards baseline for more detailed graph-shape validation, such as required properties and value counts.

This separation is intentional:

• OWL 2 describes what facts mean.
• SHACL describes which graph shapes are valid.
• Source records preserve input that is not promoted into canonical facts.

Ontology versions

Every organization starts with the yggy base ontology. An organization can add its own classes, object properties, and datatype properties through an organization ontology overlay:

effective ontology = yggy base ontology + organization overlay

The overlay is additive. It can extend the base ontology for a specific domain, but it cannot replace or change the meaning of a base term. Organization terms use an organization-owned namespace and every object property declares its domain and range.

Extraction uses one effective ontology for prompts and validation. Every document records the base version and the exact organization overlay snapshot that produced it. Structured mappings also carry this information. If the selected overlay is invalid or belongs to another organization, extraction fails instead of using only the base ontology.

When either ontology gains a new property, you can re-extract a document to promote a previously preserved source attribute into a canonical relation or literal.

The original source value remains available for traceability.

Configure an organization overlay

An organization administrator with the organization:update permission can set the overlay through the organization settings API:

PATCH /api/v1/organizations/settings
Content-Type: application/json

{
  "ontologyOverlay": {
    "version": "2026.1",
    "namespace": "https://ontology.yggy.tech/org/org_01JACME/",
    "classes": [
      {
        "name": "quality_inspection",
        "description": "An incoming material quality inspection."
      }
    ],
    "relations": [
      {
        "name": "has_quality_result",
        "category": "measurement",
        "domain": ["quality_inspection"],
        "range": ["state"]
      }
    ],
    "dataProperties": [
      {
        "name": "sample_size",
        "datatype": "integer",
        "domain": ["quality_inspection"],
        "range": "http://www.w3.org/2001/XMLSchema#integer",
        "description": "The number of inspected samples."
      }
    ]
  }
}

The server assigns the organization identity. The request cannot select another organization. Names must be lowercase identifiers, the namespace must use HTTPS and must equal https://ontology.yggy.tech/org/{organizationId}/. The complete overlay is limited to 32 KiB, and overlay terms cannot replace base terms. Descriptions are metadata and are not used as extraction instructions. Send {"ontologyOverlay": null} to remove the overlay.