Read what one module's objects, fields and relationships mean.

GET

/v1/ontology/{moduleKey}

curl --request GET \
  --url 'https://example.com/v1/ontology/example?detail=summary' \
  --header 'Authorization: Bearer <token>'

Authorizations

• bearerAuth

Parameters

Path Parameters

moduleKey

required

string

Module key.

Query Parameters

detail

One of:

string

Keys, labels, descriptions, kinds, types, targets, flags, and relationships – no guidance and no rules. The default.

string

Allowed value: summary

string

Everything summary carries, plus object and field guidance and object rules.

string

Allowed value: full

How much prose to include. Defaults to summary.

Responses

200

The instance ontology: every module, object, field, and relationship this instance defines, with their authored meaning.

The whole-instance form served by GET /v1/ontology; GET /v1/ontology/{moduleKey} returns the same shape with modules containing exactly one entry. Reflects exactly the schema currently serving data traffic.

Media typeapplication/json

The instance ontology: every module, object, field, and relationship this instance defines, with their authored meaning.

The whole-instance form served by GET /v1/ontology; GET /v1/ontology/{moduleKey} returns the same shape with modules containing exactly one entry. Reflects exactly the schema currently serving data traffic.

object

detail

required

How much prose this document carries. Echoes the ?detail query parameter the caller supplied (or its summary default).

One of:

string

Keys, labels, descriptions, kinds, types, targets, flags, and relationships – no guidance and no rules. The default.

string

Allowed value: summary

string

Everything summary carries, plus object and field guidance and object rules.

string

Allowed value: full

modules

required

Every loaded module, sorted by module key. Exactly one entry for the per-module route; every loaded module for the whole-instance route.

Array<object>

One module’s ontology: its own meaning plus every object and relationship it declares.

object

description

Free-text description of the module’s purpose. Absent when the module’s manifest carries none.

string | null

label

required

Human-readable display name for the module.

string

moduleKey

required

Qualified module key, e.g. "core" or "acme.crm".

string

objects

required

Every object declared or synthesized within this module, sorted by object key.

Array<object>

One object’s ontology: its own meaning plus every field it carries.

object

abstract

Whether the object is abstract – it cannot be instantiated directly through the data API.

boolean

description

Free-text description of the object’s purpose. Absent when not authored.

string | null

extends

The fully qualified name of the parent object this object extends, e.g. "core.Party". Absent when the object has no parent.

string | null

fields

required

Every field on this object, sorted by field key.

Array<object>

One field’s ontology entry.

object

description

Free-text description of the field’s purpose. For a RelatedRecords field, this is the owning relationship’s description. Absent when not authored.

string | null

fieldKey

required

The field’s API name within its object, e.g. "email".

string

guidance

Any of:

object

Audience-structured usage guidance for an object or field.

Set on an object definition or on any authorable field kind. Both keys are independently optional, so an author can supply only the one that applies.

Distinct from description: description says what the object or field is; guidance says how to use it. Synthesized fields (managed lookups, RelatedRecords inverses, junction objects) carry no Guidance of their own — the owning relationship’s description is their meaning.

object

authoring

Prose addressed to whoever writes records: conventions, units, when to use this object or field versus another. Absent by default.

string | null

querying

Prose addressed to whoever queries records: what filters and aggregates mean, pitfalls to avoid. Absent by default.

string | null

null

null

kind

required

The shape of this field’s stored or computed value.

One of:

string

A single user-provided value.

string

Allowed value: scalar

string

A read-only value computed from an expression.

string

Allowed value: formula

string

A reference to a record in another object.

string

Allowed value: lookup

string

An aggregate computed across related records.

string

Allowed value: rollup

string

A single logical value made up of several parts.

string

Allowed value: composite

string

The read-only inverse side of a managed lookup relationship.

string

Allowed value: relatedRecords

label

required

Human-readable display name.

string

required

Whether the data API rejects a create/update that omits this field.

boolean

synthesized

Whether this field was generated from a relationship declaration (a managed lookup or a relatedRecords inverse projection) rather than authored directly.

boolean

target

The referenced object, for lookup (the target object, or several comma-separated targets for a multi-target lookup) and relatedRecords (the related child object) fields. Absent for every other kind.

string | null

type

The field’s data type, for kinds that have a single scalar type: scalar (its declared type), formula and rollup (their return type), composite (its composite kind). Absent for lookup and relatedRecords, which carry no single type – see target.

string | null

unique

Whether this field has a UNIQUE constraint.

boolean

guidance

Any of:

object

Audience-structured usage guidance for an object or field.

Set on an object definition or on any authorable field kind. Both keys are independently optional, so an author can supply only the one that applies.

Distinct from description: description says what the object or field is; guidance says how to use it. Synthesized fields (managed lookups, RelatedRecords inverses, junction objects) carry no Guidance of their own — the owning relationship’s description is their meaning.

object

authoring

Prose addressed to whoever writes records: conventions, units, when to use this object or field versus another. Absent by default.

string | null

querying

Prose addressed to whoever queries records: what filters and aggregates mean, pitfalls to avoid. Absent by default.

string | null

null

null

label

required

Human-readable display name for the object type.

string

objectKey

required

The object’s identifier within its module, e.g. "Account".

string

rules

Object-level validation rules, keyed by rule name. Present only under ?detail=full; absent under summary. Omitted entirely when the object declares no rules.

object

key

additional properties

A single entry in an object’s rules: block: a named boolean condition that every record of the object must satisfy.

Carries a human-readable label, a formula expression evaluated as a boolean predicate, and optional fields controlling the violation message and which field an error is attributed to.

object

description

Free-text description of what this rule protects against. Absent by default.

Distinct from message: description explains the rule’s intent to a metadata author; message is shown to the API caller whose write violated it.

string | null

expression

required

The rule’s boolean formula expression, e.g. "score >= 0". See the formula language reference for supported syntax.

Must be non-empty and must evaluate to a boolean. An empty expression, one that fails to compile, or one that evaluates to a non-boolean type each produce a compile-time diagnostic.

string

field

Any of:

string

A validated FieldKey identifier key: camelCase, 1-63 ASCII alphanumeric characters, no underscores.

string

>= 1 characters <= 63 characters /^[a-z][a-zA-Z0-9]*$/

null

null

label

required

Human-readable name for the rule, shown in error displays.

Distinct from the rule’s key in the rules: map — the label may contain spaces and punctuation. Purely informational; not used to identify the rule internally.

string

message

The message shown to the caller when a record violates this rule, e.g. "Score cannot be negative.". Absent by default.

When absent, a generic message derived from label is used instead. When set, this string is returned verbatim in the API error payload.

string | null

synthesized

Whether this object was generated from a relationship declaration (a many-to-many junction table) rather than authored directly.

boolean

relationships

required

Every relationship declared within this module, sorted by relationship key.

Array<object>

One relationship’s ontology entry.

object

cardinality

Any of:

unknown

One of:

string

Exactly one record on each side of the relationship.

string

Allowed value: oneToOne

string

Many records on the from side may reference the same record on the to side.

string

Allowed value: manyToOne

string

Many records on both sides may reference each other.

string

Allowed value: manyToMany

null

null

description

Free-text description of the relationship’s purpose. Absent when not authored.

string | null

from

required

Qualified object name of the source side of the relationship, e.g. "core.Account".

string

label

required

Human-readable label shown in the UI.

string

pick

Any of:

unknown

One of:

string

A record selects exactly one value from the set.

string

Allowed value: one

string

A record may select any number of values from the set.

string

Allowed value: many

null

null

relationshipKey

required

Unique key for this relationship within its module.

string

to

required

The relationship’s target: a single object, multiple objects, or a closed value set.

object

Any of:

string

string

Array<string>

Array<string>

>= 1 items

object

object

values

required

Array<string>

>= 1 items

requireDescriptions

Whether this module’s ontology posture requires every entity it declares to carry a description. true for core; false for any module that has not opted in.

boolean

sourceTreeHash

required

SHA-256 hex digest of the applied metadata this document was projected from. Two ontology reads carrying the same hash reflect identical applied metadata.

string

Example

{
  "detail": "summary",
  "modules": [
    {
      "objects": [
        {
          "fields": [
            {
              "kind": "scalar"
            }
          ]
        }
      ],
      "relationships": [
        {
          "cardinality": "oneToOne",
          "pick": "one"
        }
      ]
    }
  ]
}

default

Structured error envelope (SPEC-DATA-0006): {"errors": [{"domain", "scope", "target", "code", "message"}, ...]}. domain (added #950 D9) names the subsystem that produced the entry (data, metadata, apply, git, auth, iam, hfx, or api for a transport-level failure with no domain error behind it) and is always present.

Media typeapplication/json

The top-level response body. Wraps a non-empty list of [ErrorEntry].

object

errors

required

The error entries making up the envelope. Always non-empty.

Array<object>

One entry in the error envelope.

Carries a [Domain] naming the subsystem that produced it, an anchoring [ErrorScope], an optional target that disambiguates within the scope, a stable SCREAMING_SNAKE_CASE code, and a human-readable English message. See SPEC-DATA-0006 for the full envelope contract.

object

code

required

Machine-readable, stable, SCREAMING_SNAKE_CASE identifier.

string

domain

required

Which subsystem produced this entry. Always serialized.

One of:

string

data::error::DataError – record CRUD, validation, queries.

string

Allowed value: data

string

server::routes::metadata::error::MetadataError – the metadata write API (module/object/field/screen PUT and POST).

string

Allowed value: metadata

string

server::apply::ApplyError – the metadata apply/plan pipeline.

string

Allowed value: apply

string

server::git::GitError – the git-backed metadata repository.

string

Allowed value: git

string

auth::error::AuthError – JWT and credential authentication.

string

Allowed value: auth

string

server::routes::iam::error::IamError – principal and credential management (IAM handlers still emit Domain::Data for genuine request-body field validation, which stays DataError).

string

Allowed value: iam

string

server::routes::hfx::error::HfxError – HFX parse/emit.

string

Allowed value: hfx

string

Module packages (.hfmod, #1165): package format, signature and compatibility refusals, and the install lifecycle that consumes them.

string

Allowed value: module

string

A transport-level ApiError built directly (forbidden, not_found, internal, service_unavailable), with no <Domain>Error behind it.

string

Allowed value: api

location

Any of:

object

HFX source location for an HFX_PARSE entry.

Emitted as the extra location field on the entry JSON when present. The line/column are 1-based. The frame is the offending source line extracted verbatim from the input.

object

column

required

1-based column within the line, measured in UTF-16 code units of the prefix so browser-side editors can consume it directly.

integer format: uint32

frame

The offending source line text, when available.

string | null

line

required

1-based line number within the source text.

integer format: uint32

null

null

message

required

Server-authored English message. Not part of the API contract; may change across releases without notice.

string

rule

The key of the validation rule that failed, when the code is RULE_FAILED. None for all other codes. Skipped during serialization when absent so it does not appear on unrelated entries (same pattern as location).

string | null

scope

required

Anchoring category. Drives client-side rendering.

One of:

string

Attached to a specific request field. target is the field key.

string

Allowed value: field

string

Attached to the record being written or read. target is the id if known.

string

Allowed value: record

string

Attached to the request as a whole. target is always null.

string

Allowed value: global

target

Field key for field scope, record id for record scope, null otherwise. Always serialized, even when null.

string | null

Example

{
  "errors": [
    {
      "domain": "data",
      "scope": "field"
    }
  ]
}