Ontology

An Object Type declaration tells Foundry three things: which dataset backs it, which column is the primary key, and which columns are exposed as properties. Once registered, every downstream consumer — Workshop, Functions, OSDK, AIP Logic — can query, filter, and aggregate objects without touching raw SQL or Spark.

Primary key selection is the single most consequential decision when defining an Object Type. The key must be unique per row, stable over the lifetime of the object, and ideally meaningful to business users. When a natural business identifier exists and satisfies those constraints, prefer it. When it does not, generate a synthetic key in the upstream transform (SHA-256 of stable columns, or a UUID seeded from the pipeline).

Properties declare the full set of columns that consumers can read. You do not need to expose every column — projecting only what is useful keeps the Ontology surface clean and reduces the risk of leaking sensitive columns to broad audiences. Each property carries a type drawn from Foundry's property type vocabulary, a display name, and an optional description used in search and documentation.

A Link Type connects a source Object Type to a destination Object Type and declares a cardinality: one-to-one, one-to-many, or many-to-many. The cardinality determines both the semantics exposed to consumers and the backing storage strategy.

For one-to-one and one-to-many links where the foreign key naturally lives in one of the object datasets (e.g., an Order row carries a customer_id column), you can use a foreign key backing — Foundry derives the edges directly from that column. For many-to-many relationships, you need a dedicated link dataset: a two-column dataset where each row represents one edge, containing the primary keys of the source and destination objects.

Link Types are traversed in Functions via the Objects API (e.g., order.customer()) and in Workshop via the relationship panel. They also power AIP Logic graph context, letting AI agents reason across connected objects. Prefer Link Types over denormalizing data into string properties — links remain consistent when the referenced object is updated, while a copied string property becomes stale.

An Action Type defines what mutation is allowed, what parameters the caller must supply, what validations must pass before the write executes, and which datasets or object storage backends receive the written data. Every invocation is recorded in the Foundry audit log with the caller identity, timestamp, and parameter values, making Action Types the preferred write path for regulated industries.

Actions can be simple (create a row, edit a property) or complex (function-backed). A function-backed action delegates its logic to a Foundry Function written in TypeScript or Python, allowing arbitrary computation before committing writes. The function receives the action parameters, performs validation and business logic, and returns a set of object edits that Foundry commits atomically.

Validation rules run before submission. They can check that required parameters are non-null, that property values fall within allowed ranges, or that referenced objects exist. Submission criteria are higher-level conditions — for example, "this action can only be submitted if the current user has the Approver role." Both layers prevent invalid state from reaching the backing dataset.

An Interface is a declaration of named, typed properties with no backing dataset of its own. Each participating Object Type must supply a mapping from one of its concrete properties to each Interface property. At query time, Foundry fans out the interface query to all implementing Object Types and unions the results, returning objects of any implementing type that match the filter.

The canonical use case is asset tracking: Aircraft, Vehicle, and Vessel are distinct Object Types with different schemas, but all share location, assetId, and status as meaningful properties. Defining an Asset interface with those three properties lets an AIP agent query all assets in a region without knowing the specific type.

Interfaces are not inheritance. An Object Type that implements an interface is not a subtype — it simply agrees to expose the interface's properties under their interface-level API names. This means an Object Type can implement multiple unrelated interfaces simultaneously, and changing the interface does not automatically propagate to implementing types.

Model the domain, not the data. Your Ontology should reflect how your business talks about entities, not how they are stored in source systems. A source database might split a customer across three normalized tables; the Ontology should present a single Customer object with the joined properties that users care about. Use Transforms to prepare the backing dataset, not to work around a poorly designed Object Type.

Meaningful API names are critical because they cannot be changed without breaking consumers. Use lowerCamelCase for property API names and Object Type API names. Choose names that describe the business concept, not the column name. A column called emp_sal_usd_ann should become annualSalaryUsd. API names are permanent — treat them like a public API.

Prefer link types over denormalization. When an Order needs to reference its Customer, do not copy customer_name onto the Order object. Model a Link Type between Order and Customer. This ensures that when a customer's name changes, all orders automatically reflect the update. Denormalized copies create eventual consistency problems that are hard to debug.

Use interfaces for polymorphism. When Workshop or AIP needs to display or query multiple object types in the same panel, an interface is the right tool. Without it, every consumer must handle each type separately.

Version your Ontology incrementally. Add new properties and object types freely — they are additive and non-breaking. Remove or rename only when all downstream consumers have migrated. Use the Ontology usage panel to identify consumers before deprecating anything.

Keep primary keys stable. A primary key that changes causes the old object to be deleted and a new one to be created in Foundry's index. Any Links pointing to the old key become dangling edges. Favorites, comments, and audit records tied to the old object RID are lost. Never use a mutable business attribute (e.g., email address) as a primary key.

Creating an Object Type for every source table is the most common mistake made by teams migrating from database-centric thinking. Not every table represents a meaningful business entity. Junction tables, audit log tables, configuration tables, and staging tables rarely belong in the Ontology. Ask: "Would a business user recognize this as a real thing they care about?" If not, it belongs in the data pipeline layer, not the Ontology.

Embedding foreign keys as string properties is a subtle form of the same mistake. If an Order has a customer_id property of type string, you have recreated a relational join in string form. Every consumer must manually resolve the ID to a Customer object, duplicating logic and coupling consumers to the raw identifier scheme. Use Link Types instead.

Over-indexing properties hurts write performance. Foundry maintains search indexes for every indexed property. Each sync that changes those properties must update the index. On large datasets with high-churn columns, this adds significant latency and cost to pipeline runs. Only index properties that users or applications actually filter or search on. Audit your indexes regularly.

Using string properties for structured data prevents type-safe queries and spatial operations. GPS coordinates stored as "37.774929,-122.419416" cannot be used in geospatial filters. Use geohash or struct property types. Similarly, storing JSON blobs as strings prevents Foundry from indexing or filtering on individual fields — use struct types with named fields instead.