TerminusDB 12.0.6: Shared Documents and Handlebars Text Rendering

TerminusDB 12.0.6 adds @shared documents that are cascade-deleted when their last referrer goes away, and a Handlebars text-rendering format for the document API. It was released on 24 June 2026.

• @shared documents — standalone documents that are deleted automatically when their last reference goes away.
• Embedding text output — render documents as plain text through a schema-defined Handlebars template.
• Fixes — @ref resolution for tagged unions, non-ASCII document loss, and SwapValue on compound values.

@shared documents

What it does

@shared is a new class-level annotation, a middle ground between a regular document and a @subdocument:

• Like a regular document, a @shared document has its own IRI and can be referenced from any number of other documents.
• Like a subdocument, it has a managed lifecycle: when the last document that references it is deleted, the @shared document is deleted too — in the same transaction.

{
  "@id": "Tag",
  "@type": "Class",
  "@shared": [],
  "label": "xsd:string"
}

This is designed for flows where documents are created standalone and linked later — for example loading data in several transactions that are merged into one commit. The cascade delete is atomic: either all deletions succeed or the whole transaction rolls back.

Why it matters

At shared is important when you build a knowledge graph out of JSON-LD documents and think of the question of lifecycles. How do you lifecycle the triples of a JSON-LD document without annotation of what triples belong to which document?

With @shared you can say that this document exists only as long as it is referenced. But it lives its own life, can be referenced by many and be updated independently. But once the last reference is removed, it is deleted automatically. This is very useful for representing knowledge graphs in TerminusDB.

Together with the XML and Triples features of TerminusDB Enterprise, you can now represent knowledge graphs in a very natural way, including for the blank nodes handling that are not required in a TerminusDB knowledge graph thanks to the schema, where instead they get skolemized and replaced by schema frames.

Example

{ "@type": "Tag", "@id": "Tag/featured", "label": "Featured" }

{ "@type": "Article", "@id": "Article/1", "title": "On graphs", "tags": ["Tag/featured"] }

When Article/1 is the last document holding a reference to Tag/featured and it is deleted, Tag/featured is removed in the same commit.

Read more: The document model · Schema reference · Subdocuments

Embedding text output

What it does

The document API can now render documents as text/plain using a Handlebars template defined in the schema under @metadata.embedding. Ask for it with format=embedding or an Accept: text/plain header:

curl -u admin:root "http://localhost:6363/api/document/admin/db?format=embedding&id=Animal/Plato"

{
  "@id": "Animal",
  "@type": "Class",
  "@key": { "@type": "Lexical", "@fields": ["name"] },
  "name": "xsd:string",
  "@metadata": {
    "embedding": {
      "query": "query ($id: ID) { Animal(id: $id) { name } }",
      "template": "The animal is named {{name}}."
    }
  }
}

For Animal/Plato this returns The animal is named Plato. — a flat text rendering of the document, made for embedding into vector indexes such as VectorLink. Classes without an embedding definition return a no_embedding_query error.

Why it matters

Templates turn any document into embedding-ready text in a single API call, removing the transformation step from your indexing pipeline. The same template keeps rendered text consistent as documents change, so vector indexes stay in sync with the data.

Fixes

• @ref capture resolution now works with TaggedUnion variants (#2432)
• Fixed silent document loss for non-ASCII characters in the document API (#2450)
• SwapValue patches now handle dicts, lists and numbers correctly (#2438)

Upgrade

docker pull terminusdb/terminusdb-server:v12.0.6

No data migration is needed. Docker install guide · Full changelog on GitHub

Previous: TerminusDB 12.0.5: Streaming History with Diffs · Next: TerminusDB 12.0.7: Resolve Merge Conflicts with Insert and Delete Patches · TerminusDB 12.0 changelog · Release index