Skip to content
Beskid Platform specification

Beskid

Jump to a Beskid service

Beskid

Jump to a Beskid service

Design model

Platform spec article

Design model

Back to Project templates Open feature in platform map

Spec standingStandard

Owner
Piotr Mikstacki
Submitter
Piotr Mikstacki

Purpose and scope

Section titled “Purpose and scope”

This article defines the normative data model for Beskid templates: manifest file location, beskid.template.v1 top-level keys, symbol types, content manipulation, and corelib behavior on instantiated projects.

Manifest location

Section titled “Manifest location”
ContextPath
Template package or git/path tree.beskid/template.json at the template root
Optional author metadata in Project.projproject.template { shortName, identity } when type: Template

The engine must read .beskid/template.json as authoritative. project.template keys are hints for discovery and packaging; if both exist, template.json wins on conflict.

Top-level beskid.template.v1 keys

Section titled “Top-level beskid.template.v1 keys”
KeyRequiredMeaning
schemayesLiteral beskid.template.v1
identityyesStable id: packageId::version or path/git fingerprint
nameyesDisplay name in beskid new list
shortNameyesCLI selector: beskid new <shortName>
authornoAuthor string
descriptionnoShort summary
classificationsnoSearch tags
tagsnoObject; type must be one of: project, workspace, item
sourceNamenoDefault token replaced in paths and file bodies (in addition to {{ }})
symbolsnoParameter definitions
sourcesnoFile copy rules; default single mapping ./ → output
guidsnoGUIDs to regenerate in output
formsnoValue transforms (see below)
postActionsnoOrdered post-instantiation actions
preferInteractivenoWhen true, prompt for symbols without CLI values before using defaults

Forbidden in v1: constraints, foreign schema imports, or alternate placeholder delimiters.

Tags.type semantics

Section titled “Tags.type semantics”
tags.typeOutput
projectCreates a directory tree with Project.proj (and Src/ or template-defined layout)
workspaceCreates Workspace.proj plus member project trees
itemAdds or overwrites files inside an existing project directory; must not emit a new root Project.proj unless sources explicitly includes one and the CLI passed --allow-project-manifest

Symbols

Section titled “Symbols”

Each symbol is an object keyed by symbol id (used in {{symbolId}}):

FieldRequiredMeaning
typeyesstring, choice, bool, integer
descriptionnoPrompt text
defaultValuenoUsed when non-interactive and flag omitted
choicesfor choiceAllowed values
isRequirednoDefault false; when true, interactive mode must collect a value

CLI mapping: --symbol <id>=<value> and short forms documented in beskid new.

Placeholders

Section titled “Placeholders”
  1. {{symbolId}} — replaced in all processed text files after forms are applied.
  2. sourceName — when set at template level, every occurrence of the sourceName string in paths and file contents is replaced with the primary name symbol (default symbol id name unless nameSymbol specifies another).

Hosts must fail if any {{...}} remains after substitution.

Forms

Section titled “Forms”

forms define named transforms applied to symbol values before substitution (for example lowerCase, safeName, namespace). Built-in form ids are listed in contracts and edge cases.

Sources

Section titled “Sources”

Each source entry:

FieldDefaultMeaning
source./Path inside template root
target./Relative to user output directory
include["**/*"]Glob includes
excludebuild artifacts, .beskid/template.json copy to wrong placeGlob excludes
copyOnly[]Copy without text processing
rename{}Explicit renames after symbol resolution
conditiontrueWhen false, skip this source block
modifiers[]Conditional patches to include/exclude

.beskid/template.json must not appear in generated output unless a source block intentionally copies it to a documentation path.

Guids

Section titled “Guids”

The guids array lists GUID strings appearing in template sources. For each entry, the engine must generate a new GUID and replace all occurrences in output, preserving format and casing of each occurrence (same rules as common template GUID rewriting: match N, D, B, P, X representations independently).

corelib policy

Section titled “corelib policy”
RuleNormative statement
Implicit dependencyEvery instantiated project with project.type absent or Host must treat corelib as an implicit registry dependency resolved by the toolchain—equivalent to today’s std/corelib discovery path.
Manifest surfaceProject.proj emitted by templates must not declare a noCorelib, useCorelib: false, or any flag that disables corelib.
Template author docsTemplates may omit an explicit dependency "corelib" block from generated manifests; the first beskid lock / fetch must materialize corelib anyway.
Mod / workspaceMod projects in template output follow mod resolution rules; corelib policy applies to host members that execute Beskid user code.

If the compiler today requires an explicit dependency for some workflows, tooling must inject the dependency during instantiation or in post-action addCorelib—without exposing a user-facing opt-out.

Authoring: project.type = Template

Section titled “Authoring: project.type = Template”
project {
  name    = "beskid-templates-console"
  version = "0.0.0"
  type    = Template
  template {
    shortName = "console"
    identity  = "beskid.templates.console"
  }
}

Template projects must not be selected as compile targets for beskid build at the template package root; only their packaged .beskid/template.json is consumed by consumers.

Diagram

Section titled “Diagram”
flowchart TB
  TJ[.beskid/template.json]
  SYM[symbols]
  SRC[sources]
  PH["{{ }} + sourceName"]
  GD[guids]
  OUT[Output tree]
  TJ --> SYM --> PH
  TJ --> SRC --> PH
  TJ --> GD --> OUT
  PH --> OUT

Code anchors

Section titled “Code anchors”
  • Planned: compiler/crates/beskid_cli/src/template/ (engine)
  • Manifest parse: extend compiler/crates/beskid_analysis/src/projects/model.rs with ProjectKind::Template
  • Registry: pckg template package profile