Palantir Ontology Modeling: 4 Core Principles for Scalable Domain Design

The article opens by recalling the previous discussion of splitting an order table into Order, Customer, Product, and Order Line objects. While that first step clarifies the model, the real test comes when a second or third team integrates: sales builds Sales Customer, support builds Support Customer, finance builds Billing Customer. Each duplicates name, email, phone, yet maintains separate state, relationships, and actions. Six months later the team faces disputes over which is the “real” customer, how to sync a name change, where an agent should start a risk query, how many actions need a freeze rule, and who owns a new compliance field.

Palantir’s ontology design documentation provides four core principles with explicit priority:

Domain-driven design: model the domain, not the source systems.

Don’t repeat yourself: the Rule of Three signals refactor time.

Open for extension, closed for modification: protect stable core, extend from the side.

Composition over deep hierarchies: prefer focused interfaces to deep inheritance trees.

The author then unpacks each principle with concrete examples and a practical sequence.

1. Domain-Driven Design: Model the Business Reality, Not the Source Schema

Palantir places this first because a wrong semantic foundation undermines all later reuse, extension, and abstraction. Objects should be entities or events that business people recognize—Customer, Work Order, Equipment, Inspection—and relationships should reflect real business relations, not just join keys.

Example: ERP stores ERP Equipment (asset ID, purchase price, depreciation), maintenance stores Maintenance Asset (work orders, fault level, last service), IoT stores Connected Device (serial number, sensor readings, online status). Modeling three separate objects creates three islands. A domain-first approach yields a single Equipment with stable identity, linked Work Order s, streaming Sensor Reading s, and clear data-source ownership for finance, maintenance, and operations. Source data remains but no longer dictates business boundaries.

Practical sequence:

Confirm real-world entities, events, and actions with domain experts.

Define their identity, lifecycle, and relationships.

Only then map tables and columns.

2. Rule of Three: Third Repetition Triggers Refactor

After domain modeling, duplication becomes the next problem. Palantir uses an engineering heuristic: one duplicate may be coincidence, two show a pattern, the third demands serious refactoring.

The three Customer objects don’t just share a name; they copy identical fields, similar relationships, duplicated risk logic, three “update contact” actions, and three sets of agent tool descriptions. Copies drift: sales statuses (prospect, active, churned), support statuses (regular, key, complaint), finance statuses (normal, overdue, frozen) all live in a field called status and start overwriting each other.

The fix isn’t necessarily a single monolithic Customer. Teams should first decide:

Which facts belong to the universally agreed customer identity.

Which are only a specific domain’s observation of the customer.

Which logic should become a shared Function.

Which behavior should unify into one business Action.

Which differences should be preserved via relationships, extension objects, or Interfaces.

DRY does not mean “one model for the whole company”; it opposes unjustified copies of the same business concept that drift independently.

3. Open for Extension, Closed for Modification: Protect the Stable Core

Once an object type like Equipment is used by multiple applications, actions, and agents, it behaves like a public API. A seemingly harmless field change can cascade.

Scenario: Equipment runs stably in maintenance, inventory, and production. Compliance wants certification body, expiry, audit trail, status. The naive move adds all fields to Equipment. Then energy adds ten fields, insurance adds eight, safety adds approval states. Most fields stay empty for most assets; the core object widens, permissions become inexplicable.

“Open for extension, closed for modification” does not forbid core changes; it sets a default posture: avoid breaking changes to widely depended-on core semantics; add new capabilities via extensions.

For certification:

Create a linked Equipment Certification object.

Express ownership with a Link.

If multiple types are certifiable, introduce a Certifiable Interface.

Keep certification-specific permissions inside the extension boundary.

Three questions to decide if a field belongs in the core:

Is it fundamental to the entity’s identity or critical in most scenarios?

Is it owned long-term by the core object’s responsible team?

Would the core entity be incomplete without it?

If all answers are no, an extension object or capability interface is safer.

4. Composition Over Deep Hierarchies: Capabilities as Interfaces

Teams often express reuse via classification trees:

Asset
└── Physical Asset
    └── Building
        └── Schedulable Building
            └── Arena

Real capabilities don’t grow along a single tree. An Arena is a Building and a Schedulable Resource; a Warehouse may be both schedulable and inspectable; a Vehicle is not a Building but needs scheduling and inspection. Forcing every combination into the hierarchy produces artificial types like InspectableWarehouse, SchedulableWarehouse, InspectableSchedulableWarehouse, TrackableInspectableVehicle —technical artifacts, not business entities.

Palantir recommends factoring capabilities into focused Interfaces:

Inspectable

SchedulableResource

Trackable

Billable

An object implements any combination. Actions and functions target the Interface, so “schedule inspection” works for factory equipment, warehouses, vehicles, and arenas without per-type duplication. The next article will compare Interface, Shared Property, and Struct—three reuse tools that solve different problems.

5. When Principles Conflict, Preserve Business Semantics First

Real modeling is messy. Deadlines may force a temporary duplicate; performance may require denormalization; legacy systems may need limited mapping. Palantir states these are guidelines, not laws. The key is making trade-offs explicit.

Example of managed technical debt: “These two Customers stay separate because identity alignment is unreliable; unify Interface and query entry first, converge when match accuracy and ownership stabilize.”

Undocumented “we’ll fix it later” becomes permanent architecture.

Official priority when principles clash:

Ensure the model reflects business reality.

Eliminate meaningless duplication.

Protect stable core, design extension boundaries.

Use composition to increase capability reuse.

Don’t force-merge semantically different concepts for DRY. Don’t over-abstract ten layers before the first workflow runs. A good ontology continuously delivers value in real use while keeping a clear evolution path.

6. 12-Question Modeling Review Checklist

Before submitting a new Object Type, Link, Interface, or Action, have modelers, business reps, and app developers walk through:

A. Business Semantics

Does it represent a real-world entity/event, or a table/API/department view?

Is the name a singular noun business people naturally use, free of source-system abbreviations?

Are identity, lifecycle, and fact ownership clear? Are observations mixed with the observed entity?

B. Duplication & Reuse

Does the same concept already exist in another team or ontology?

Have identical attributes, derived logic, or actions been copied to a third place?

Should similar models merge into one canonical object, or keep differences and implement a common Interface?

C. Extension & Composition

Is a new field truly a core fact of the entity, or just one team’s extension need?

Can the capability be added via a new linked object, namespace, or Interface without breaking existing consumers?

Is the model sprouting deep inheritance or “combo types” invented to stitch capabilities?

D. Operations & Governance

Is the right tool used? Human/Agent decisions → Action; automated data transforms → Pipeline.

Are owners and security boundaries clear for core objects, extensions, and actions? Do extensions accidentally widen access?

Are key trade-offs documented: why this design, what was sacrificed, under what conditions to refactor?

The checklist is a gate, not a guarantee—it stops source-system naming, departmental boundaries, and ad-hoc requests from entering the enterprise semantic layer unchecked.

7. Don’t Chase the “Ultimate Ontology” Upfront

Over-abstracting the first version is as dangerous as copying databases. Reuse should grow from observed duplication:

First use case: nail business semantics and security boundaries.

Second use case: observe which structures actually repeat.

Third use case: trigger an evidence-based refactor.

Then protect the stable core and let new capabilities attach via extensions.

The Rule of Three prevents premature abstraction, not repetition. Ontology deserves production-grade design and production-grade iteration.

Conclusion

Moving from tables to business objects only solves “does the model look like reality.” To make ontology a long-term, cross-team, agent-understandable asset, three questions remain: avoid triplicate concepts, add capabilities without breaking the core, share capabilities without a rigid taxonomy.

Palantir’s four principles compress to: Secure business semantics first, then converge duplication; protect the stable core, use composition for change.

Ontology is not a translated schema nor a one-time blueprint—it’s an evolving business software contract.

References

Palantir Docs: Ontology design — Best practices [1]

Palantir Docs: Ontology design — Structural guidance [2]

Palantir Docs: Ontology design — Anti-patterns [3]

Palantir Docs: Interfaces overview [4] [1] https://www.palantir.com/docs/foundry/ontology/ontology-best-practices/ [2] https://www.palantir.com/docs/foundry/ontology/ontology-structural-guidance/ [3] https://www.palantir.com/docs/foundry/ontology/ontology-anti-patterns/ [4] https://www.palantir.com/docs/foundry/interfaces/interface-overview/