Ontology data model

Preview 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.

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`

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	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	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	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	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	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.

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:

{
  "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.

Ontology concepts: what each kind is for.
Publish an ontology through the API: import, validate and publish these definitions.
Public API: request and response schemas for every operation.

Skill management

Agent management

AI Gateway

Metrics Studio

Ontology

Common rules

`ontology`

`ontology_object_type`

Property

Value schema

Constraint

`ontology_interface_type`

`ontology_link_type`

`ontology_shared_property_type`

`ontology_action_type`

`ontology_concept_scheme`

`ontology_concept`

Derivations

`ontology_record`

Bindings

Interchange formats

Release limits

Complete example

Validation diagnostics

​Common rules

​ontology

​ontology_object_type

​Property

​Value schema

​Constraint

​ontology_interface_type

​ontology_link_type

​ontology_shared_property_type

​ontology_action_type

​ontology_concept_scheme

​ontology_concept

​Derivations

​ontology_record

​Bindings

​Interchange formats

​Release limits

​Complete example

​Validation diagnostics

​Related

Common rules

`ontology`

`ontology_object_type`

Property

Value schema

Constraint

`ontology_interface_type`

`ontology_link_type`

`ontology_shared_property_type`

`ontology_action_type`

`ontology_concept_scheme`

`ontology_concept`

Derivations

`ontology_record`

Bindings

Interchange formats

Release limits

Complete example

Validation diagnostics

Related