Turtle Support

Enterprise adds full Turtle serialization and parsing to the document endpoint. Documents stored in TerminusDB can be retrieved as well-formed Turtle, and Turtle documents can be submitted for import — both validated against the database schema.

Turtle (Terse RDF Triple Language) is a compact, human-readable RDF serialization. It uses prefixed names, semicolons for predicate grouping, and square brackets for blank nodes — making it considerably more readable than RDF/XML for the same data.

Turtle output

Request Turtle output with the format=turtle query parameter or the Accept: text/turtle header:

curl -s -H "$AUTH" "$SERVER/api/document/$DB?type=Product&format=turtle"

The output is a valid Turtle document with @base and @prefix declarations followed by the document triples:

@base <terminusdb:///data/> .
@prefix schema: <terminusdb:///schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

<terminusdb:///data/Product/SKU-1001>
  a schema:Product ;
  schema:name "Industrial Sensor Module" ;
  schema:price "249.99"^^xsd:decimal ;
  schema:active "true"^^xsd:boolean ;
  schema:category <terminusdb:///data/Category/ELEC> ;
  schema:unit [
    a schema:UnitOfMeasure ;
    schema:symbol "pcs" ;
    schema:name "pieces"
  ] .

Prefix declarations

Prefix declarations are generated from the database context. The standard RDF and XSD namespaces are always included. The @base declaration provides the base IRI for resolving relative references. Schema-specific namespaces (terminusdb:///schema#) appear as the prefix used for types and properties.

Typed literals

Typed values carry ^^ datatype annotations matching their XSD types:

• xsd:decimal for decimal numbers (e.g., prices, weights)
• xsd:boolean for boolean values
• xsd:integer for integer values
• xsd:dateTime for date-time values
• Strings are plain double-quoted literals without a datatype annotation

Document references

References to other documents use full IRIs in angle brackets:

schema:category <terminusdb:///data/Category/ELEC> .

Subdocument nesting

Subdocuments (classes with @subdocument) are serialized as blank node blocks using the [ ... ] syntax rather than flat references. This preserves the hierarchical structure and keeps related data together:

schema:unit [
    a schema:UnitOfMeasure ;
    schema:symbol "pcs" ;
    schema:name "pieces"
  ] .

The blank node syntax is the Turtle equivalent of nested child elements in RDF/XML or embedded objects in JSON — it expresses the same containment relationship in a compact, readable form.

Turtle input

Submit Turtle documents with the Content-Type: text/turtle header:

echo '@prefix schema: <terminusdb:///schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<terminusdb:///data/Product/SKU-3001>
  a schema:Product ;
  schema:sku "SKU-3001" ;
  schema:name "Calibration Standard" ;
  schema:category <terminusdb:///data/Category/ELEC> ;
  schema:price "425.00"^^xsd:decimal ;
  schema:weight_kg "0.15"^^xsd:decimal ;
  schema:unit [
    a schema:UnitOfMeasure ;
    schema:symbol "pcs" ;
    schema:name "pieces"
  ] ;
  schema:active "true"^^xsd:boolean .' | \
curl -s -X POST \
  -H "Content-Type: text/turtle" \
  -H "$AUTH" \
  --data-binary @- \
  "$SERVER/api/document/$DB?author=admin&message=import"

The echo | --data-binary @- pattern is necessary because Turtle starts with @prefix, and curl interprets a leading @ as a filename reference. Using --data-binary (rather than -d) also preserves newlines, which Turtle syntax relies on.

The parser reads prefix declarations, resolves prefixed names to full IRIs, maps ^^ datatype annotations to schema types, and inserts documents — all validated against the schema.

Supported reference styles

Turtle input supports multiple ways to reference documents and subdocuments:

• Blank node blocks — subdocuments as inline [ ... ] blocks (hierarchical style)
• Full IRI references — <terminusdb:///data/...> references to other top-level documents
• Blank node labels — _:label references for subdocuments defined elsewhere in the same document
• Statement order independence — referenced subdocuments can appear before or after the referencing parent

Context and prefix relationship

Turtle @prefix declarations serve the same purpose as JSON-LD @context and RDF/XML xmlns: — they map short prefixes to full IRIs. The key difference is in syntax:

When a database has a custom schema @context, it affects JSON-LD output only. Turtle output always generates @prefix declarations from the resolved namespace IRIs regardless of the schema @context setting.

Turtle compared to RDF/XML

Turtle and RDF/XML express exactly the same RDF graph — they are alternative serializations of the same data model. The choice between them is primarily about readability and tooling:

Use cases for Turtle

Turtle is the right format choice when working with:

• Human review workflows where data stewards need to read and verify RDF content
• Version control where line-oriented diffs make changes easy to review in pull requests
• SPARQL tooling that accepts Turtle as a data exchange format
• Academic and research data exchange where Turtle is the de facto standard
• Debugging and diagnostics where compact, readable output helps trace data issues
• Configuration-as-code pipelines where RDF data is committed alongside application code

Further reading

• Document Formats & Content Negotiation — how to select formats
• RDF/XML Support — the XML-based counterpart
• JSON-LD Context Processing — the JSON-LD counterpart
• Multi-Format Document API Tutorial — hands-on round-trip walkthrough