> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `aireg` CLI; `aireg --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces.

# Ontology data model

> Every Ontology definition kind with its fields, types, constraints, cardinality, derivations, SKOS terminology, records, and interchange formats.

<Badge color="orange">Preview</Badge>

This page lists the fields of each Ontology definition kind as they appear in Studio's **JSON** view, import documents, and release schemas. Every kind rejects unknown fields. For what each kind means, see [Ontology concepts](/ontology/concepts).

## Common rules

Every definition belongs to one ontology through `ontology_id` and has an `api_name`. Its name and description are separate, editable display fields, not part of the definition JSON.

| Rule | Value |
| - | - |
| `api_name` | Starts with a lowercase letter; lowercase letters, digits and `_` only; up to 128 characters. Unique per kind in an ontology. |
| References between definitions | `{ "kind": "<definition kind>", "artifact_id": "<id>" }`. A release resolves each to an exact version and checksum. |
| IRIs (`source_iri`, `namespace_iri`) | Absolute IRI, up to 2,048 bytes. |
| Strings | Up to 4,096 bytes unless a field states a narrower limit. |
| One definition | Up to 64 KiB of canonical JSON. |
| Forbidden content | Field names such as `table`, `column`, `sql`, `query`, `join`, `connection`, `credential`, `url` and `token` are rejected anywhere in a definition. Physical detail belongs in a [Bindings](/ontology/concepts/bindings). |

## `ontology`

| Field | Type | Required | Meaning |
| - | - | - | - |
| `api_name` | string | Yes | Stable name of the ontology. |
| `compatibility_policy` | `none` \| `backward_compatible` \| `full_compatible` | Yes | Versioning policy. Fixed once a release exists. |
| `namespace_iri` | string | No | Base for Studio's suggested IRIs. Fixed once a release exists. |
| `icon` | string | No | One of 24 named glyphs, such as `cart` or `store`. Display only, not part of a release. |
| `color` | string | No | One of `blue`, `indigo`, `violet`, `pink`, `red`, `orange`, `amber`, `green`, `teal`, `gray`. Display only. |

## `ontology_object_type`

| Field | Type | Required | Meaning |
| - | - | - | - |
| `ontology_id` | string | Yes | Owning ontology. |
| `api_name` | string | Yes | Stable name, such as `customer`. |
| `object_kind` | `entity` \| `event` | Yes | Something that exists over time, or something that happened. |
| `properties` | array of [properties](#property) | Yes | Up to 256. May be empty. |
| `implements` | array of references | No | Interfaces this type implements. Each interface's required properties must appear here with the same data type. |
| `source_iri` | string | No | External identity for RDF, OWL and SPARQL. Without it, validation warns `missing_source_iri`. |
| `constraints` | array of [constraints](#constraint) | No | Up to 128 named rules. |
| `annotations` | object | No | Non-semantic metadata. May hold `physical_references`, up to 32 locators. |

### Property

Used in object types, interfaces, links, action parameters, and `struct` fields.

| Field | Type | Required | Meaning |
| - | - | - | - |
| `api_name` | string | Yes | Unique within its owner. |
| `value_schema` | [value schema](#value-schema) | Yes | The property's data type. |
| `is_required` | boolean | No | Default `false`. |
| `is_identifier` | boolean | No | Default `false`. An identifier must be required and a single value, not `array` or `struct`. |
| `shared_property` | reference | No | A shared property type. The `value_schema` must equal it exactly. |
| `derivation` | [derivation rule](#derivations) | No | How the value is computed. Its result must fit `value_schema`. |
| `annotations` | object | No | Non-semantic metadata, such as `source_iri`. |

### Value schema

| `kind` | Studio label | Allowed constraints |
| - | - | - |
| `string` | Text | `format`, `max_length`, `enum` (unique strings, at least one) |
| `integer` | Whole number | `min`, `max`, `unit` |
| `decimal` | Decimal | `min`, `max`, `unit`, `precision`, `scale` (scale ≤ precision) |
| `boolean` | Yes / no | None |
| `date` | Date | `format` |
| `timestamp` | Date and time | `format` |
| `duration` | Duration | `format`, `unit` |
| `binary` | Binary | `max_length` |
| `reference` | Reference | `reference` (required): an object type or interface |
| `array` | List | `items` (required): the item's value schema |
| `struct` | Group | `fields` (required): one or more properties |

A constraint that belongs to another kind is rejected with `invalid_value_constraint`, as is `min` greater than `max`. Value schemas nest up to 32 levels.

### Constraint

A named rule on an object type's values. Ontology versions it and returns it to agents; it does not evaluate it against data.

| Field | Type | Required | Meaning |
| - | - | - | - |
| `api_name` | string | Yes | Rule name. |
| `severity` | `info` \| `warning` \| `violation` | Yes | How serious a breach is. |
| `message` | string | Yes | What the rule means. |
| `remediation` | string | No | How to fix a breach. |
| `expression` | object | Yes | `operator: "property"` with `property_api_name` and any of `min_count`, `max_count`, `pattern` (a regular expression), `allowed_values`; or `all`, `any` (up to 64 `operands`) or `not` (one `operand`). |

## `ontology_interface_type`

| Field | Type | Required | Meaning |
| - | - | - | - |
| `ontology_id` | string | Yes | Owning ontology. |
| `api_name` | string | Yes | Stable name. |
| `required_properties` | array of properties | Yes | Properties every implementing object type must declare with the same data type. |
| `extends` | array of references | No | Parent interfaces: up to 16 direct parents, 16 levels deep, no cycles. |

## `ontology_link_type`

| Field | Type | Required | Meaning |
| - | - | - | - |
| `ontology_id` | string | Yes | Owning ontology. |
| `api_name` | string | Yes | How the link reads from the source, such as `places`. |
| `source` | reference | Yes | An object type or interface. |
| `target` | reference | Yes | An object type or interface. A link to an interface applies to every type that implements it. |
| `source_cardinality` | `one` \| `optional` \| `many` | Yes | How many sources each target has. |
| `target_cardinality` | `one` \| `optional` \| `many` | Yes | How many targets each source has. |
| `inverse_api_name` | string | Yes | How the link reads from the target, such as `placed_by`. Must differ from `api_name`. |
| `properties` | array of properties | No | Properties of the relationship itself, up to 64. |
| `derivation` | [derivation rule](#derivations) | No | When the link exists. |
| `source_iri`, `inverse_source_iri` | string | No | External identities of each direction. |
| `annotations` | object | No | Non-semantic metadata. |

Cardinality values read as **exactly one** (`one`), **at most one** (`optional`) and **many** (`many`). Studio's **Relationship** picker sets both ends: **One to many** is `source_cardinality: one`, `target_cardinality: many`.

## `ontology_shared_property_type`

| Field | Type | Required | Meaning |
| - | - | - | - |
| `ontology_id` | string | Yes | Owning ontology. |
| `api_name` | string | Yes | Stable name, such as `lifecycle_status`. |
| `value_schema` | value schema | Yes | The data type every property that uses it must match exactly. |

## `ontology_action_type`

| Field | Type | Required | Meaning |
| - | - | - | - |
| `ontology_id` | string | Yes | Owning ontology. |
| `api_name` | string | Yes | Stable name, such as `cancel_order`. |
| `target` | reference | Yes | One object type. Interfaces can't be targets. |
| `binding_state` | `unbound` | Yes | Always `unbound`: nothing runs an action type. |
| `parameters` | array of properties | No | Values supplied when the action is used, up to 64. |
| `preconditions` | array | No | Each has `property_api_name`, `operator` (`equals`, `not_equals`, `is_set`, `is_not_set`) and an optional `value`. All must hold. |
| `effects` | array | No | Each has `property_api_name`, `operation` (`set` or `clear`) and an optional `value`. |

## `ontology_concept_scheme`

| Field | Type | Required | Meaning |
| - | - | - | - |
| `ontology_id` | string | Yes | Owning ontology. |
| `api_name` | string | Yes | Stable name. |
| `source_iri` | string | Yes | Canonical IRI, unique in the ontology. |
| `preferred_labels` | array of labels | Yes | At least one, and one per language. |
| `alternative_labels` | array of labels | No | Synonyms and acronyms. |
| `definitions` | array of labels | No | Definitions, per language. |

A label is `{ "value": "Product category", "language": "en" }`. `language` is optional and must be a BCP 47-style tag such as `en` or `fr-CA`.

## `ontology_concept`

| Field | Type | Required | Meaning |
| - | - | - | - |
| `ontology_id` | string | Yes | Owning ontology. |
| `api_name` | string | Yes | Stable name. |
| `source_iri` | string | Yes | Canonical IRI, unique in the ontology. |
| `scheme` | reference | Yes | The concept scheme that owns it. |
| `preferred_labels` | array of labels | Yes | At least one, and one per language. |
| `alternative_labels`, `hidden_labels` | array of labels | No | Synonyms and search-only forms. A label can't appear in more than one role. |
| `definitions`, `scope_notes` | array of labels | No | Meaning and usage notes. |
| `notations` | array | No | Codes, each `{ "value": "...", "datatype_iri": "..." }` with an optional datatype. |
| `broader`, `related` | array of references | No | Other concepts. The broader hierarchy can't form a cycle. |
| `mappings` | array | No | Each `{ "relation": "...", "target_iri": "..." }`. Relations are `exact_match`, `close_match`, `broad_match`, `narrow_match` and `related_match`. |

A concept or scheme holds up to 128 labels in total, and a concept up to 256 semantic relationships. A mapping whose target IRI matches another concept in the same release is followed by context retrieval; an external target is kept but not followed. Scheme membership never expands context.

## Derivations

A derivation is a typed expression that says how a property's value is computed, or when a link exists. Ontology checks it against the whole release graph but never evaluates it. In a binding, a registered transformation is what implements a derived property.

| Field | Type | Required | Meaning |
| - | - | - | - |
| `binding_state` | `unbound` | Yes | Always `unbound`. |
| `expression` | object | Yes | The expression tree, tagged by `kind`. A link rule must be a true-or-false expression; a property rule must produce a value that fits the property. |
| `missing_value_behavior` | `no_match` \| `indeterminate` | No | Default `no_match`: null, empty or malformed inputs don't match. |
| `link_policy` | object | No | Links only: `allow_self_links` (default `false`) and `symmetry` (`auto`, `directed` or `canonical_pair`). |

Expression kinds:

| Group | `kind` values |
| - | - |
| Values | `path`, `literal`, `transform` (`lowercase`, `trim`, `normalize_whitespace`, `normalize_phone`, `normalize_address`, `prefix`, `suffix`, `absolute`), `exclude`, `aggregate` (`count`, `sum`, `average`, `minimum`, `maximum`, `exact_cardinality`, `approximate_cardinality`, `collect_list`, `collect_set`), `custom_function` |
| Logic | `all`, `any`, `not`, `compare` (`equals`, `not_equals`, `less_than`, `less_than_or_equals`, `greater_than`, `greater_than_or_equals`), `presence`, `exists`, `set_compare` (`intersects`, `contains`, `contains_all`), `custom_predicate` |
| Matching | `within_tolerance`, `temporal_proximity`, `interval_overlap`, `geospatial_proximity`, `fuzzy_match` (`levenshtein`, `jaro_winkler`, `token_set`), `frequency_guard`, `reachable` |

A `path` starts at `self_object`, `source` or `target` and follows link steps `outgoing` or `incoming`. A custom function names an exact versioned implementation, never code or a URL.

| Derivation limit | Value |
| - | - |
| Link steps in one path | 3 |
| Hops in `reachable` | 8 |
| Expression depth | 16 levels |
| Expression nodes | 128 |
| Operands in `all` or `any`, and excluded values | 64 |
| Custom-function arguments | 16 |

Links also accept the earlier shape `{ "binding_state": "unbound", "match_mode": "all" | "any", "conditions": [...] }`, where each condition compares a source property with a target property using `equals` or `not_equals`. Studio's **Derived relationship** form writes this shape.

## `ontology_record`

A [Manage knowledge records](/ontology/how-tos/manage-records).

| Field | Type | Required | Meaning |
| - | - | - | - |
| `ontology_id` | string | Yes | Owning ontology. |
| `api_name` | string | Yes | Stable name. |
| `ontology_release` | object | Yes | `ontology_id`, `release_id` (`rel_…`), `version_label` and `manifest_digest` of the release it is locked to. |
| `record_type_artifact_id` | string | Yes | The object type's ID. |
| `record_type` | exact reference | Yes | `kind`, `artifact_id`, `version_ordinal` and `content_hash` of the object type version. |
| `values` | object | Yes | Property name to value. Up to 256 values, 1 MiB encoded. |
| `effective_from` | RFC 3339 timestamp | Yes | Start of the business-valid period, inclusive. |
| `effective_to` | RFC 3339 timestamp | No | End, exclusive. Required for `superseded` and `retired`. Must be later than `effective_from`. |
| `lifecycle_state` | `draft` \| `active` \| `superseded` \| `retired` | Yes | Draft records stay out of record-set releases. |
| `relationships` | array | No | Up to 512. Each has `relationship_type` (exact link type version), `target_record_id`, and an optional `valid_time` inside the record's own. |
| `knowledge_references` | array | No | Up to 64 exact supporting-document versions. |
| `supersedes` | array of record IDs | No | Up to 64 earlier records this one replaces. |

A record set has `ontology_id`, `api_name` and the `ontology_release` it is locked to. Each release of it records the record count, shard checksums and a manifest digest; it holds up to 50,000 records in shards of 500.

## Bindings

The Ontology Binding app adds four kinds. All physical names are qualified-name strings of up to 512 bytes.

| Kind | Key fields |
| - | - |
| `ontology_binding` | `api_name`, `ontology_release` (exact release and digest), `source_scope`, `compatibility_policy` |
| `ontology_object_binding` | `binding_id`, `ontology_object` (exact version), `relation` (a qualified relation, or `mode: query_backed` with a read-only query), `grain` (`description` up to 512 bytes, and `uniqueness`: 1 to 16 logical properties) |
| `ontology_property_binding` | `binding_id`, `object_binding_id`, `ontology_property_api_name`, `implementation` (`field`, or `registered_transformation` with `implementation` and `output_field`) |
| `ontology_link_binding` | `binding_id`, `ontology_link` (exact version), `source_object_binding_id`, `target_object_binding_id`, `join_keys` (up to 16 property-mapping pairs) |

A query-backed relation declares `dialect` (`ansi`, `big_query`, `databricks`, `postgres`, `snowflake`), `sql` (up to 64 KiB), optional `default_catalog` and `default_schema`, `outputs` (up to 256, each `name`, `physical_type`, `nullable`) and `dependencies` (up to 128). One binding release holds up to 5,000 mappings.

## Interchange formats

Import and export go through versioned adapters. `GET /ontology/v1/adapters` lists them.

| `format` | `serialization` | `adapter_version` | `profile` | What it carries |
| - | - | - | - | - |
| `native_json` | `json` | `native-json/1` | None | Every field. Studio calls it **Studio JSON**. |
| `rdf` | `turtle` | `rdf/1` | `rdf-rdfs-supported-subset` | Classes and properties. |
| `owl` | `turtle` | `owl/1` | `owl2-dl-supported-subset` | `owl:Class` to object type, `owl:DatatypeProperty` to property, `owl:ObjectProperty` to link, with inverses. |
| `skos` | `turtle` or `json_ld` | `skos/1` | `skos-core-supported-subset` | Concept schemes and concepts, labels, notations, hierarchy, related concepts and mappings. |

* `rdf`, `owl` and `skos` also need `profile` and a `base_iri`: an absolute `http` or `https` IRI that ends in `/` or `#`, up to 2,048 characters.
* An import document can be at most 8 MiB, and an RDF document at most 100,000 triples. Adapters never fetch remote imports or JSON-LD contexts.
* Every export and import preview returns a report with `lossless`, and counts of `approximations`, `omissions`, `unsupported` parts and `generated_identities`. Derivations survive RDF and OWL only through the native annotation, and the report says so.
* Applying an import creates at most 100 definitions in one all-or-nothing step.

## Release limits

| Bound | Maximum |
| - | - |
| Definitions per release | 256 |
| Complete release schema | 8 MiB of canonical JSON |
| Properties per object type or interface | 256 |
| Properties per link | 64 |
| Action parameters | 64 |
| Interface inheritance | 16 parents, 16 levels |
| Reference depth during validation | 32 |

## Complete example

The retail `customer` object type, as it appears in an import document or Studio's **JSON** view:

```json theme={null}
{
  "ontology_id": "ontology_01example",
  "api_name": "customer",
  "object_kind": "entity",
  "source_iri": "https://example.com/retail#Customer",
  "implements": [],
  "properties": [
    {
      "api_name": "customer_id",
      "is_required": true,
      "is_identifier": true,
      "value_schema": { "kind": "string", "max_length": 64 }
    },
    {
      "api_name": "status",
      "is_required": true,
      "value_schema": { "kind": "string", "enum": ["active", "churned"] }
    },
    {
      "api_name": "home_store",
      "value_schema": {
        "kind": "reference",
        "reference": { "kind": "ontology_object_type", "artifact_id": "ontology_object_type_01store" }
      }
    }
  ],
  "constraints": [
    {
      "api_name": "customer_id_format",
      "severity": "violation",
      "message": "Customer IDs start with C- followed by digits.",
      "expression": { "operator": "property", "property_api_name": "customer_id", "pattern": "^C-[0-9]+$" }
    }
  ]
}
```

## Validation diagnostics

Validation returns diagnostics with `code`, `severity` (`error` or `warning`), `resource`, `path`, `message` and `remediation`, sorted so the same input always gives the same list. Errors block publishing; warnings don't. Common codes:

| Code | Means |
| - | - |
| `invalid_api_name` | An API name breaks the naming rule. |
| `duplicate_property` | Two properties in one owner share an API name. |
| `invalid_identifier` | An identifier isn't required, or isn't a single value. |
| `invalid_value_constraint` | A value schema constraint doesn't fit its kind or range. |
| `shared_property_mismatch` | A property differs from its shared property's data type. |
| `reference_not_found` | A reference names a definition that isn't in the candidate set. |
| `interface_not_implemented` | An object type misses a required property of an interface it implements. |
| `interface_cycle` | Interfaces extend each other in a loop. |
| `missing_source_iri` | Warning: the definition has no IRI, so RDF, OWL and SPARQL can't address it. |
| `graph_limit_exceeded` | A collection or nesting limit is exceeded. |

## Related

* [Ontology concepts](/ontology/concepts): what each kind is for.
* [Publish an ontology through the API](/cookbooks/how-tos/ontology): import, validate and publish these definitions.
* [Public API](/api/references/api-reference): request and response schemas for every operation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.