Read the ontology of a running instance

Goal

Read what a running Henceforth instance’s modules, objects, fields, and relationships actually mean — their labels, descriptions, kinds, types, targets, and (on request) authoring/querying guidance — as one document, from hf ontology or GET /v1/ontology.

Prerequisites

A running Henceforth server and its URL, or the hf CLI logged in to a target (see Manage metadata with the hf CLI).
Permissions, depending on which read you make:
- The whole-instance read (hf ontology with no module, GET /v1/ontology) requires admin.metadata.module.read, admin.metadata.object.read, admin.metadata.field.read, and admin.metadata.relationship.read, all held unscoped (a grant scoped to one module does not satisfy this read).
- The per-module read (hf ontology <moduleKey>, GET /v1/ontology/{moduleKey}) requires the same four actions scoped to that module (field read scoped to each of its objects, {moduleKey}.{objectKey}).
- Missing any one of these answers 403 FORBIDDEN — the route is gated, not filtered: it never returns a partial document for a principal that fails part of the check.

Steps

1. Read the whole instance

hf ontology

Lists every loaded module, each with its objects (labels, descriptions, fields) and relationships. Add -t <target> to point at a target other than the current one, as with any other hf remote verb.

2. Read one module

hf ontology core

Returns the same document shape with exactly one module. Reading a module you cannot see returns 403, whether or not that module exists.

3. Ask for guidance and validation rules

hf ontology core --full

By default (summary), the document carries keys, labels, descriptions, kinds, types, targets, flags, and relationships. --full additionally includes each object’s and field’s guidance (separate authoring and querying prose) and each object’s validation rules.

4. Read it over HTTP directly

curl -H "Authorization: Bearer $TOKEN" \
  "https://your-server/v1/ontology?detail=full"

?detail=summary (the default) or ?detail=full control the same distinction --full does above; curl .../v1/ontology/core?detail=full is the per-module equivalent. Every response from the ontology routes carries Cache-Control: private, no-cache.

5. Print the raw response

hf ontology --json

--json prints the server’s response body verbatim (the same OntologyDocument shape curl would receive) instead of the human-readable outline — useful for piping into jq or another tool.

Verification

Compare sourceTreeHash across two reads: hf ontology --json | jq .sourceTreeHash returns the same value on every call between one apply and the next. Two ontology reads carrying the same hash reflect identical applied metadata.

Notes

Screens are not part of the ontology (they are a presentation concern); the object, field, and relationship shapes described here are the whole of it.