Workshop 3: Ontology

This workshop decides the shape of the knowledge graph: which things Experio tracks, what it records about each one, and how they connect. That shape is the ontology. Extraction can only fill in what the ontology defines, and chat can only answer questions whose nouns, verbs and filters exist in it. If a golden question needs “who led the project” and the ontology has no way to record a role on an assignment, no prompt tuning will fix the answer later. You build the ontology from the questions, not from the documents.

At a glance


Purpose	Agree the entity types, attributes, relationships, match keys and vector indexes that the golden questions need
When	Phase 2 Model, week 2–3. Run before Workshops 4–7
Duration	3 hours, plus a 60-minute follow-up after the first Test Ingestion runs
Attendees	Experio: FFE (facilitates), Experio SMEs as needed. Client: PM, super user, one SME per use case, the owner of each structured source
Inputs	Golden questions with expected answers (Workshop 1), data inventory with keys (Workshop 2), 2–3 sample documents per document family
Outputs	Ontology diagram, entity/attribute/relationship table, question-to-model trace, match key per entity type, list of taxonomies to build, a saved ontology revision
Admin pages	Model & Define > Ontology, Model & Define > Compatibility

Before the workshop

FFE and Experio SMEs

Print or share the golden questions from Workshop 1, grouped by use case.
Open Model & Define > Ontology and review the default ontology. Note which types fit the client (Client, Employee, Project, Proposal, Contract, Skill often do) and which do not (for example TimeEntry or ProductCatalog for a consulting firm).
Pre-mark each question: underline nouns, circle verbs, box filters and sorts. You will redo this with the room, but a draft keeps the session moving.
Pull the column headers of each structured export from the data inventory. The keys there (employee_id, project_code, account_id) become attributes and match keys.

Client homework (super user)

Confirm the golden questions are final for the pilot. Adding questions later is fine; changing their meaning mid-workshop is not.
Bring the headers of every structured export and one real example row.
Bring any existing picklists you already know about (industries, service lines, skills). They feed Workshop 4.

Agenda

Time	Segment	Output
0:00	Why the ontology matters; walk one question end to end	Shared vocabulary
0:15	Question walk: nouns, verbs, filters, controlled words	Raw candidate list
1:00	Consolidate entity types; compare with the default ontology	8–15 entity types
1:30	Break
1:40	Attributes: types, extraction instructions, formats	Attribute table
2:10	Relationships: direction, names, relationship attributes	Relationship table
2:35	Keys and vector indexes	Match key per type, index list
2:50	Trace check: every question maps to the model; scope cut	Trace table, parking lot

Running the workshop

1. Walk each question

Put one question on screen at a time and mark it up with the room.

Mark	Becomes	Question to ask the room
Nouns (“projects”, “clients”, “consultants”)	Entity types	”Is this a thing we want to list, count or look up by name?”
Verbs (“delivered for”, “led”, “worked on”)	Relationships	”Which two things does this connect, and which way does it read?”
Filters and sorts (“since 2023”, “below $1M”, “in the next 90 days”)	Attributes with a type	”Would you filter or sort by this? Is it a date, a number, yes/no, or a choice from a list?”
Controlled words (“healthcare”, “cloud migration”, “reporting obligation”)	Taxonomies or enum attributes	”Is there an official list of these values somewhere?”

Write every candidate down, even duplicates. Consolidate afterwards.

2. Consolidate entity types

Use singular PascalCase names: Client, Project, Employee, Obligation. Not Clients, not client_account.
Merge synonyms into one type. “Customer”, “account” and “client” are one Client. Record the other words as synonyms on the entity type; chat uses them to map informal terms to the right type.
Start from the default ontology where it fits. Keep its types and attributes when they match, rename when only the name differs (for example Division to Practice), and delete what no question needs.
Aim for 8–15 entity types for a pilot. More than that usually means you are modelling the documents rather than the questions.

Ask: “Which question breaks if we drop this type?” If none does, drop it or put it on the parking list.

3. Decide attributes

For each entity type, list only the attributes a question filters on, sorts on, returns, or needs as a key.

Type	Use for	Example
Text	Names, descriptions, codes	`project_code`, `description`
Number	Anything you compare or add up	`contract_value`, `liability_cap`
Date	Anything with “since”, “before”, “expiring”	`start_date`, `expiration_date`
Boolean	Yes/no flags	`is_active`
List	Several values on one node	`aliases`
Enum (with options)	A short fixed list that belongs to this attribute only	`outcome`: won / lost / pending

Write an extraction instruction for every attribute a document will fill. Say where the value usually appears, what to do when it is missing, and the format you want. Put the format in the instruction itself, for example “Format: YYYY-MM-DD” or “Number in US dollars, no currency symbol”. Long lists of allowed values belong in a taxonomy; reference it with @TaxonomyName (see Workshop 4).

The visual editor’s type list offers Text, Number, Date and List. Set boolean and enum attributes in the JSON view; an enum needs an options array. Enum options are validated when you save but are not sent to the extraction model, so also list the allowed values in the extraction instruction (“One of: MSA, SOW, amendment.”). Values are stored as text.

4. Decide relationships

Name relationships as UPPER_SNAKE verbs that read left to right: Employee WORKS_ON_PROJECT Project, Contract IMPOSES Obligation.
Model one direction only. Chat can follow a relationship either way, so do not add inverse pairs like HAS_EMPLOYEE and WORKS_FOR.
Put facts about the connection on the relationship, not on either end. The role someone played on a project belongs on WORKS_ON_PROJECT {role, start_date, end_date, hours}, because the same person has different roles on different projects.
Mark a relationship Required upstream relationship only when the child cannot be created correctly without its parent. The flag treats the relationship’s source as the parent, so the relationship must point parent to child, and the source type must have a vector index. See Workshop 5 for how artifact types use it.

Ask: “When this appears in a document, which end is the thing the document is about?“

5. Decide keys and vector indexes

For each entity type, agree the match key: the attribute that identifies one real-world thing across sources. Record it now; you enter it later in data mappings (Workshop 6) and matching strategies (Workshop 7). The ontology itself has no “key” field, but the key must exist as an attribute. Turn on a vector index for entity types that users mention by name in questions, and for types that documents must match by similarity. Chat resolves names in a question (“Lakeshore”, “Bob Chen”) through exact matches and these indexes, and document matching can only use Vector Similarity on an indexed type. Small closed lists (Practice) rarely need one.

6. Trace and cut

Fill in the question-to-model trace table (see the worked example). Every golden question must map to types, relationships and attributes that exist. Anything in the model that no question uses goes to a parking list for after the pilot.

Worked example: Northbridge Consulting

Marcus Lee (super user), Dana Ortiz, Sam Whitfield and Helen Park walked the nine golden questions. They kept Client, Employee, Project, Proposal, Contract, Skill and Obligation from the default ontology, renamed Division to Practice, and deleted the rest.

Entity type	Attributes (type)	Match key	Vector index
Client	name (text), account_id (text), industry (text, `@Industry`), region (text)	`name` (canonical Salesforce name)	Yes, name
Project	name, project_code (text), start_date, end_date (date), contract_value (number), service_line (text, `@ServiceLine`), description (text)	`project_code`	Yes, name
Employee	name, employee_id, email, title, level, location (text)	`email` (structured); name for documents	Yes, name
Practice	name (text)	`name`	No
Skill	name (text, from `@Skills`), category (text)	`name`	Yes, name
Proposal	name (text), submitted_date (date), outcome (enum: won / lost / pending), value (number)	`name`	No
Contract	name (text), contract_type (enum: MSA / SOW / amendment), effective_date, expiration_date (date), liability_cap (number)	`name`	Yes, name
Obligation	name (short label), description (text), obligation_type (text, `@ObligationType`), due_date (date), frequency (enum)	none; always created in the context of its Contract	Optional, on description

Relationship	Attributes	Notes
Project FOR_CLIENT Client		Created from `projects.csv`
Employee WORKS_ON_PROJECT Project	role, start_date, end_date, hours	From `assignments.csv`; answers “who led”
Employee HAS_SKILL Skill	proficiency	From resumes
Employee MEMBER_OF Practice; Project DELIVERED_BY Practice		From HR and project exports
Employee REPORTS_TO Employee		From `employees.csv` manager email
Proposal SUBMITTED_TO Client; Proposal RESULTED_IN Project		From proposals and CRM
Contract WITH_CLIENT Client; Contract GOVERNS Project; Contract AMENDS Contract		From SOWs and MSAs
Contract IMPOSES Obligation		Required upstream: obligations resolve under their contract
Project USED_SKILL Skill		Created by an enrichment rule (Workshop 8)

Sample extraction instructions Helen agreed for Contract:

expiration_date: The date the agreement ends. Look for "Term", "Expiration Date" or
"shall remain in effect until". If the term is stated as a duration, add it to the
effective date. Leave blank if the contract renews automatically with no end date.
Format: YYYY-MM-DD.

liability_cap: The maximum aggregate liability in the "Limitation of Liability" clause.
If the cap is a multiple of fees, leave blank and quote the clause in description.
Format: number in US dollars, no currency symbol or commas.

Question to model trace

Question	Entity types	Relationships	Attributes and taxonomies
Q1 Cloud migration projects for healthcare clients since 2023, and who led each	Project, Client, Employee	FOR_CLIENT, WORKS_ON_PROJECT	Project.service_line (`@ServiceLine`: Cloud Migration), Client.industry (`@Industry`: Healthcare leaves), Project.start_date, WORKS_ON_PROJECT.role = “Engagement Lead”
Q4 Azure data platform experience and healthcare work	Employee, Skill, Project, Client	HAS_SKILL, WORKS_ON_PROJECT, FOR_CLIENT	Skill.name (`@Skills`: Azure Data Platform), Client.industry
Q7 SOWs expiring in the next 90 days, and for which clients	Contract, Client	WITH_CLIENT	Contract.contract_type = SOW, Contract.expiration_date
Q8 Reporting obligations under the Lakeshore Health MSA	Contract, Client, Obligation	WITH_CLIENT, IMPOSES	Contract.contract_type = MSA, Client.name, Obligation.obligation_type (`@ObligationType`: Reporting)

Q7 showed that expiration_date must be a date, not text, or “next 90 days” cannot be computed. Q1 showed that “who led” needs role on the relationship, not a lead attribute on Project.

Accelerate with AI

In development — availability depends on your release.

The knowledge-model copilot can draft a starting ontology. Attach 3–5 sample documents, the structured export headers and the golden questions file (questions.md). It proposes entity types, attributes and relationships as cards. Treat the draft as pre-reading: review each card in the workshop, apply the ones the room agrees, and save on the Ontology page. The manual path above always works and is the one to use when the copilot is not in your release. Admin Copilot (⌘J) is available today and can answer “how do I” questions about the ontology editor from these docs.

Entering it in Experio

Open the editor

Go to Model & Define > Ontology. Use the Canvas view to add entity types and draw relationships, or the Json view to edit the schema directly (needed for boolean and enum attributes).

Add entity types

For each type, fill Node Name, Semantic Intent (one sentence on what it means) and Synonyms on the Details tab, then add attributes with type and extraction instructions on the Attributes tab.

Add relationships

Choose source entity, relation type and target entity. Add relationship attributes (for example role). Tick Required upstream relationship only where agreed.

Turn on vector indexes

Select the entity type and open the Indexes tab. Enable the name index (the expression defaults to name) and any attribute indexes on text or list attributes.

Save a revision

Click Save. If the change renames or deletes anything, a confirmation lists the impact. Each save creates a new revision you can compare or roll back from Revision History.

Check compatibility

Open Model & Define > Compatibility and fix anything invalid before the next scan.

Revisions and compatibility

Every save publishes a revision, and Experio re-checks everything that depends on the ontology: artifact types, data mappings, enrichment rules and matching strategies. See ontology compatibility.

Change	Effect on dependents	Blocks ingestion?
Add a type, attribute or relationship	None	No
Rename	Names update automatically; dependents become stale for review	No (warning only)
Delete	Dependents that still reference it become invalid	Yes, until fixed and re-validated

Deleting from the ontology does not delete nodes already in the graph. Early in the project, before artifact types and mappings exist, changes are cheap. After pilot ingestion, prefer renames and additions, and plan deletes together with the fixes to dependents. Detail: Ontology and Ontology Compatibility.

Common pitfalls

Modelling the documents. A Resume entity type with an experience blob answers nothing. Model the person, skills and projects the resume describes.
Facts on the wrong end. A role, date range or proficiency that depends on the pair belongs on the relationship.
Dates and money as text. Filters like “since 2023” and “below $1M” need date and number types.
Enum values only in options. The extraction model does not see them; repeat them in the instruction.
No key. If two sources describe the same client and there is no agreed key, you will get duplicates. Decide keys now.
Inverse relationships. HAS_PROJECT and FOR_CLIENT side by side confuse extraction and chat. Keep one.
Keeping unused default types. Every extra type is something extraction may try to fill. Delete what no question needs, and remove any seeded artifact types that reference deleted types so they do not show as invalid.

Exit criteria

Every golden question appears in the trace table with types, relationships and attributes that exist in the saved ontology
8–15 entity types, singular PascalCase; relationships UPPER_SNAKE, one direction each
Every filter or sort attribute has the right type (date, number, boolean, enum)
Extraction instructions written for every attribute documents will fill, including format and allowed values
Match key agreed for every entity type and present as an attribute
Vector indexes enabled on the types users name in questions
Taxonomies needed (@Industry, @ServiceLine …) listed for Workshop 4
Ontology saved; Model & Define > Compatibility shows no invalid configs
Super user can explain the model to a colleague using the diagram

Workshop 4: Taxonomies builds or imports the controlled lists the ontology references.

Start Here

Plan

Workshops

Validate & Launch

Reference

At a glance

Before the workshop

Agenda

Running the workshop

1. Walk each question

2. Consolidate entity types

3. Decide attributes

4. Decide relationships

5. Decide keys and vector indexes

6. Trace and cut

Worked example: Northbridge Consulting

Question to model trace

Accelerate with AI

Entering it in Experio

Revisions and compatibility

Common pitfalls

Exit criteria

Next

​At a glance

​Before the workshop

​Agenda

​Running the workshop

​1. Walk each question

​2. Consolidate entity types

​3. Decide attributes

​4. Decide relationships

​5. Decide keys and vector indexes

​6. Trace and cut

​Worked example: Northbridge Consulting

​Question to model trace

​Accelerate with AI

​Entering it in Experio

​Revisions and compatibility

​Common pitfalls

​Exit criteria

​Next

At a glance

Before the workshop

Agenda

Running the workshop

1. Walk each question

2. Consolidate entity types

3. Decide attributes

4. Decide relationships

5. Decide keys and vector indexes

6. Trace and cut

Worked example: Northbridge Consulting

Question to model trace

Accelerate with AI

Entering it in Experio

Revisions and compatibility

Common pitfalls

Exit criteria

Next