Ontology Design Principles for Reliable iOS App Intents

Apple's App Intents framework asks every iOS app to define AppEntity and AppEnum types — a lightweight ontology hiding in plain sight. Teams that skip identity, typing, and versioning discipline end up with Siri and Shortcuts integrations that break silently as the app grows. Formal ontology-design habits fix this.

What App Intents Actually Ask Developers to Model

App Intents is Apple's framework for exposing an app's actions and data to Siri, Shortcuts, Spotlight, and visual intelligence without the app having to be in the foreground. The two building blocks developers reach for are AppEntity, a typed, identifiable object the system can look up and display, and AppEnum, a closed set of parameter values the system can present in Siri or Shortcuts UI. Declaring either one is schema design, not just API wiring: an AppEntity needs a stable identity, a display representation, and a set of typed properties before the system can reliably find, show, and act on an instance of it again.

That is a problem teams building production iOS apps run into constantly — it's one of the recurring architecture questions YuSMP's iOS development team works through with clients adopting Siri and Shortcuts integrations, because the entity decisions made when a Siri feature first ships determine whether the next feature can reuse that entity or has to invent a parallel one.

The fix isn't a bigger framework. It's treating every AppEntity and AppEnum declaration as what it actually is: a small, versioned ontology that has to hold together as the app's Siri and Shortcuts surface grows past the first feature that used it.

Why AppEntity and AppEnum Are Lightweight Ontologies

Identity — what makes two AppEntity instances "the same thing"

A formal ontology class is defined by what makes two instances of it identical or distinct, not just by the properties it happens to carry. AppEntity forces the same question: its id has to be stable across launches and across the entity's own property changes, because Siri, Spotlight, and Shortcuts all cache entity identifiers and resolve a stored Shortcut or a recent Siri result back to that identifier later. An entity whose identity drifts — built from a mutable property instead of a durable key — looks fine in testing and then silently stops resolving once a user's saved Shortcut points at an identifier the app no longer recognizes.

Typed properties vs. free-form strings

The same discipline that keeps a Common Core Ontologies class useful — typed properties related through named relations, rather than a bag of untyped strings — is exactly what makes an AppEntity usable by the system. A property typed as a date, a measurement, or a reference to another AppEntity lets Siri and Spotlight reason about it structurally: sort it, filter it, display it with the right formatting. A property collapsed into a free-form string loses all of that, and it is the same failure mode CCO-style mid-level ontologies are built to prevent in backend data integration — typed, identifiable concepts instead of untyped fields that different consumers interpret differently.

Where Ad Hoc Entity Modeling Breaks Down at Scale

Cross-app consistency (App Intent Domains)

App Intent Domains let the system recognize that several apps on a device implement the same kind of action — starting a workout, playing media, placing an order — so a generic Siri request can be routed to whichever app the user actually wants. A domain only pays off if the app's own entities already carry consistent identity and typing; bolting a domain onto an AppEntity that was modeled ad hoc, with identity baked into a mutable field and properties stored as loose strings, reproduces at the cross-app level exactly the meaning-drift problem a shared ontology exists to prevent at the data-integration level.

Schema drift across OS releases

An app's Siri and Shortcuts surface doesn't get rebuilt from scratch every release; it accumulates. A property added in one OS cycle and renamed or retyped in the next is invisible in Xcode's build output but very visible to a user whose year-old Shortcut suddenly stops matching, because the system resolved it against a cached entity schema that no longer lines up with what the app ships today.

Applying Ontology Design Patterns to App Intents

The checklist that keeps a formal ontology coherent over years of change maps directly onto AppEntity and AppEnum design: give every entity a stable identifier that never depends on a value the user or the app can edit; prefer explicit, typed properties — dates, measurements, references to other entities — over stringly-typed data that forces every consumer to re-parse meaning out of free text; document whether an AppEnum's case set is meant to stay closed or is expected to grow, so adding a case later is a deliberate, additive decision rather than an accidental one; version entity contracts the way a public API is versioned, with additive changes safe and redefinitions treated as breaking; and keep naming consistent across any App Intent Domain the app participates in, so a shared action means the same thing in every app that implements it. None of this requires new tooling — it requires applying the same discipline a mid-level ontology like Common Core Ontologies applies to backend data models, one level up, to the entities an iOS app exposes to the system. For the underlying API mechanics, Apple's App Intents framework documentation covers the specifics of declaring entities, enums, and domains.

Frequently Asked Questions

What is an AppEntity in iOS development?

An AppEntity is a typed, identifiable object that an iOS app exposes to the system so Siri, Shortcuts, Spotlight, and visual intelligence can find, display, and act on it. It defines an identity, a display representation, and a set of typed properties, which makes it a lightweight ontology class rather than just a data-transfer object.

Is AppEnum the same as a Swift enum?

An AppEnum is backed by a Swift enum but adds a closed, system-visible vocabulary with localized display names for each case. The system treats it as a fixed parameter value set it can present in Siri and Shortcuts UI, which is why its cases need the same care as a controlled vocabulary in a formal ontology, not just internal code constants.

Do App Intents require a knowledge graph or database?

No. App Intents work with whatever persistence layer the app already uses — Core Data, SwiftData, a remote API, or plain structs. The ontology discipline this article describes is a modeling practice applied to AppEntity and AppEnum declarations, not a requirement to adopt a graph database or triple store.

How do App Intent Domains help with cross-app consistency?

App Intent Domains let multiple apps on a device agree on a shared vocabulary for common actions and entities, so the system can route a request like starting a workout or playing media to whichever app implements that domain. Adopting a domain only pays off if the app's own AppEntity and AppEnum definitions already carry the same identity and typing discipline a domain assumes.

What happens if I change an AppEntity's properties in a new app version?

If a property is removed or its type changes incompatibly, any Shortcut, Siri phrase, or Spotlight result built against the old shape can silently stop resolving on devices that haven't updated yet, because the system cached the entity's prior schema. Additive changes — new optional properties, new enum cases — are safe; redefining or removing an existing property needs the same deprecation discipline as a breaking API change.

Does this apply to Android equivalents too?

Android's App Actions and App Shortcuts raise a similar modeling question, but the APIs, lifecycle, and system integration points differ enough that the two platforms need separate treatment. This article focuses specifically on iOS App Intents.