Drafts, versions and activation

A definition draft is editable work. A saved definition version is a file revision. The active version contributes to the compiled project model. Query releases, pipeline versions and persisted facts have separate lifecycles.

A change from start to verification

You need a Semogram account and project definition authoring access. Begin with the complete operations model. To add a delivery date:

1. Read the current definition and active version. Open its model/file editor and add a deliveredAt datatype property with domain Order and range xsd:dateTime, under the existing namespace.
2. Validate the full package. Compare the changed files and terms with the previous version.
3. Save a version with a concrete commit message. Review whether the workflow activates it immediately or leaves it on a branch.
4. Inspect compilation, affected bindings, mappings and published query consumers.
5. Configure the data source for deliveredAt and test a known record. A new property declaration supplies no values by itself.

Programmatic changes

HTTP POST /ontology/definitions/<DEFINITION_UUID>/versions accepts the full manifest and files, optional branchName, commitMessage and setActiveVersion. It requires ontologies:write and an Idempotency-Key. Set setActiveVersion: false to save without selecting it as active. Activation has its own POST /versions/<VERSION_UUID>/activate action.

MCP ontology_update accepts the full package plus ontologyId, expectedActiveVersionId, optional branchName, setActiveVersion and idempotencyKey. Read the current active version first; a mismatch fails rather than silently replacing someone else's change. MCP version-list/get tools inspect history; use supported UI or HTTP activation for selecting a saved version.

What activation changes

Activation changes which definition revision is compiled. It does not rerun pipelines, rewrite stored entities, approve assertions, or move all consumers to a new query release. Revalidate and deliberately update each affected consumer.

Renaming versus identity

Changing a display label preserves a term's IRI. Replacing an IRI changes the referenced term. Removing a property can break mappings, read bindings, output contracts and released consumers. Inspect dependencies and model diffs before activation; retain history and use the supported deletion preview for definition removal.

If a model change fails, return to a supported earlier version and recheck compilation and consumers. Rolling back a definition does not undo external materialization writes that already completed.