Publish bindings through API

Preview An ontology binding maps one immutable ontology release to the tables, views, fields, transformations, governed joins, or read-only SQL-backed relations that implement it, so an agent gets logical definitions and their physical names together. Use this recipe after you Publish an ontology through the API, when agents need to know where each concept lives in your data. If you already have a portable binding document, skip to Import portable binding (optional) to create the binding in one transaction.

Before you begin

Before you start, make sure you have:

Extensions: An administrator has installed the Ontology extension, which includes bindings. Until then, these routes, artifact kinds, Studio pages, and MCP tools are not available.
Ontology release: A published ontology release, with its ID, release number, and manifest digest. Core Registry release IDs use the rel_... form.
Credentials: ATLAN_GATEWAY_URL and ATLAN_TOKEN in your environment, from an approved secret store. See Send bearer token.

Set the release values in your shell:

export WORKSPACE_ID="workspace_01example"
export ONTOLOGY_ID="ontology_01example"
export ONTOLOGY_RELEASE_ID="rel_01example"
export ONTOLOGY_RELEASE="1.0.0"
export ONTOLOGY_MANIFEST_DIGEST="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

The extension validates and versions what you declare. It does not connect to a source, check that a physical name exists, store credentials, generate executable SQL, or run a query. The examples use Snowflake names, but qualified names are source-neutral strings. The steps follow this lifecycle:

ontology release -> binding drafts -> validation -> binding release -> bounded agent context

Create binding and mappings

Open Ontology Studio, select an ontology with a published release, then choose Data bindings:

Choose New binding. If the ontology has more than one release, the dialog asks for the Ontology release to lock the binding to; otherwise Studio locks it to the latest release. A binding family records that exact logical release, a physical source scope, and its Versioning policy: Any change allowed (none), Backward compatible (backward_compatible, the default), or Fully compatible (full_compatible). Choose Create binding to save it.
Studio opens the binding family’s own page. On its Mappings tab, choose Map object, Map property, and Map link to add mappings.

Each mapping declares one part of the physical model:

Mapping	Declares
Object	One exact logical object version, its physical relation, and its row grain. A qualified name such as `analytics.sales.customers` is governed metadata; the extension does not look it up in Snowflake.
Property	A logical property and the field that holds it, or a registered transformation and its output field. When the property carries a derivation, a field mapping alone does not implement it: a registered transformation is the declared implementation, and source verification and evaluation stay external.
Link	Two object mappings, joined through one or more governed property-mapping pairs. A derivation on a link type is not implemented by its join keys, and derived-link predicates are not evaluated.

Studio shows the binding family’s API name and ID under its name. Copy it into your shell:

export BINDING_ID="ontology_binding_01example"

Saving a mapping appends a draft version. Existing releases stay pinned to the versions they published.If you already have a portable binding document, choose Import binding JSON on Data bindings instead. Studio previews the document against the selected ontology release, and applying a valid preview creates the binding family and all its mappings as drafts and opens the imported family’s page. To do the same through the API, see Import portable binding (optional). You still validate and publish an imported binding.To draft a binding against a model that has no published release yet, use the native draft flow instead: POST /ontology/v1/native-drafts/preview previews separate binding drafts (and Knowledge Record drafts in the same package) pinned to the exact unpublished model, and POST /ontology/v1/native-drafts/draft-saves saves them all-or-nothing with a direct human approval. Publishing the binding then waits for the model’s release, as in Draft cannot be published or activated.

Declare SQL-backed relation (optional)

Use a query-backed relation when a bounded read-only query, rather than one table or view, implements the logical object. In Studio, choose SQL-backed virtual relation for the object mapping. In portable binding JSON, the object mapping’s relation takes this form:

{
  "mode": "query_backed",
  "query": {
    "dialect": "snowflake",
    "sql": "SELECT customer_id, status FROM analytics.sales.customers WHERE is_deleted = FALSE",
    "default_catalog": "analytics",
    "default_schema": "sales",
    "outputs": [
      {"name": "customer_id", "physical_type": "VARCHAR", "nullable": false},
      {"name": "status", "physical_type": "VARCHAR", "nullable": true}
    ],
    "dependencies": [
      {"kind": "relation", "qualified_name": "analytics.sales.customers"}
    ]
  }
}

Supported dialects are ansi, big_query, databricks, postgres, and snowflake. The extension parses and versions the declaration; the calling agent or query gateway runs it with customer-controlled credentials.

Validate and publish binding release

Validate and publish the binding in Ontology Studio:

On Data bindings, open the binding family’s page.
Choose its Publish tab.
Choose Validate mapping. Validation checks that the mappings resolve, the logical endpoints agree, and joined logical property types are compatible.
Enter a release such as 1.0.0, then choose Publish binding release. The release must be a semantic version greater than the binding’s latest release, and under any policy except Any change allowed, a breaking change needs a greater major version. Studio fills in a suggested version, and the button stays disabled until validation passes and the version has the form major.minor.patch. Publishing a label that already exists with different content is refused with release_label_conflict.

The family’s Releases tab lists its published releases, newest first, each with its version, the ontology release it is locked to, its state (Current, Superseded, or Withdrawn), and who published it and when.Studio sends the exact root and mapping versions to POST /ontology/v1/bindings/validations and POST /ontology/v1/bindings/releases. Read the published release ID back through the API:

BINDING_RELEASE_ID=$(curl -sS --fail-with-body \
  "${ATLAN_GATEWAY_URL}/ontology/v1/bindings/${BINDING_ID}/releases?limit=50&offset=0" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" | \
  jq -r '.items[] | select(.release == "1.0.0") | .id')

Publication appends an immutable snapshot to the binding root and releases that exact version through Core Registry.

Verify binding context

Retrieve bounded context from the binding release:

curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/bindings/context-queries" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg binding_id "${BINDING_ID}" \
    --arg release_id "${BINDING_RELEASE_ID}" \
    '{
      binding_id: $binding_id,
      release_id: $release_id,
      query: "customer status and support cases",
      max_resources: 12,
      max_depth: 2,
      max_tokens: 4000,
      diagnostics: true
    }')" | jq

The response pairs logical definitions with their released physical mappings. An MCP client reaches the same read-only operation as extension__ontology__get_binding_context. Pass ontology_release_id to test reuse against a newer release of the same ontology; reuse succeeds only when every referenced logical resource keeps its exact version and content hash. If it does not, see Newer ontology release does not reuse binding.Pass logical_resource_ids with the logical resources the question depends on to get their declaration coverage even when the query text would not select them, then read the response’s handoff report. It lists missing declarations, such as an unmapped object or property or a link with no governed join, with the artifact ID, the property where relevant, and a remediation. The report covers declarations only; it never claims that warehouse execution is safe.In Ontology Studio, the Ask tab of the Agent context page shows the same released context as one card per mapped definition: the logical definition, its declared physical source, grain, columns, and joins, exactly as published. The results header shows the exact binding and ontology release IDs and the release checksum. Results can show the logical model and its data bindings together, grouped under Logical model and Data bindings. Then:

Mapping handoff: The binding results can include this card for exactly the logical definitions the question returned. It lists each blocker with its code, affected definition or property, and remediation, and each derivation with a status of mapped declaration, unbound, or unsupported and the reason. Warehouse existence, join cardinality, and execution are not verified, and when coverage is partial the card says so.
Release check: A combined answer stays on the selected release. Studio refuses a logical reply that names a different release, and a binding reply that does not match the selected binding, logical release, or the logical reply’s manifest digest, and reports it as an error.
Supporting evidence: Under Supporting knowledge records, turn on Include released evidence, choose a Record set and its Exact record-set release (only releases pinned to the selected ontology release are offered), and set Valid as of. Evidence keyword (optional) narrows the records; leaving it empty returns a bounded inventory. Matching records appear under Supporting knowledge evidence with their lifecycle state, effective dates, version, content hash, governed values, relationships, and supporting documents. Evidence supports an explanation; it does not prove causation or override the logical model. If evidence retrieval is unavailable, Studio reports the error and keeps the logical and binding results.

Before handing the binding release to an agent, confirm that:

Both the ontology and binding release IDs are exact rel_... handles.
Validation returned is_valid: true for the versions you published.
The binding response carries both manifest digests.
Qualified physical names and SQL declarations contain no credentials.
The calling agent or executor uses a separately governed source connection.

List or read the release later through:

GET /ontology/v1/bindings/{binding_id}/releases
GET /ontology/v1/bindings/{binding_id}/releases/{release_id}/schema
GET /registry/v1/artifacts/ontology_binding/{binding_id}/releases/latest

Export portable binding (optional)

Export one exact binding release as deterministic, credential-free JSON, for example to recreate it in another workspace:

PORTABLE_EXPORT=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/bindings/exports" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg binding_id "${BINDING_ID}" \
    --arg release_id "${BINDING_RELEASE_ID}" \
    '{binding_id: $binding_id, release_id: $release_id}')")

jq '{format, document_digest, binding_manifest_digest}' <<<"${PORTABLE_EXPORT}"

The document uses logical API names rather than environment-specific artifact IDs. It contains physical declarations, but no credentials or source data. A release with legacy artifact-based physical references cannot be exported this way; see Portable binding export refused.

Import portable binding (optional)

Preview a portable document against one exact destination ontology release:

IMPORT_PREVIEW_REQUEST=$(jq -n \
  --arg document "$(jq -r '.document' <<<"${PORTABLE_EXPORT}")" \
  --arg ontology_id "${ONTOLOGY_ID}" \
  --arg release_id "${ONTOLOGY_RELEASE_ID}" \
  --arg release "${ONTOLOGY_RELEASE}" \
  --arg digest "${ONTOLOGY_MANIFEST_DIGEST}" \
  --arg workspace_id "${WORKSPACE_ID}" \
  '{
    document: $document,
    ontology_release: {
      ontology_id: $ontology_id,
      release_id: $release_id,
      release: $release,
      manifest_digest: $digest
    },
    workspace_id: $workspace_id,
    binding_api_name: "customer_360_imported",
    display_name: "Customer 360 imported"
  }')

IMPORT_PREVIEW=$(curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/bindings/imports/preview" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "${IMPORT_PREVIEW_REQUEST}")

jq '{preview_id, is_valid, diagnostics, object_count, property_count, link_count}' \
  <<<"${IMPORT_PREVIEW}"

Apply the unchanged valid preview:

curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/ontology/v1/bindings/imports/apply" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -H "Content-Type: application/json" \
  --data "$(jq \
    --arg preview_id "$(jq -r '.preview_id' <<<"${IMPORT_PREVIEW}")" \
    '. + {preview_id: $preview_id}' <<<"${IMPORT_PREVIEW_REQUEST}")" | \
  jq '{binding_id, created_count}'

Apply recomputes the preview and creates the binding root and every mapping in one Registry transaction, and its response returns the new binding_id. It creates drafts and does not publish a binding release, so validate and publish the imported binding as in Validate and publish binding release. Preview and apply never contact a physical source.

Archive mapping or binding family

Open a binding family from Data bindings to archive the drafts it no longer needs. Nothing is deleted:

Archive mapping: Open a mapping and choose Archive mapping to remove it from the family’s drafts and from the next binding release. Published binding releases keep the version they are locked to. When other mappings refer to the one you archive, Studio names them, and validation reports them until you edit or archive them.
Archive family: Choose Archive family on the binding family’s page to archive the family and all its draft mappings. The family disappears from Data bindings for everyone in the workspace. Studio asks you to type the family’s API name to confirm.

Troubleshooting

If the extensions are not available, a binding export is refused, or a binding does not carry over to a newer ontology release, see Ontology errors.

Next steps

Get bounded ontology-binding context: Give an agent bounded logical definitions and released physical mappings through MCP.

Register and manage agents

Give agents business context

Observe agent runs

Evaluate and improve agents

Track agent cost

Publish bindings through API

Before you begin

Archive mapping or binding family

Troubleshooting

Next steps

See also