Linked.Archi

Linked.Archi Backstage Deliverable Templates

Deliverable Templates

https://meta.linked.archi/backstage/deliverable-templates#

v0.1.0 draft bsdt: Kalin Maldzhanski Linked.Archi License

Catalogue of deliverable templates for generating architecture documents from Backstage catalog models — a service catalog, a system architecture document, and an organization structure document. Declares no classes or properties; the vocabulary these individuals instantiate (arch:DeliverableTemplate, arch:TemplateSection) is defined in the core ontology.

Service Catalog Document

A Backstage-based service catalog document progressing from a full service inventory through ownership governance and API dependency analysis to a lifecycle portfolio. Suitable for platform engineering reviews and developer onboarding.

Template: templates/service-catalog-document.md.hbs
Required Viewpoints: ServiceCatalog OwnershipMatrix APIDependency LifecyclePortfolio
Target Purposes: Informing, Governing
Available Formats: MarkdownFormat, HTMLFormat

Sections

1 1. Service Catalog
Inventory of all registered components, systems, APIs and resources.
Viewpoint: ServiceCatalog Result key: serviceCatalog
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX arch: <https://meta.linked.archi/core#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?element ?name ?label ?type ?specType ?lifecycle ?description ?domain ?system WHERE {
    ?element a ?type ;
             skos:prefLabel ?label .
    VALUES ?type { bs:Component bs:System bs:API bs:Resource }
    OPTIONAL { ?element bs:name ?name }
    OPTIONAL { ?element skos:definition ?description }
    OPTIONAL {
        ?element (bs:componentType|bs:apiType|bs:resourceType|bs:systemType)/skos:notation ?specType
    }
    OPTIONAL { ?element bs:lifecycleState/skos:notation ?lifecycle }
    OPTIONAL {
        { ?element bs:belongsToDomain ?dom }
        UNION
        { ?element bs:partOfSystem/bs:belongsToDomain ?dom }
        ?dom skos:prefLabel ?domain .
        FILTER(lang(?domain) = "en")
    }
    OPTIONAL {
        ?element bs:partOfSystem ?sys .
        ?sys skos:prefLabel ?system .
        FILTER(lang(?system) = "en")
    }
    FILTER(lang(?label) = "en")
} ORDER BY ?type ?domain ?label
2 2. Ownership Matrix
Which groups or users own which catalog entities.
Viewpoint: OwnershipMatrix Result key: ownershipMatrix
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?element ?elementLabel ?type ?owner ?ownerLabel ?ownerKind WHERE {
    ?element a ?type ;
             skos:prefLabel ?elementLabel ;
             bs:ownedBy ?owner .
    ?owner skos:prefLabel ?ownerLabel .
    VALUES ?type { bs:Component bs:System bs:API bs:Resource bs:Domain }
    OPTIONAL {
        ?owner a ?ownerKind .
        VALUES ?ownerKind { bs:Group bs:User }
    }
    FILTER(lang(?elementLabel) = "en")
    FILTER(lang(?ownerLabel) = "en")
} ORDER BY ?ownerLabel ?type ?elementLabel
3 3. API Dependencies
API provision and consumption relationships across components and systems.
Viewpoint: APIDependency Result key: apiDependencies
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?api ?apiLabel ?apiType ?visibility ?provider ?providerLabel ?consumer ?consumerLabel WHERE {
    ?api a bs:API ;
         skos:prefLabel ?apiLabel .
    OPTIONAL { ?api bs:apiType/skos:notation ?apiType }
    OPTIONAL { ?api bs:apiVisibility/skos:notation ?visibility }
    OPTIONAL {
        ?provider bs:providesAPI ?api .
        ?provider skos:prefLabel ?providerLabel .
        FILTER(lang(?providerLabel) = "en")
    }
    OPTIONAL {
        ?consumer bs:consumesAPI ?api .
        ?consumer skos:prefLabel ?consumerLabel .
        FILTER(lang(?consumerLabel) = "en")
    }
    FILTER(lang(?apiLabel) = "en")
} ORDER BY ?apiLabel ?providerLabel ?consumerLabel
4 4. Lifecycle Portfolio
Components and APIs grouped by lifecycle state, with their owners.
Viewpoint: LifecyclePortfolio Result key: lifecyclePortfolio
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?element ?label ?kind ?lifecycle ?ownerLabel WHERE {
    ?element a ?kind ;
             skos:prefLabel ?label .
    VALUES ?kind { bs:Component bs:API }
    OPTIONAL { ?element bs:lifecycleState/skos:notation ?lifecycle }
    OPTIONAL {
        ?element bs:ownedBy ?owner .
        ?owner skos:prefLabel ?ownerLabel .
        FILTER(lang(?ownerLabel) = "en")
    }
    FILTER(lang(?label) = "en")
} ORDER BY ?lifecycle ?kind ?label
📄 Template Preview 
---
title: "Service Catalog Document"
date: "{{meta.date}}"
author: "{{meta.author}}"
status: "{{meta.status}}"
version: "{{meta.version}}"
---

# Service Catalog Document

{{#if meta.description}}
> {{meta.description}}
{{/if}}

| Property | Value |
|----------|-------|
| Date | {{meta.date}} |
| Author | {{meta.author}} |
| Status | {{meta.status}} |
| Version | {{meta.version}} |
| Metamodel | Backstage Catalog |

---

## 1. Service Catalog

Inventory of all registered components, systems, and APIs.

### All Entities

| Entity | Type | Domain | System | Description |
|--------|------|--------|--------|-------------|
{{#each serviceCatalog}}
| {{this.label}} | {{this.type}} | {{this.domain}} | {{this.system}} | {{this.description}} |
{{/each}}

---

## 2. Ownership Matrix

Which groups own which components and systems.

### Ownership

| Owner | Entity | Type |
|-------|--------|------|
{{#each ownershipMatrix}}
| {{this.ownerLabel}} | {{this.elementLabel}} | {{this.type}} |
{{/each}}

---

## 3. API Dependencies

API provision and consumption relationships across components.

### API Dependency Map

| API | Provider | Consumer |
|-----|----------|----------|
{{#each apiDependencies}}
| {{this.apiLabel}} | {{this.providerLabel}} | {{this.consumerLabel}} |
{{/each}}

System Architecture Document

A Backstage-based system architecture document progressing from domain organization through system dependencies and API landscape analysis to component composition. Suitable for architecture reviews and system design discussions.

Template: templates/system-architecture-document.md.hbs
Required Viewpoints: DomainOverview SystemDependency APIDependency
Target Purposes: Designing, Informing
Available Formats: MarkdownFormat, HTMLFormat

Sections

1 1. Domain Overview
Domains, their nesting, and their constituent systems and components.
Viewpoint: DomainOverview Result key: domainOverview
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?domain ?domainLabel ?parentLabel ?description ?system ?systemLabel ?component ?componentLabel
WHERE {
    ?domain a bs:Domain ;
            skos:prefLabel ?domainLabel .
    OPTIONAL { ?domain skos:definition ?description }
    OPTIONAL {
        ?domain bs:subdomainOf ?parent .
        ?parent skos:prefLabel ?parentLabel .
        FILTER(lang(?parentLabel) = "en")
    }
    OPTIONAL {
        ?system bs:belongsToDomain ?domain ;
                a bs:System ;
                skos:prefLabel ?systemLabel .
        FILTER(lang(?systemLabel) = "en")
        OPTIONAL {
            ?component bs:partOfSystem ?system ;
                       a bs:Component ;
                       skos:prefLabel ?componentLabel .
            FILTER(lang(?componentLabel) = "en")
        }
    }
    FILTER(lang(?domainLabel) = "en")
} ORDER BY ?parentLabel ?domainLabel ?systemLabel ?componentLabel
2 2. System Dependencies
System-level dependencies, whether via a consumed API or a direct dependency.
Viewpoint: SystemDependency Result key: systemDependencies
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?system ?systemLabel ?dependsOn ?dependsOnLabel ?dependencyType WHERE {
    ?system a bs:System ;
            skos:prefLabel ?systemLabel .
    {
        # Indirect: a component in this system consumes an API provided from another system.
        ?comp bs:partOfSystem ?system ;
              bs:consumesAPI ?api .
        ?provider bs:providesAPI ?api ;
                  bs:partOfSystem ?depSys .
        ?depSys skos:prefLabel ?dependsOnLabel .
        BIND("API" AS ?dependencyType)
        BIND(?depSys AS ?dependsOn)
        FILTER(?system != ?depSys)
    } UNION {
        # Direct: spec.dependsOn from a component in this system, onto a resource or a component.
        ?comp bs:partOfSystem ?system .
        ?comp (bs:dependsOn|bs:usesResource) ?dep .
        ?dep skos:prefLabel ?dependsOnLabel .
        BIND(?dep AS ?dependsOn)
        BIND(IF(EXISTS { ?dep a bs:Resource }, "Resource", "Component") AS ?dependencyType)
    }
    FILTER(lang(?systemLabel) = "en")
    FILTER(lang(?dependsOnLabel) = "en")
} ORDER BY ?systemLabel ?dependencyType ?dependsOnLabel
3 3. API Landscape
API provision and consumption across the system boundary.
Viewpoint: APIDependency Result key: apiLandscape
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?api ?apiLabel ?apiType ?visibility ?description ?provider ?providerLabel ?consumer ?consumerLabel
WHERE {
    ?api a bs:API ;
         skos:prefLabel ?apiLabel .
    OPTIONAL { ?api skos:definition ?description }
    OPTIONAL { ?api bs:apiType/skos:notation ?apiType }
    OPTIONAL { ?api bs:apiVisibility/skos:notation ?visibility }
    OPTIONAL {
        ?provider bs:providesAPI ?api .
        ?provider skos:prefLabel ?providerLabel .
        FILTER(lang(?providerLabel) = "en")
    }
    OPTIONAL {
        ?consumer bs:consumesAPI ?api .
        ?consumer skos:prefLabel ?consumerLabel .
        FILTER(lang(?consumerLabel) = "en")
    }
    FILTER(lang(?apiLabel) = "en")
} ORDER BY ?apiLabel
4 4. Component Composition
Component nesting within systems, from spec.subcomponentOf.
Viewpoint: SystemDependency Result key: componentComposition
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?component ?componentLabel ?parent ?parentLabel ?system ?systemLabel WHERE {
    ?component a bs:Component ;
               skos:prefLabel ?componentLabel ;
               bs:subcomponentOf ?parent .
    ?parent skos:prefLabel ?parentLabel .
    OPTIONAL {
        ?component bs:partOfSystem ?system .
        ?system skos:prefLabel ?systemLabel .
        FILTER(lang(?systemLabel) = "en")
    }
    FILTER(lang(?componentLabel) = "en")
    FILTER(lang(?parentLabel) = "en")
} ORDER BY ?systemLabel ?parentLabel ?componentLabel
📄 Template Preview 
---
title: "System Architecture Document"
date: "{{meta.date}}"
author: "{{meta.author}}"
status: "{{meta.status}}"
version: "{{meta.version}}"
---

# System Architecture Document

{{#if meta.description}}
> {{meta.description}}
{{/if}}

| Property | Value |
|----------|-------|
| Date | {{meta.date}} |
| Author | {{meta.author}} |
| Status | {{meta.status}} |
| Version | {{meta.version}} |
| Metamodel | Backstage Catalog |

---

## 1. Domain Overview

Domains and their constituent systems and components.

### Domain Hierarchy

{{#each domainOverview}}
| Domain | System | Component | Description |
|--------|--------|-----------|-------------|
| {{this.domainLabel}} | {{this.systemLabel}} | {{this.componentLabel}} | {{this.description}} |
{{/each}}

---

## 2. System Dependencies

System-level dependencies including APIs and resources.

### Dependency Map

| System | Depends On | Dependency Type |
|--------|------------|-----------------|
{{#each systemDependencies}}
| {{this.systemLabel}} | {{this.dependsOnLabel}} | {{this.dependencyType}} |
{{/each}}

---

## 3. API Landscape

API provision and consumption across the system boundary.

### APIs

| API | Description | Provider | Consumer |
|-----|-------------|----------|----------|
{{#each apiLandscape}}
| {{this.apiLabel}} | {{this.description}} | {{this.providerLabel}} | {{this.consumerLabel}} |
{{/each}}

Organization Structure Document

The organizational half of the Backstage catalog: the group hierarchy, who belongs to each group, and what each group is accountable for. Suitable for ownership reviews and onboarding.

Template: templates/organization-structure-document.md.hbs
Required Viewpoints: OrganizationStructure OwnershipMatrix
Target Purposes: Informing, Governing
Available Formats: MarkdownFormat, HTMLFormat

Sections

1 1. Group Hierarchy
Groups and their parents, from spec.parent.
Viewpoint: OrganizationStructure Result key: groupHierarchy
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?group ?groupLabel ?groupType ?displayName ?email ?parent ?parentLabel WHERE {
    ?group a bs:Group ;
           skos:prefLabel ?groupLabel .
    OPTIONAL { ?group bs:groupType/skos:notation ?groupType }
    OPTIONAL { ?group bs:displayName ?displayName }
    OPTIONAL { ?group bs:email ?email }
    OPTIONAL {
        ?group bs:childOf ?parent .
        ?parent skos:prefLabel ?parentLabel .
        FILTER(lang(?parentLabel) = "en")
    }
    FILTER(lang(?groupLabel) = "en")
} ORDER BY ?parentLabel ?groupLabel
2 2. Group Membership
Users and the groups they belong to, from spec.memberOf.
Viewpoint: OrganizationStructure Result key: groupMembership
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?group ?groupLabel ?user ?userLabel ?displayName ?email WHERE {
    ?user a bs:User ;
          skos:prefLabel ?userLabel ;
          bs:memberOf ?group .
    ?group skos:prefLabel ?groupLabel .
    OPTIONAL { ?user bs:displayName ?displayName }
    OPTIONAL { ?user bs:email ?email }
    FILTER(lang(?userLabel) = "en")
    FILTER(lang(?groupLabel) = "en")
} ORDER BY ?groupLabel ?userLabel
3 3. Accountability
What each group or user is the ultimate owner of, counted by kind.
Viewpoint: OwnershipMatrix Result key: accountability
SPARQL Query 
PREFIX bs:   <https://meta.linked.archi/backstage/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?owner ?ownerLabel ?kind (COUNT(?element) AS ?ownedCount) WHERE {
    ?element bs:ownedBy ?owner ;
             a ?kind .
    ?owner skos:prefLabel ?ownerLabel .
    VALUES ?kind { bs:Component bs:System bs:API bs:Resource bs:Domain }
    FILTER(lang(?ownerLabel) = "en")
} GROUP BY ?owner ?ownerLabel ?kind
  ORDER BY DESC(?ownedCount) ?ownerLabel
Source: linked-archi-meta • Linked.Archi