Read what every module, object, field and relationship of this instance means.
const url = 'https://example.com/v1/ontology?detail=summary';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/v1/ontology?detail=summary' \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters”Responses
Section titled “ Responses ”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.
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
How much prose this document carries. Echoes the ?detail query
parameter the caller supplied (or its summary default).
Keys, labels, descriptions, kinds, types, targets, flags, and
relationships – no guidance and no rules. The default.
Everything summary carries, plus object and field guidance and
object rules.
Every loaded module, sorted by module key. Exactly one entry for the per-module route; every loaded module for the whole-instance route.
One module’s ontology: its own meaning plus every object and relationship it declares.
object
Free-text description of the module’s purpose. Absent when the module’s manifest carries none.
Human-readable display name for the module.
Qualified module key, e.g. "core" or "acme.crm".
Every object declared or synthesized within this module, sorted by object key.
One object’s ontology: its own meaning plus every field it carries.
object
Whether the object is abstract – it cannot be instantiated directly through the data API.
Free-text description of the object’s purpose. Absent when not authored.
The fully qualified name of the parent object this object extends,
e.g. "core.Party". Absent when the object has no parent.
Every field on this object, sorted by field key.
One field’s ontology entry.
object
Free-text description of the field’s purpose. For a RelatedRecords
field, this is the owning relationship’s description. Absent when
not authored.
The field’s API name within its object, e.g. "email".
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
Prose addressed to whoever writes records: conventions, units, when to use this object or field versus another. Absent by default.
Prose addressed to whoever queries records: what filters and aggregates mean, pitfalls to avoid. Absent by default.
The shape of this field’s stored or computed value.
A single user-provided value.
A read-only value computed from an expression.
A reference to a record in another object.
An aggregate computed across related records.
A single logical value made up of several parts.
The read-only inverse side of a managed lookup relationship.
Human-readable display name.
Whether the data API rejects a create/update that omits this field.
Whether this field was generated from a relationship declaration (a
managed lookup or a relatedRecords inverse projection) rather
than authored directly.
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.
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.
Whether this field has a UNIQUE constraint.
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
Prose addressed to whoever writes records: conventions, units, when to use this object or field versus another. Absent by default.
Prose addressed to whoever queries records: what filters and aggregates mean, pitfalls to avoid. Absent by default.
Human-readable display name for the object type.
The object’s identifier within its module, e.g. "Account".
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
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
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.
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.
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.
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.
Whether this object was generated from a relationship declaration (a many-to-many junction table) rather than authored directly.
Every relationship declared within this module, sorted by relationship key.
One relationship’s ontology entry.
object
Free-text description of the relationship’s purpose. Absent when not authored.
Qualified object name of the source side of the relationship, e.g.
"core.Account".
Human-readable label shown in the UI.
Unique key for this relationship within its module.
The relationship’s target: a single object, multiple objects, or a closed value set.
object
object
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.
SHA-256 hex digest of the applied metadata this document was projected from. Two ontology reads carrying the same hash reflect identical applied metadata.
Example
{ "detail": "summary", "modules": [ { "objects": [ { "fields": [ { "kind": "scalar" } ] } ], "relationships": [ { "cardinality": "oneToOne", "pick": "one" } ] } ]}default
Section titled “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.
The top-level response body. Wraps a non-empty list of [ErrorEntry].
object
The error entries making up the envelope. Always non-empty.
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
Machine-readable, stable, SCREAMING_SNAKE_CASE identifier.
Which subsystem produced this entry. Always serialized.
data::error::DataError – record CRUD, validation, queries.
server::routes::metadata::error::MetadataError – the metadata
write API (module/object/field/screen PUT and POST).
server::apply::ApplyError – the metadata apply/plan pipeline.
server::git::GitError – the git-backed metadata repository.
auth::error::AuthError – JWT and credential authentication.
server::routes::iam::error::IamError – principal and credential
management (IAM handlers still emit Domain::Data for genuine
request-body field validation, which stays DataError).
server::routes::hfx::error::HfxError – HFX parse/emit.
Module packages (.hfmod, #1165): package format, signature and
compatibility refusals, and the install lifecycle that consumes them.
A transport-level ApiError built directly (forbidden,
not_found, internal, service_unavailable), with no
<Domain>Error behind it.
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
1-based column within the line, measured in UTF-16 code units of the prefix so browser-side editors can consume it directly.
The offending source line text, when available.
1-based line number within the source text.
Server-authored English message. Not part of the API contract; may change across releases without notice.
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).
Field key for field scope, record id for record scope, null
otherwise. Always serialized, even when null.
Example
{ "errors": [ { "domain": "data", "scope": "field" } ]}