Packages, imports and compilation
Understand definition files, dependencies and the compiled project model
A definition package contains a manifest and source files. A project can have several active definitions; compilation combines their model structure into a compiled ontology package used by bindings, mappings and queries.
Package contents
| Manifest field | Meaning |
|---|---|
| name | Lowercase name with hyphens, such as operations-demo |
| defaultNamespace | The definition's term namespace |
| modelEntrypoints | Package-relative model files to load |
| shapeEntrypoints | Package-relative shape files to load |
| imports | Declared imported resources/files supported by the loader |
| definitionImports | Dependencies on other definition assets and namespaces |
Paths stay inside the package: no absolute paths or .. traversal. modelEntrypoints must contain at least one file. Imports need resolvable content; declaring an import is not permission to fetch arbitrary remote resources.
Example package
You need a Semogram account and project definition authoring access. Create operations-demo with the complete model.ttl, and this manifest:
{
"name": "operations-demo",
"description": "Orders, customers and delivery evidence",
"defaultNamespace": "https://example.com/operations#",
"modelEntrypoints": [
"model.ttl"
],
"shapeEntrypoints": [],
"imports": []
}In the definition UI, use the corresponding Name, Namespace and model-file entrypoints; use the assistant to prepare/review this package if preferred. The downloadable create body includes both manifest and file content for HTTP or MCP creation. Saving this package does not copy database records.
Know which ID you are using
| Identifier | Use |
|---|---|
| Definition asset UUID | Inspect/change that one source definition |
| Definition saved-version UUID | Compare, activate or inspect its immutable file revision |
| Compiled package UUID | Select the combined model in mappings, bindings and queries |
| Numeric package version | Select the compiled revision required by those contracts |
| Full term IRI | Reference one class/property/relationship in that model |
Do not substitute one identifier for another even if their UI names are similar.
Compile and inspect
Active definition changes compile the project model. Public callers can explicitly request compilation:
Use a workspace API key with ontologies:write. Set SEMOGRAM_API_KEY in your shell and replace UUID placeholders with accessible resource IDs.
curl --request POST "https://platform.semogram.com/api/v1/projects/<PROJECT_UUID>/ontology/compile" \
--header "Authorization: Bearer ${SEMOGRAM_API_KEY}"Inspect GET /api/v1/projects/<PROJECT_UUID>/ontology with ontologies:read: it reports the compiled package, numeric version, source-definition information and collection counts. Inspect terms, links and shapes rather than relying on a “compiled” status alone.
Compilation may ensure a default materialized binding when a compatible fact-store endpoint is available. It does not populate that store, replace a manually authored binding, or guarantee that every term has the intended data source. Review bindings after compilation, particularly when the workspace has multiple stores.
Extend through another definition
Keep shared Customer meaning in one definition and import it into an orders definition using the supported definition-import controls. Review dependency identity, namespace and active revision. Do not redeclare an incompatible Customer under the same IRI. Validate the complete project's active model and query consumers after an imported definition changes.