Deliverable Templates & Document Generation¶

Linked.Archi provides a fully declarative pipeline for generating architecture documents from the knowledge graph. The ontology defines the document structure, the SPARQL queries that extract data, and the Handlebars templates that render the output. A generator tool reads these definitions and produces Markdown, HTML, or PDF documents — no hardcoded extraction logic required.

How It Works¶

The pipeline has three layers, all defined in the ontology:

Ontology (what)              Template (how)              Output (result)
─────────────────            ──────────────              ───────────────
DeliverableTemplate          .md.hbs file                .md / .html / .pdf
  └─ TemplateSection         {{#each key}}
       ├─ sectionOrder         table rows
       ├─ sectionQuery       {{/each}}
       └─ sectionResultKey

An arch:DeliverableTemplate defines the document — its title, purpose, required viewpoints, and sections.
Each arch:TemplateSection carries a SPARQL query (arch:sectionQuery) and a result key (arch:sectionResultKey).
A generator tool executes the queries, assembles a JSON context, and renders a Handlebars template.

Example: Architecture Definition Document¶

The ArchiMate 3.2 deliverable templates define three documents. Here's how the Architecture Definition Document works end-to-end.

Ontology Definition¶

:ADD-S1 a arch:TemplateSection ;
    arch:sectionOrder     1 ;
    arch:sectionViewpoint amvp:Organization ;
    arch:sectionResultKey "businessOrganization" ;
    skos:prefLabel        "1. Business Organization"@en ;
    skos:definition       "Organizational structure — actors, roles, collaborations."@en ;
    arch:sectionQuery     """
        PREFIX am:   <https://meta.linked.archi/archimate3/onto#>
        PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

        SELECT ?element ?label ?type ?description ?assignedTo WHERE {
            ?element a ?type ;
                     skos:prefLabel ?label .
            VALUES ?type {
                am:BusinessActor am:BusinessRole am:BusinessCollaboration
                am:BusinessInterface am:Location
            }
            OPTIONAL { ?element skos:definition ?description }
            OPTIONAL {
                ?element am:assignedTo ?target .
                ?target skos:prefLabel ?assignedTo .
                FILTER(lang(?assignedTo) = "en")
            }
            FILTER(lang(?label) = "en")
        } ORDER BY ?type ?label
    """^^xsd:string .

SPARQL Execution¶

The generator executes the query against the knowledge graph. For a model containing:

ex:ITOps a am:BusinessActor ;
    skos:prefLabel "IT Operations"@en ;
    skos:definition "Manages infrastructure and platform services."@en .

ex:ServiceAgent a am:BusinessRole ;
    skos:prefLabel "Service Agent"@en ;
    skos:definition "Front-line customer support."@en ;
    am:assignedTo ex:CustomerServiceTeam .

The query returns:

element	label	type	description	assignedTo
ex:ITOps	IT Operations	am:BusinessActor	Manages infrastructure...
ex:ServiceAgent	Service Agent	am:BusinessRole	Front-line customer support.	Customer Service Team

JSON Context Assembly¶

The generator converts the results into a JSON context using arch:sectionResultKey as the key:

{
  "meta": {
    "title": "Architecture Definition Document",
    "date": "2026-04-24",
    "author": "Kalin Maldzhanski",
    "status": "Draft",
    "version": "1.0"
  },
  "businessOrganization": [
    {
      "element": "https://example.com/ITOps",
      "label": "IT Operations",
      "type": "BusinessActor",
      "description": "Manages infrastructure and platform services.",
      "assignedTo": null
    },
    {
      "element": "https://example.com/ServiceAgent",
      "label": "Service Agent",
      "type": "BusinessRole",
      "description": "Front-line customer support.",
      "assignedTo": "Customer Service Team"
    }
  ],
  "businessProcessCooperation": [ ... ],
  "applicationCooperation": [ ... ]
}

Handlebars Rendering¶

The template file (architecture-definition-document.md.hbs) uses the result keys:

## 1. Business Organization

| Element | Type | Description | Assigned To |
|---------|------|-------------|-------------|
{{#each businessOrganization}}
| {{this.label}} | {{this.type}} | {{this.description}} | {{this.assignedTo}} |
{{/each}}

Output¶

## 1. Business Organization

| Element | Type | Description | Assigned To |
|---------|------|-------------|-------------|
| IT Operations | BusinessActor | Manages infrastructure and platform services. | |
| Service Agent | BusinessRole | Front-line customer support. | Customer Service Team |

Available Templates¶

ArchiMate 3.2¶

Template	Sections	File
Architecture Definition Document	6 (Organization, Business Process, Application, Technology, Layered, Deployment)	`archimate3.2-deliverable-templates.ttl`
Architecture Requirements Specification	4 (Stakeholder, Goal Realization, Requirements, Motivation)	same file
Architecture Principles Document	2 (Motivation, Strategy)	same file

Template files are in modelingLanguages/archimate/3.2/templates/.

Core (Framework-Agnostic)¶

Template	Sections	File
Architecture Overview Document	5 (Landscape, Stakeholders, Components, Dependencies, Standards)	`core-deliverable-templates.ttl`
Solution Design Document	5 (Context, Process, Interface, Deployment, Decisions)	same file
Change Impact Assessment	4 (Impact, Dependencies, Gaps, Roadmap)	same file

Ontology Properties¶

Property	Domain	Range	Description
`arch:templateHasSection`	`DeliverableTemplate`	`TemplateSection`	Links template to its sections
`arch:sectionOrder`	`TemplateSection`	`xsd:integer`	Sort order within the template
`arch:sectionViewpoint`	`TemplateSection`	`Viewpoint`	The viewpoint this section addresses
`arch:sectionQuery`	`TemplateSection`	`xsd:string`	SPARQL SELECT query for section data
`arch:sectionResultKey`	`TemplateSection`	`xsd:string`	JSON key for query results in template context
`arch:templateResource`	`DeliverableTemplate`	`xsd:anyURI`	Path to the Handlebars template file
`arch:templateHasFormat`	`DeliverableTemplate`	`PresentationFormat`	Supported output formats
`arch:templateTargetsPurpose`	`DeliverableTemplate`	`Purpose`	What architecture activity this supports

Writing Custom Templates¶

To create a new deliverable template:

Define a arch:DeliverableTemplate individual with sections
Add arch:sectionQuery to each section with a SPARQL query
Set arch:sectionResultKey to name the JSON key
Create a .md.hbs file that uses {{#each resultKey}}
Point arch:templateResource to the template file

The generator tool reads everything from the ontology — no code changes needed.

Tool Specification¶

See Deliverable Generator Spec for the full tool specification including CLI interface, processing pipeline, configuration, and error handling.