> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open-metadata.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Author the Ontology (Edit Mode) | OpenMetadata
> Draw typed relations, add attributes and OWL axioms, apply modeling patterns, build subsets, merge structures, and preview delete impact — safely, behind an editing lease.
# Author — Edit Mode
Edit mode turns the studio into an authoring workspace. It has two surfaces: **Graph**, for direct manipulation of concepts and relations, and **Model**, a workbench of structured modeling tools.
Edit mode appears only if you hold `EditAll`, `EditGlossaryTerms`, or `EditEntityRelationship` on Glossary — or you are an admin.
## The Editing Lease
Ontology edits are structural: one person retyping a relation while another deletes its target produces a model neither of them intended. OpenMetadata guards this with a **lease** rather than a lock you can forget to release.
* Entering Edit mode acquires a lease on the selected glossary.
* The lease is short — the UI takes **60 seconds** and renews it on a heartbeat while you are working. The server accepts leases between 10 and 300 seconds.
* The lease status is shown in the sub-mode bar with a retry action.
* If someone else holds the lease you can still read the model; you cannot write to it.
* Abandoning the tab lets the lease expire on its own, leaving no stuck lock to clear.
API: `POST /api/v1/ontologyEditLocks/acquire`, `PUT /api/v1/ontologyEditLocks/renew`, `GET|DELETE /api/v1/ontologyEditLocks/{resourceType}/{resourceId}`.
## Graph Authoring
With the lease held, the graph canvas becomes editable and the sub-mode bar gains an **Add Concept** action plus an **Edit · Active** lease indicator. Each concept node grows a **+** handle you drag to draw a relation.
* **Add concept** — new concepts are created in the glossary you have selected.
* **Draw a relation** — connect two concepts and pick the relationship type. Cross-glossary edges are only offered for types where `crossGlossaryAllowed` is set.
* **Retype or remove a relation** — select an edge and change its type or delete it.
* **Inspect and edit** — the authoring inspector edits everything that hangs off a concept.
### The Authoring Inspector
| Section | What you can do |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Concept** | Name, display name, description, concept IRI. |
| **Relationships** | Add, retype, and remove typed relations; pick the target concept by search. |
| **Attributes** | Add typed attributes (`STRING`, `INTEGER`, `DECIMAL`, `BOOLEAN`, `DATE`, `ENUM`), mark identifiers, set units and enum values. Inherited attributes are shown read-only with the ancestor that declares them. |
| **Mappings** | Map the concept to an external scheme by IRI with a match type (exact, close, broad, narrow, related, same-as). Duplicate mappings and malformed IRIs are rejected inline. |
| **Realization** | The data assets carrying this concept, grouped by service. |
## Delete with an Impact Preview
Deleting a concept in an ontology is not like deleting a row. Children have to go somewhere, typed relations disappear, external crosswalks break, and assets lose their semantic anchor.
Selecting **Delete** opens an **impact preview** before anything happens, showing:
* **Children** — immediate child concepts that must be reassigned, or explicitly cascaded.
* **Relationships** — every typed relation that would be removed.
* **Bound assets** — assets currently carrying the concept, with a total count and a flag when the sample is truncated (the preview shows up to 100).
* **Mappings** — external crosswalks that would be lost.
* Whether the resulting projection needs SHACL revalidation.
The preview is **version-bound**: it is generated against a specific version of the concept and carries a short-lived signed token (valid for two minutes) tied to both you and that exact snapshot. If the concept changes underneath you, the token no longer applies and you get a fresh preview instead of applying a stale decision.
API: `GET /api/v1/ontology/impacts/glossaryTerms/{id}/delete` to preview, `POST` the same path with the token to apply.
## The Model Workbench
**Edit → Model** is a set of structured tools for changes that are awkward to make node-by-node. Five tabs:
### Concept IRI
Preview the IRI a new concept will receive under the glossary's current `baseIri` and minting pattern *before* creating it. Placeholders are `{glossary}`, `{term}`, and `{uuid}`.
API: `POST /api/v1/ontology/modeling/iris/preview`.
### Template — Modeling Patterns
Instantiate a known-good sub-model instead of hand-drawing it. Three patterns ship today:
| Pattern | Shape |
| ---------------------- | ------------------------------------------------------ |
| **Regulatory Control** | Control `hasPart` Requirement `hasPart` Evidence |
| **Measured KPI** | KPI `calculatedFrom` Metric `calculatedFrom` Dimension |
| **Product Hierarchy** | Product `partOf` Portfolio; Feature `partOf` Product |
You supply names for each role; the pattern is materialized as a **draft change set** for review rather than applied directly.
API: `GET /api/v1/ontology/patterns`, `POST /api/v1/ontology/patterns/instantiate`.
### Include — Subsets
Build a scoped **application ontology** from a canonical one. Pin the source concepts a project needs, optionally pull in descendants and relationships, and OpenMetadata produces a draft change set that creates them in the target glossary.
Each materialized concept records its provenance: source glossary and term, the **exact versions** they were pinned at, the source IRI for exact-match traceability, and whether the modeler selected it directly or it came along as a descendant. That is what lets you answer "which version of the canonical model is this project actually built on" months later.
API: `POST /api/v1/ontology/subsets`.
### Merge — Structural Diff and Merge
Compare two ontology structures and reconcile them. The panel previews changes per concept — name, description, parent, entity status, relationships, mappings, custom properties — labels each as changed or unchanged, and offers conflict resolution before producing a draft change set.
API: `POST /api/v1/ontology/structure/diff`, `POST /api/v1/ontology/structure/merge`.
### Ontology Constraints — Axioms
Author OWL axioms with a structured class-expression editor: pick the constraint type, build the subject and target expressions, and **Validate** before saving.
The type dropdown uses plain-language labels for the OWL axiom types:
| Label in the UI | OWL axiom |
| ----------------------- | ------------------------- |
| **Child Of** | `rdfs:subClassOf` |
| **Exact Match** | `owl:equivalentClass` |
| **Conflict Resolution** | `owl:disjointWith` |
| **Classification** | class assertion |
| **Relationship** | object-property assertion |
| **Custom Property** | data-property assertion |
Class expressions compose named classes, intersections, unions, enumerations, and restrictions (`SOME`, `ONLY`, `VALUE`, `MIN`, `MAX`, `EXACT`). With `RDF_STRICT_OWL_PROFILE` enabled — the default — axioms outside the supported OWL 2 DL profile are rejected with an explanation.
Axioms are versioned entities in their own right, with owners, reviewers, and history.
API: `GET|POST|PUT|PATCH|DELETE /api/v1/ontologyAxioms`, `POST /api/v1/ontologyAxioms/validate`.
## Change Sets
Patterns, subsets, and merges all produce an **ontology change set** — a durable authoring session containing typed, reversible operations.
| State | Meaning |
| -------------- | ---------------------------------------------------------- |
| `DRAFT` | Being edited. Operations can be added, undone, and redone. |
| `SUBMITTED` | Sent for review; a review task is attached. |
| `APPLIED` | Operations executed against the ontology. |
| `APPLY_FAILED` | Application failed; the result records why. |
| `DISCARDED` | Abandoned. |
Operations are typed rather than free-form patches: `CREATE_TERM`, `UPDATE_TERM`, `DELETE_TERM`, `ADD_RELATIONSHIP`, `UPDATE_RELATIONSHIP`, `DELETE_RELATIONSHIP`, `UPSERT_ATTRIBUTE`, `DELETE_ATTRIBUTE`, `UPSERT_MAPPING`, `DELETE_MAPPING`, `UPSERT_AXIOM`, `DELETE_AXIOM`.
Each operation that touches an existing entity carries a `baseVersion` for **optimistic concurrency**: if the target moved since the draft was built, application fails loudly instead of silently overwriting. An `undoCursor` tracks the undo/redo position, so a draft is genuinely reviewable — you can walk it backwards before deciding.
API: `POST /api/v1/ontologyChangeSets`, then `/{id}/operations`, `/{id}/undo`, `/{id}/redo`, `/{id}/submit`, `/{id}/apply`, `/{id}/discard`.
The review path exists so ontology change can follow the same governance as anything else in the catalog: a suggester builds a draft, submits it, a reviewer approves, and application is a single audited event with a recorded result.
## Bulk Operations
Changes too large to make interactively — retyping every `relatedTo` edge in a glossary, find-and-replace across concept descriptions, mass attribute upserts — go through an asynchronous **bulk API**:
| Endpoint | Purpose |
| ------------------------------------------------- | ------------------------------------------ |
| `GET /api/v1/ontology/bulk/template` | Download a CSV template for the operation. |
| `POST /api/v1/ontology/bulk` | Submit a bulk job (supports dry run). |
| `GET /api/v1/ontology/bulk/jobs` | List your jobs. |
| `GET /api/v1/ontology/bulk/jobs/{jobId}` | Job status. |
| `PUT /api/v1/ontology/bulk/jobs/{jobId}/cancel` | Cancel a running job. |
| `GET /api/v1/ontology/bulk/jobs/{jobId}/artifact` | Download the result artifact. |
Bulk submissions are planned and validated before execution, and can be run as a **dry run** that produces a full report without persisting anything. Like the workbench tools, they can land as a draft change set for review.
## Next
Govern the edge vocabulary you author with.
Start from a standard instead of a blank canvas.
Bring an existing OWL/SKOS ontology in.
Get proposals for the parts you have not modeled yet.