A Foundry pilot usually works. A small team maps a few datasets into the Ontology, builds an operational app, and a planner can finally see open orders next to supplier delays in one place.
Then the second and third use cases arrive. A Customer object means "billing account" to one team and "legal entity" to another. A link that looked like obvious double-counts shipments. An Action that updates a status field has no clear owner, and nobody can say who changed what last Tuesday, or why.
These are rarely platform limitations. They are design decisions made quickly during a proof of concept and then inherited by production. This article covers how to design a Palantir Foundry Ontology that survives that transition: Object Types, Link Types, properties, and the Action governance that connects the model to real workflows.
What a Production-Ready Foundry Ontology Actually Needs
The Foundry Ontology is a semantic layer over your datasets. It maps rows and columns to business concepts through four main building blocks:
Object Types: the entities people work with, such as a Work Order, Supplier, or Aircraft.
Properties: the attributes of those entities.
Link Types: the relationships between Object Types.
Action Types: defined, permissioned ways to change objects and links.
Applications built on Foundry, from operational apps to SDK-based custom software to AI workflows, read and write through this layer. That is what makes it powerful, and it is also why design mistakes spread quickly.
In a pilot, the Ontology is a convenience. In production, it behaves like a public API with many consumers. It needs stable meaning, named owners, controlled change, secure access, and writes you can audit. The rest of this article is about building those properties in from the start.
Start from what people act on
A useful test for a candidate Object Type: would someone open it, assign it, approve it, or track it? If the answer is no, it is probably a property, a lookup, or a pipeline detail.
Avoid creating one Object Type per source table. ERP systems often split one business entity across header, item, and status tables. The Ontology should present the entity users recognize, with the joining done upstream in pipelines.
Granularity takes judgment. Should a Work Order and its individual operations be one Object Type or two? Split them when they have different lifecycles, owners, or access rules. Keep them together when users only ever treat them as one unit.
Choose primary keys that never move
The primary key is the most consequential decision on an Object Type. Links, user edits, and downstream references all depend on it, so changing it later is expensive.
A good key is unique, deterministic, and stable across pipeline rebuilds. Avoid row numbers, surrogate IDs that are regenerated with each run, and natural keys that are reused, e.g., reissued badge numbers. When objects come from multiple source systems, prefix the key with the system and site (for example, SAP-DE01-4500012345) to prevent collisions after a merge.
Be selective with properties
Include the properties people filter on, decide with, or need an AI workflow to reason about. Leave the other 180 source columns in the dataset. Use business names, explicit units, UTC timestamps, and a clear title property so objects are readable in search results and apps.
Getting Link Types Right
A Link Type connects two Object Types with a defined cardinality. One-to-many links are typically resolved through a foreign key property, while many-to-many links are backed by a join dataset.
The goal is to model relationships the business talks about, not every foreign key in the source schema. "Supplier supplies Part" is meaningful. "Table A references column B in a staging table" is not. Name both directions clearly, such as Supplied Parts from the Supplier side and Approved Suppliers from the Part side.
When a link should become an object
Some relationships carry their own data: effective dates, contract prices, approval status. If you need that, consider modeling the relationship as its own Object Type, like a Supplier Part Approval between Supplier and Part. You pay for an extra hop in queries, but you gain history, a lifecycle, and separate permissions. For a simple association with no attributes, a plain link is the better choice.
Verify cardinality against real data
A link declared one-to-many that is actually many-to-many in the data will not always fail loudly. It can produce misleading counts and incomplete traversals instead. Test cardinality assumptions in the backing pipelines before you publish the link.
From Data Model to Operational Model
Data quality belongs upstream
The Ontology reflects whatever its backing datasets contain. Duplicate keys, null foreign keys, and orphaned link targets show up as confusing objects in front of users. Put checks where the data is produced: key uniqueness, required fields, and referential integrity for every link, using Foundry's data health checks and pipeline expectations.
Ownership and lineage
Give every Object Type a named business owner who decides what it means and a technical owner who maintains its pipeline. Foundry's lineage shows how data flows from source to backing dataset, which helps with impact analysis. Lineage does not explain meaning, though, so write real descriptions for Object Types and properties.
Change over time
Decide early whether an Object Type represents current state, history, or both. A common pattern keeps the entity as current state and adds a separate event Object Type, such as Status Change, for history.
Treat schema changes like API versioning. Adding a property is usually safe. Renaming or removing properties, changing types, or altering a primary key can break apps and SDK consumers. Deprecate first, notify consumers, and use review workflows such as ontology branching or proposals where your environment supports them.
Designing for AI applications
AI workflows that reason over the Ontology depend on the same clarity humans do: precise names, useful descriptions, and unambiguous links. When an AI workflow is allowed to propose or make changes, the Action becomes the safety boundary. It should get the same permissions, validation, and audit trail as any human user, not a shortcut around them.
Designing Actions With Governance in Mind
An Action Type is a parameterized, permissioned transaction against the Ontology. It can create, modify, or delete objects and links, and it can trigger side effects such as notifications or webhooks. Simple Actions are configured with rules; complex ones can be backed by functions. Actions are how the Ontology stops being a read-only view and starts supporting decisions.
They are also where most production risk lives. Ontology governance that controls reads but not writes is only half done.
Keep Actions narrow
A single "Update Work Order" Action with 30 optional fields is hard to secure and harder to audit. Separate Actions like Reassign Work Order and Close Work Order each have one purpose, one set of eligible users, and one clear validation rule.
The five governance questions
| Concern | What to define |
|---|---|
| Permissions | Who can submit, separate from who can view. Grant through groups, not individuals. |
| Validation | Submission criteria on the user and parameters, enforced server-side, not just in the UI. |
| Ownership | A named owner, a documented purpose, and the expected callers: people, automations, or AI. |
| Auditability | Who changed what, when, and why. Add a required justification parameter for sensitive changes. |
| Approval | Whether a second person must confirm before the change takes effect. |
Approvals need explicit design
For changes that need sign-off, a portable pattern is a request object with a status, plus a separate approval Action limited to approvers. Submission criteria can block self-approval by checking that the approver is not the requester. If your environment offers a native approval capability, evaluate it against this pattern, but make the approval path visible in the model either way.
A Practical Enterprise Example
Consider a hypothetical manufacturer that wants to manage supplier quality problems across several plants. Today, incidents live in spreadsheets, and putting a supplier on hold means an email thread with procurement.
Object Types and Link Types
- Supplier, keyed by a global vendor ID, not a per-plant ERP code.
- Part, linked many-to-many to Supplier through an approved supplier list.
- Plant, the site where incidents are raised.
- Quality Incident, linked to one Part, one Plant, and one Supplier.
- Supplier Hold Request, linked to one Supplier and to the incidents that justify it.
Actions
| Action | Who can submit | Key validation | Effect |
|---|---|---|---|
| Log Quality Incident | Plant quality engineers | Part is active at the selected Plant; severity required | Creates an incident and its links |
| Request Supplier Hold | Quality leads | At least one linked incident; justification required | Creates a request with status Pending |
| Approve Supplier Hold | Procurement leads | Approver is not the requester; request is Pending | Sets the Supplier's hold status and notifies buyers |
| Release Supplier Hold | Procurement leads | Supplier is currently on hold; reason required | Clears the hold and records the release |
An AI assistant could summarize open incidents for a supplier and draft a hold request. Only a procurement lead can submit the approval, so the most consequential step stays with a human.
One decision remains outside the Ontology: which system owns the hold status. If the ERP blocks purchase orders, the approved hold must reach it, for example through a webhook side effect or an outbound sync. Define the system of record explicitly, or two systems will disagree about whether a supplier is blocked.
Common Ontology Design Mistakes
- Mirroring the source schema. The Ontology becomes a harder-to-query copy of the ERP instead of a model of the business.
- Unstable primary keys. Keys that shift on rebuild break links and orphan user edits.
- Catch-all Object Types. A single Asset type covering vehicles, buildings, and software licenses forces dozens of mostly-null properties and muddled permissions.
- Generic write Actions. "Edit Object" style Actions make validation and audit nearly meaningless.
- Governing reads but not writes. Row-level access is carefully designed, while any editor can submit any Action.
- No owners or descriptions. Six months later, nobody knows whether status means ERP status or operational status.
- Using the Ontology as a reporting layer. Heavy aggregations usually belong in datasets and analytics tools, with the Ontology focused on entities people act on.
- Breaking changes without a consumer inventory. Renaming a property can quietly break apps, automations, and SDK clients you did not know existed.
Production Readiness Checklist
Use this before promoting an Object Type, Link Type, or Action to production.
Model
- Each Object Type represents something users open, assign, approve, or track.
- Primary keys are unique, deterministic, and stable across rebuilds and source systems.
- Properties include explicit units and business names. Timezones are all the same.
- The link cardinality is tested on real data and both directions are explicitly stated.
Data and ownership
- Backing datasets have health checks for key uniqueness, required fields, and link integrity.
- Every Object Type has a business owner, a technical owner, and a written description.
- History requirements are decided: current state, event objects, or both.
- Consumers are known, and there is a deprecation process for breaking changes.
Actions
- Each Action has a single purpose and a named owner.
- Submission permissions are group-based and distinct from read access.
- Validation is performed server-side via submission criteria or function logic.
- Sensitive Actions require a justification and, where needed, a second approver.
- AI-initiated changes go through the same Actions and controls as human changes.
- The system of record is defined for any value that is written back to external systems.
Final Takeaways
A production Foundry Ontology is a contract, not a diagram. Object Types should reflect the entities people act on, Link Types should capture relationships the business actually uses, and primary keys should be treated as permanent from day one.
Actions deserve the most care, because they are where the model changes the business. Keep them narrow, permission them deliberately, validate server-side, and make approvals and audit trails explicit.
None of these rules is absolute. Granularity, history, and the choice between a link and an intermediate object depend on your workflows. Whether the work is done by an internal platform team or with a Palantir consulting partner, the useful test is the same: can a new team understand, trust, and safely change this Ontology without asking the people who built it?
Top comments (0)