Define your ontology

In Port, your data model is more than a schema — it is an ontology. A schema tells a system what fields exist. An ontology tells a system what those fields mean.

This distinction matters enormously for AI agents. When an agent queries your context lake, it reads descriptions, relation titles, and property types to understand your organization's structure and make decisions. A schema without semantic meaning is a structure humans can browse. An ontology with semantic meaning is a knowledge graph agents can traverse and act on.

This page covers various elements that give your context lake ontological meaning:

Blueprint and property descriptions

The description field on a blueprint and on each of its properties is how you communicate intent to agents and to future humans reading the model.

{
  "identifier": "service",
  "title": "Service",
  "description": "A deployable unit of software owned by a team. Represents a microservice, backend API, or frontend application tracked in the catalog.",
  "schema": {
    "properties": {
      "on_call": {
        "type": "string",
        "format": "user",
        "title": "On-call engineer",
        "description": "The engineer currently on-call for this service. Updated automatically from PagerDuty."
      },
      "tier": {
        "type": "string",
        "title": "Service tier",
        "description": "Business criticality of this service. Tier 1 = customer-facing revenue path. Tier 2 = internal platform dependency. Tier 3 = non-critical tooling.",
        "enum": ["tier-1", "tier-2", "tier-3"]
      }
    }
  }
}

Write descriptions as if explaining to a new team member who has no context. The agent has exactly the same level of familiarity.

• The blueprint description should explain what this entity represents in your organization, not just what the word means generically.
• Property descriptions should explain what the value means, where it comes from, and any implicit conventions (for example, which team owns it, or what the expected format is).

These descriptions are read by Port AI when it queries the catalog, by custom agents when they plan their next action, and by external agents connecting via the MCP server. They are also rendered in the UI when a user hovers over the info icon on a property.

Relation titles and descriptions

Relations are the edges of your knowledge graph. The title you give a relation is the semantic label of that edge — it is how agents understand the connection between two blueprints. The description explains why the edge exists and what it means to traverse it.

{
  "relations": {
    "owned_by": {
      "title": "Owned by",
      "description": "The team responsible for this service's development and on-call. Used to route incidents, enforce ownership-based permissions, and calculate team workload.",
      "target": "team",
      "required": false,
      "many": false
    },
    "runs_in": {
      "title": "Runs in",
      "description": "The cloud environment (production, staging, dev) where this service is currently deployed. Many-to-many: a service can run in multiple environments simultaneously.",
      "target": "environment",
      "required": false,
      "many": true
    },
    "depends_on": {
      "title": "Depends on",
      "description": "Upstream services this service calls at runtime. Used to calculate blast radius during incidents and map the impact of a degraded dependency.",
      "target": "service",
      "required": false,
      "many": true
    }
  }
}

Titles provide the semantic label. Compare these two for the same structural edge:

Vague title	Semantic title
team	Owned by
env	Runs in
svc	Depends on

The vague titles are technically correct but semantically silent. When an agent asks "which team is responsible for the payment service?", it needs to traverse the Owned by edge — not figure out that team might mean ownership.

Descriptions resolve ambiguity that a title alone cannot. A service can own, use, deploy to, or report to a team in different contexts — all of which would share the same target blueprint. The description is what tells an agent which kind of connection this is, when to traverse it, and what it means in your organization's domain.

Property types as semantic signals

Choosing a property type is not just a validation decision — it is a semantic declaration. Port offers several property types, and each one signals something different about the value.

When you use this type	The agent understands
team	This value is a Port team — it has members, a manager, and can be used for ownership and permission resolution.
user	This value is a Port user — it has an email, role, and team memberships.
url	This value is a navigable link to an external resource (dashboard, repository, runbook).
boolean	This is a binary flag. The agent can use it as a condition without parsing string values.
number	This is a numeric measure. The agent can compare, rank, and threshold on it.
string	This is free-form text. The agent cannot make structural assumptions about it.

Using string for a value that is structurally a team name, a URL, or a numeric count deprives the agent of the semantic signal it needs to reason correctly. An agent that sees a team-typed owned_by property can immediately resolve ownership, query that team's properties, and apply team-based permissions. An agent that sees a string field named owner has to guess.

The same principle applies to format specifiers like date-time, email, and ipv4: they narrow the value's meaning and give agents precise handling rules.

Enum values with descriptions

Enums define the vocabulary of a field. Without a description, an agent can only infer meaning from the value string itself.

{
  "severity": {
    "type": "string",
    "title": "Severity",
    "description": "Impact level of this incident on users and revenue. critical = complete service outage or data loss. high = major feature unavailable, no workaround. medium = degraded performance, workaround exists. low = cosmetic or minor issue, no user impact.",
    "enum": ["critical", "high", "medium", "low"]
  }
}

Put the per-value meaning directly in the property description. Explain:

• What each value represents in your organization's conventions.
• What conditions or thresholds map to each value.
• How the value is set (manually, automatically, by an SLA policy, etc.).

An agent asked to "escalate all critical incidents in the payment service" can only act correctly if it knows that critical means complete outage, not just "bad". An agent asked to "create an incident with appropriate severity" needs the vocabulary to make that judgment.

---

Taken together, these elements transform your context lake from a record store into a knowledge graph. Every description you write, every relation title you choose, every property type you select, and every enum definition you annotate is a piece of ontological signal that makes the graph richer for both agents and humans.

For the technical fields and configuration options, see set up blueprints, properties, and relate blueprints.