Auto Ontology management and modeling
Purpose
Inspect and change Auto Ontology's semantic layer without confusing a successful API call
with correct business meaning or durable publication. The machine-readable
inputs, outputs, statuses, gates, and handoffs are in
runtime-contract.yaml.
Choose the focused workflow before acting:
- routine inspection or metadata edits: continue below and use
write-api.md;
- concepts, relationships, measures, units, grain, or policies: use
modeling.md;
- model promotion or reusable analytical results: use
publication.md.
MCP tools only read. Create, patch, import, and compile-reset go through
the Next.js /api/... gateway. Governed result rows require an approved source
writer; Auto Ontology has no generic result-row writeback endpoint. Request bodies and
field types live in docs/openapi/auto-ontology-api.json; this skill names operations and
permissions only.
Prerequisites
Use a running, authenticated Auto Ontology deployment. Use nvidia-ontology-setup when
the deployment or semantic layer is not ready.
Limitations
MCP is read-only, Auto Ontology has no generic result-row writeback endpoint, and current
model import and certification APIs do not prove atomic promotion. Follow the
publication gates below and fail closed when exact readback is unavailable.
Auth
Scripts use an API token (x-api-key or Authorization: Bearer). Mint it in
the UI (user menu → API Tokens). A token acts as its owner — a viewer's
token cannot do admin things. Creating and revoking tokens requires a signed-in
session; a token cannot mint another token.
Writes below need catalog:edit unless noted. 403 means the owner's role
lacks that permission, not that the path is wrong.
Instructions
- Discover current meaning via MCP (
search_terms, get_term,
get_term_columns, get_term_sql_attributes, describe_table) or REST
if MCP is absent (GET /api/terms, GET /api/terms/{term_id},
GET /api/exploration/tables/{table_id}/details).
- Resolve the semantic contract when meaning changes. Record source
binding, identity, population, relationship cardinality, measure expression,
unit, grain, denominator, time, validity, and counterexamples; see
modeling.md.
- State the proposed change to the user (term rename, new SQL attribute,
import, and so on). Do not silently rewrite the glossary.
- Validate SQL before create/update:
POST /api/sql-attributes/validate.
A parse failure is HTTP 422, not valid: false.
- Apply the smallest write that matches the request (see
write-api.md).
- Compilation is not a hidden side effect. Check
GET /api/semantic-compilation/status. Do not call
POST /api/semantic-compilation/reset as cleanup — it is an asynchronous,
destructive rebuild of every database's compiled layer, returns 202, and
requires semanticCompilation:manage.
- Verify the persisted change, not merely request success. Model imports
require a scoped backup and exact re-export comparison; see
publication.md. Then use MCP
check_answerable / ask_question (or REST
POST /api/question-entity-coverage and POST /api/chat/completions) for
positive and negative behavior checks.
Semantic relationships and "what does this dataset mean"
Stay on the semantic layer. Do not browse raw schemas to answer meaning.
- Term → columns: MCP
get_term_columns or
GET /api/terms/{term_id}/column-attributes
- Term → derived SQL: MCP
get_term_sql_attributes
- Table → terms and SQL attributes: MCP
describe_table or
GET /api/exploration/tables/{table_id}/details
- Semantic hop chain between two terms:
GET /api/exploration/terms/{term_id}/path/{other_term_id}
- Semantic graphs:
GET /api/exploration/graph,
GET /api/exploration/semantic-graph
These are semantic relationship paths, not generation provenance, source
revision, certification history, or version lineage.
Bulk import / export
POST /api/model/export — YAML of catalog + semantic layer.
Permission modelInterchange:export. Body may set catalog database IDs
in databases (empty = all) and format (auto_ontology or ossie).
POST /api/model/import — multipart YAML; native Auto Ontology
(data_layer / semantic_layer) or Apache Ossie (version, name,
datasets at the root).
Query replace (default true) and embed (default true). Permission
modelInterchange:import. Can replace existing data — confirm with the
user before replace=true, apply first in isolation, and use the exact
readback workflow in publication.md.
Examples
- To define a run-grain measure, follow the evidence and counterexample workflow
in modeling.md.
- To revise and promote a model, back up the exact scope and follow the staged
readback workflow in publication.md.
Troubleshooting
For write failures, verify the authenticated owner's permission, distinguish
HTTP 422 parse failures from validation results, and inspect compilation status
before changing the model or resetting compilation.
See also
- write-api.md
- modeling.md
- publication.md
nvidia-ontology-query — how to call Auto Ontology and validate query results
nvidia-ontology-setup — deployment not ready
mcp/auto_ontology_mcp/tools.py — live read-tool allow-list
1---2name: nvidia-ontology-management3description: >-4 Model and publish semantic definitions in Auto Ontology. Use for terms, relationships,5 measures, imports, and governed results—not deployment or querying.6license: Apache-2.07metadata:8 source: https://skillmd.com/skills/nvidia/nvidia-ontology-management9 version: "0.2.1"10 author: "NVIDIA <opensource@nvidia.com>"11 tags:12 - nvidia-ontology13 - ontology14 - glossary15 - sql-attributes16 - catalog17---1819<!--20SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.21All rights reserved.22SPDX-License-Identifier: Apache-2.023-->2425# Auto Ontology management and modeling2627## Purpose2829Inspect and change Auto Ontology's semantic layer without confusing a successful API call30with correct business meaning or durable publication. The machine-readable31inputs, outputs, statuses, gates, and handoffs are in32[runtime-contract.yaml](assets/runtime-contract.yaml).3334Choose the focused workflow before acting:3536- routine inspection or metadata edits: continue below and use37 [write-api.md](references/write-api.md);38- concepts, relationships, measures, units, grain, or policies: use39 [modeling.md](references/modeling.md);40- model promotion or reusable analytical results: use41 [publication.md](references/publication.md).4243MCP tools only **read**. Create, patch, import, and compile-reset go through44the Next.js `/api/...` gateway. Governed result rows require an approved source45writer; Auto Ontology has no generic result-row writeback endpoint. Request bodies and46field types live in `docs/openapi/auto-ontology-api.json`; this skill names operations and47permissions only.4849## Prerequisites5051Use a running, authenticated Auto Ontology deployment. Use `nvidia-ontology-setup` when52the deployment or semantic layer is not ready.5354## Limitations5556MCP is read-only, Auto Ontology has no generic result-row writeback endpoint, and current57model import and certification APIs do not prove atomic promotion. Follow the58publication gates below and fail closed when exact readback is unavailable.5960## Auth6162Scripts use an API token (`x-api-key` or `Authorization: Bearer`). Mint it in63the UI (user menu → API Tokens). A token **acts as its owner** — a viewer's64token cannot do admin things. Creating and revoking tokens requires a signed-in65session; a token cannot mint another token.6667Writes below need `catalog:edit` unless noted. `403` means the owner's role68lacks that permission, not that the path is wrong.6970## Instructions71721. **Discover current meaning** via MCP (`search_terms`, `get_term`,73 `get_term_columns`, `get_term_sql_attributes`, `describe_table`) or REST74 if MCP is absent (`GET /api/terms`, `GET /api/terms/{term_id}`,75 `GET /api/exploration/tables/{table_id}/details`).762. **Resolve the semantic contract** when meaning changes. Record source77 binding, identity, population, relationship cardinality, measure expression,78 unit, grain, denominator, time, validity, and counterexamples; see79 [modeling.md](references/modeling.md).803. **State the proposed change** to the user (term rename, new SQL attribute,81 import, and so on). Do not silently rewrite the glossary.824. **Validate SQL** before create/update: `POST /api/sql-attributes/validate`.83 A parse failure is **HTTP 422**, not `valid: false`.845. **Apply** the smallest write that matches the request (see85 [write-api.md](references/write-api.md)).866. **Compilation is not a hidden side effect.** Check87 `GET /api/semantic-compilation/status`. Do **not** call88 `POST /api/semantic-compilation/reset` as cleanup — it is an asynchronous,89 destructive rebuild of every database's compiled layer, returns 202, and90 requires `semanticCompilation:manage`.917. **Verify the persisted change**, not merely request success. Model imports92 require a scoped backup and exact re-export comparison; see93 [publication.md](references/publication.md). Then use MCP94 `check_answerable` / `ask_question` (or REST95 `POST /api/question-entity-coverage` and `POST /api/chat/completions`) for96 positive and negative behavior checks.9798## Semantic relationships and "what does this dataset mean"99100Stay on the semantic layer. Do not browse raw schemas to answer meaning.101102- Term → columns: MCP `get_term_columns` or103 `GET /api/terms/{term_id}/column-attributes`104- Term → derived SQL: MCP `get_term_sql_attributes`105- Table → terms and SQL attributes: MCP `describe_table` or106 `GET /api/exploration/tables/{table_id}/details`107- Semantic hop chain between two terms:108 `GET /api/exploration/terms/{term_id}/path/{other_term_id}`109- Semantic graphs: `GET /api/exploration/graph`,110 `GET /api/exploration/semantic-graph`111112These are semantic relationship paths, not generation provenance, source113revision, certification history, or version lineage.114115## Bulk import / export116117- `POST /api/model/export` — YAML of catalog + semantic layer.118 Permission `modelInterchange:export`. Body may set catalog database **IDs**119 in `databases` (empty = all) and `format` (`auto_ontology` or `ossie`).120- `POST /api/model/import` — multipart YAML; native Auto Ontology121 (`data_layer` / `semantic_layer`) or Apache Ossie (`version`, `name`,122 `datasets` at the root).123 Query `replace` (default true) and `embed` (default true). Permission124 `modelInterchange:import`. Can replace existing data — confirm with the125 user before `replace=true`, apply first in isolation, and use the exact126 readback workflow in [publication.md](references/publication.md).127128## Examples129130- To define a run-grain measure, follow the evidence and counterexample workflow131 in [modeling.md](references/modeling.md).132- To revise and promote a model, back up the exact scope and follow the staged133 readback workflow in [publication.md](references/publication.md).134135## Troubleshooting136137For write failures, verify the authenticated owner's permission, distinguish138HTTP 422 parse failures from validation results, and inspect compilation status139before changing the model or resetting compilation.140141## See also142143- [write-api.md](references/write-api.md)144- [modeling.md](references/modeling.md)145- [publication.md](references/publication.md)146- `nvidia-ontology-query` — how to call Auto Ontology and validate query results147- `nvidia-ontology-setup` — deployment not ready148- `mcp/auto_ontology_mcp/tools.py` — live read-tool allow-list