TypeScript library + CLI for programmatic mutation of LikeC4 .c4 files. Parses .c4 via @likec4/language-server (Langium), mutates through CST-position-based text replacement, serializes back preserving formatting.
Requires Node.js >= 22.22.3 (the minimum supported by @likec4/language-server).
npm install likec4-mutator # library
npx likec4-mutator --help # CLIimport { LikeC4Mutator } from 'likec4-mutator';
const mutator = LikeC4Mutator.fromFiles({
'model.c4': `
specification {
element service
element database
tag internal
tag critical
tag deprecated
}
model {
app = service 'My App' {
api = service 'API'
}
}
views {
view index {
include *
}
}
`});
// Query
const el = mutator.getElement('app');
const all = mutator.listElements({ kind: 'service' });
const rels = mutator.getRelationships({ sourceFqn: 'app' });
const source = mutator.getElementSource('app');
const spec = mutator.getSpecification();
const views = mutator.listViews();
const blocks = mutator.listViewsBlocks();
const globals = mutator.getGlobals();
// Add element (all properties)
mutator.addElement('app', {
name: 'db',
kind: 'database',
title: 'PostgreSQL',
summary: 'Primary data store',
description: 'Main database for user and transaction data',
technology: 'PostgreSQL 16',
tags: ['internal', 'critical'],
links: [
{ url: 'https://docs.example.com/db', label: 'DB Docs' },
{ url: 'https://github.com/example/db' },
],
style: {
shape: 'cylinder',
color: 'blue',
icon: 'tech:postgresql',
opacity: '80%',
border: 'dashed',
},
metadata: {
owner: 'platform-team',
env: 'production',
keywords: ['internal', 'critical'], // array values are supported
},
});
// Add relationship (all properties)
mutator.addRelationship('app.api', 'app.db', 'reads/writes', {
description: 'Queries the main database',
technology: 'JDBC',
tags: ['internal'],
links: [{ url: 'https://docs.example.com/db', label: 'DB Docs' }],
metadata: { sla: '99.9%' },
style: { line: 'dashed', color: 'red', head: 'diamond', tail: 'none' },
});
// Add view
mutator.addView({
id: 'appView',
type: 'element', // 'element' | 'dynamic' | 'deployment'
target: 'app',
title: 'App Overview',
includes: ['*'], // one `include` rule per item; a leading `include` keyword is stripped
});
// Update element (only specified fields are changed). tags / links / metadata
// apply to the effective values, including `extend` blocks — see "`extend` blocks".
const { changedFiles } = mutator.updateElement('app.db', {
title: 'Updated Title', // REPLACE
summary: 'Updated summary', // REPLACE
description: 'Updated description', // REPLACE
technology: 'PostgreSQL 17', // REPLACE
tags: ['deprecated'], // REPLACE (v0.4.0 BREAKING — was append). Empty [] clears own and extend tags.
links: [{ url: 'https://new.link' }], // REPLACE. Empty [] clears own and extend links.
metadata: { // MERGE + null-deletion
team: 'backend', // upsert (string)
keywords: ['core', 'critical'], // upsert (array)
deprecated: null, // delete the key
},
style: { color: 'red' }, // MERGE per-field (v0.4.0 BREAKING — was full replace)
});
// Update an existing relationship (=> { changedFiles })
mutator.updateRelationship(
{ source: 'app.api', target: 'app.db' },
{
label: 'persists',
description: 'Reads and writes user data',
technology: 'JDBC',
tags: ['internal'], // REPLACE
links: [{ url: 'https://docs.example.com/db' }], // REPLACE
metadata: { sla: '99.9%', owner: null }, // MERGE + null-delete
style: { line: 'dashed', color: 'red' }, // MERGE per-field
},
);
// Remove
mutator.removeRelationship('app.api', 'app.db'); // => { changedFiles }
mutator.removeElement('app.db'); // rejected while other constructs refer to it — see "Removing referenced elements"
// or: mutator.removeElement('app.db', { cascade: true }); // removes the referring view items, steps and instances too
// Rename (=> { fqn, changedFiles }); every reference to the element and its subtree is rewritten — see "Renaming elements"
mutator.renameElement('app.api', 'gateway');
// Move (=> { fqn, changedFiles }) under a new parent, or to the top level of a file — see "Moving elements"
mutator.moveElement('app.gateway', { parent: null, file: 'model.c4' });
// Validate & serialize
const errors = mutator.validate(); // syntax only, synchronous: [] = valid
const records = await mutator.validateModel(); // as `likec4 validate` does: [] = valid
const files = mutator.serialize(); // { 'model.c4': '...' }validate() is a synchronous syntax check. validateModel(options?) checks the loaded files as likec4 validate of LikeC4 1.60.0 does, with LikeC4's own language services, and resolves to what it reports, as ValidationRecord[] (the type is exported):
interface ValidationRecord {
origin: 'language-services' | 'views';
message: string;
file?: string; // located records: the file name as loaded
line?: number; // 1-based
column?: number; // 1-based
}- Every diagnostic of error severity — syntax errors, unresolved references, duplicate names, undeclared kinds and tags, invalid relationships — is a located record (
origin: 'language-services') with LikeC4's message and the position of the diagnostic's start. Warnings are not reported. - Unless
{ layout: false }is given, the views are computed and laid out; an exception escaping that step is an unlocated record (origin: 'views') with the exception's message only. A view LikeC4 fails to lay out without failing the step is logged by LikeC4 and is not an error, as for the command. Console output LikeC4 writes during the check is discarded. Manual layouts are not read, so layout drift is never reported. - The result is empty when LikeC4 accepts the files; language-service records come first, in document order.
- The sources are copied when the method is called: mutations made while the check runs do not change its result, and concurrent calls, on one instance or on several, are independent.
- The promise rejects when the check cannot run (LikeC4's services cannot be built); that is not a record.
const records = await mutator.validateModel({ layout: false });
for (const r of records) {
console.error(r.file ? `${r.file}:${r.line}:${r.column}: ${r.message}` : r.message);
}The deployment model (deployment { ... }: nodes, instances, their relationships and extend <node> blocks) has its own read and write methods — see Deployment model. So have views — their rules, the steps of dynamic views and their removal; see Views.
Every write of the library has a command: each apply operation is one command with the same fields and the same checks, and writes the same files apply writes for that one operation. apply remains the way to run several operations atomically: it checks the whole mutations file first, applies the operations in order, and writes nothing when any of them is rejected. The public reads of the library have commands too (see Read commands), and validate checks a model as likec4 validate does.
Every command loads the files LikeC4 reads — .c4, .likec4 and .like-c4 (the extensions come from LikeC4's language metadata) — from the whole --dir tree, subdirectories included, as one model: references between files of different extensions resolve, and a write chooses its default file among all of them alike. A write command writes every loaded file back under its own relative path and extension, unchanged files byte-identical, to --output when given. A single-operation command writes in place without --output; apply keeps requiring --output or --in-place. A directory without such files is an empty model: validate fails on it with exit code 1 (No LikeC4 files (.c4, .likec4, .like-c4) found in <dir>), a read command succeeds with an empty result, and a write is rejected by the check of its field (no file to write to, an undeclared kind).
The command of an operation is the operation name in kebab-case, except the five commands that existed before the others (add-element, add-relationship, update-element, remove-element, remove-relationship), which keep their names, flags and output.
apply operation |
Command |
|---|---|
addElement |
add-element |
updateElement |
update-element |
removeElement |
remove-element |
renameElement |
rename-element |
moveElement |
move-element |
addKind |
add-kind |
updateKind |
update-kind |
addTag |
add-tag |
renameKind |
rename-kind |
removeKind |
remove-kind |
renameTag |
rename-tag |
removeTag |
remove-tag |
addElementExtend |
add-element-extend |
addRelationshipExtend |
add-relationship-extend |
addRelationship |
add-relationship |
updateRelationship |
update-relationship |
removeRelationship |
remove-relationship |
addView |
add-view |
updateView |
update-view |
removeView |
remove-view |
addViewRule |
add-view-rule |
updateViewRule |
update-view-rule |
moveViewRule |
move-view-rule |
replaceViewRule |
replace-view-rule |
removeViewRule |
remove-view-rule |
updateViewsBlock |
update-views-block |
addViewsBlockStyle |
add-views-block-style |
updateViewsBlockStyle |
update-views-block-style |
removeViewsBlockStyle |
remove-views-block-style |
addGlobalPredicateGroup |
add-global-predicate-group |
addGlobalDynamicPredicateGroup |
add-global-dynamic-predicate-group |
addGlobalStyle |
add-global-style |
addGlobalStyleGroup |
add-global-style-group |
updateGlobalStyle |
update-global-style |
addGlobalRule |
add-global-rule |
updateGlobalRule |
update-global-rule |
removeGlobalRule |
remove-global-rule |
renameGlobal |
rename-global |
removeGlobal |
remove-global |
addViewStep |
add-view-step |
updateViewStep |
update-view-step |
moveViewStep |
move-view-step |
removeViewStep |
remove-view-step |
addViewParallel |
add-view-parallel |
addDeploymentNode |
add-deployment-node |
updateDeploymentNode |
update-deployment-node |
removeDeploymentNode |
remove-deployment-node |
addDeploymentInstance |
add-deployment-instance |
updateDeploymentInstance |
update-deployment-instance |
removeDeploymentInstance |
remove-deployment-instance |
addDeploymentRelationship |
add-deployment-relationship |
updateDeploymentRelationship |
update-deployment-relationship |
removeDeploymentRelationship |
remove-deployment-relationship |
addDeploymentExtend |
add-deployment-extend |
removeDeploymentExtend |
remove-deployment-extend |
The fields of each operation are described in Batch mutations format; likec4-mutator <command> --help lists the flags of a command.
A command's flags are its operation's fields in kebab-case (viewId → --view-id, matchKind → --match-kind), plus --dir, --output and --json. A value is encoded by the kind of the field:
| Field | Flag | Example |
|---|---|---|
| text | --field <text>, taken literally: --title null is the four-letter text, --title '' the empty text |
--title 'Payments API' |
a field that accepts null (removes the property; for moveElement, parent: null is the model level) |
also --unset-field, which passes null; giving both is rejected |
update-view --id index --unset-title |
a number that accepts null (updateView's order) |
--field <number>, plus --unset-field; a value that is not a number, or both flags, is rejected |
update-view --id index --order 3 |
a selector's matchBidirectional, where false differs from leaving it out |
--field true or --field false |
--match-bidirectional false |
a switch that matters only when on (cascade, bidirectional, shared) |
--field, without a value |
--cascade |
a number (occurrence) |
--field <number>, a JSON number |
--occurrence 2 |
tags |
a value that is, as a whole, a JSON array of strings is that list; any other value is a comma-separated list, items trimmed and empty items dropped; --tags '' means not given; --tags '[]' is the empty list |
--tags internal,backend, --tags '["internal"]' |
any other list (includes, whose items may contain commas) and every object or list of objects (links, metadata, style, rule, step, address, position, endpoints) |
the JSON value as the flag's text | --links '[{"url":"https://example.com"}]' |
A flag given twice takes its last value. A value that does not fit its encoding (invalid JSON, a wrong shape, yes for true), a missing required field, an unknown flag, or a field the library rejects fails the command with exit code 1, the reason on stderr and nothing written. A rejected field carries the detail apply gives, with the flag in place of the mutation path:
Error: --rule: expected a JSON value, got "{bad" (Expected property name or '}' in JSON at position 1 (line 1 column 2))
Error: --title: cannot be given together with --unset-title
Error: --tags[1]: tag 'nope' is not declared by a specification of the loaded files (`specification { tag nope }`)
Error: --match-bidirectional: expected true or false, got "yes"
Text output of a command is every line apply prints for its operation (cascade lines and emptied-par lines included), without apply's summary line; when apply prints none, one line <operation>: done. The five older commands keep their own lines (Created element 'app.api', ...); remove-element --cascade lists the removed constructs after them, in the form apply uses.
$ likec4-mutator rename-element --dir ./c4 --fqn app.api --new-name gateway
renameElement: renamed 'app.api' to 'app.gateway'
$ likec4-mutator add-view-rule --dir ./c4 --id index --rule '{"kind":"exclude","expression":"db"}'
addViewRule: doneWith --json, stdout carries only {"operation": <the apply operation name>, "result": <the library method's value, or null when it returns nothing>}:
$ likec4-mutator update-view --dir ./c4 --id index --title Overview --json
{
"operation": "updateView",
"result": {
"changedFiles": [
"model.c4"
]
}
}A rejection prints its reason on stderr and nothing on stdout, with or without --json.
Each public read of the library has a command (serialize aside); get-element has two modes. Flags are the method's parameters in kebab-case. The output is readable text, or with --json the value the method returns, unchanged.
| Command | Library method | Flags |
|---|---|---|
list-elements |
listElements |
--kind, --parent (the parentFqn filter) |
get-element |
getElement |
--fqn |
get-element --source |
getElementSource |
--fqn |
get-relationships |
getRelationships |
--source-fqn, --target-fqn |
get-specification |
getSpecification |
— |
list-views |
listViews |
--type, --file |
list-views-blocks |
listViewsBlocks |
--file |
get-globals |
getGlobals |
— |
get-view |
getView |
--id |
list-deployment-nodes |
listDeploymentNodes |
--kind, --parent-id |
get-deployment-node |
getDeploymentNode |
--id |
get-deployment-node-kind |
getDeploymentNodeKind |
--kind |
list-deployment-instances |
listDeploymentInstances |
--node-id, --element |
get-deployment-instance |
getDeploymentInstance |
--id |
list-deployment-relationships |
listDeploymentRelationships |
--source, --target, --kind |
A get-* command whose construct does not exist exits 1 with the reason on stderr (View 'nope' not found) and nothing on stdout. get-specification of a model without a specification succeeds (--json prints null), and so does an empty list. get-element --source prints the raw DSL text of the element; with --json, that text as a JSON string. An unnamed view is listed by list-views and cannot be addressed by get-view.
likec4-mutator list-elements --dir ./c4 --kind service
likec4-mutator get-element --dir ./c4 --fqn app.api --json
likec4-mutator get-element --dir ./c4 --fqn app.api --source
likec4-mutator list-views --dir ./c4 --type dynamic --jsonCheck the loaded files as likec4 validate (LikeC4 1.60.0) does, with LikeC4's own language services, and report what it reports (see validateModel): syntax errors, unresolved references, duplicate names, undeclared kinds and tags, invalid relationships, and the computation and layout of the views. Warnings are not errors.
likec4-mutator validate --dir ./c4
likec4-mutator validate --dir ./c4 --no-layout
likec4-mutator validate --dir ./c4 --jsonEach error is a line on stderr: file:line:column: message (1-based line and column, LikeC4's message), or the message alone for an error without a location (an exception escaping the computation and layout of the views). The exit code is 1 when there is any error; otherwise 0, with All files are valid (N file(s) checked) on stdout.
bad.likec4:2:7: Could not resolve reference to ElementKind named 'nokind'.
--json prints only the array of records on stdout ([] when valid), and stderr stays empty; a located record has file, line and column, an unlocated one only origin and message:
[
{
"origin": "language-services",
"message": "Could not resolve reference to ElementKind named 'nokind'.",
"file": "bad.likec4",
"line": 2,
"column": 7
}
]--no-layout skips the computation and layout of the views; only the language-service errors are reported. When the check itself cannot run, the command prints Error: <reason> on stderr and exits 1.
Parity scope. The verdict equals likec4 validate for the files this command loaded. LikeC4's own directory walk skips some directories (node_modules, .git, .svn, .yarn, .pnpm) and applies a project configuration (likec4.config.json); this command loads the whole --dir tree and reads no project configuration. Manual layouts are not read, so layout drift is never reported. A tree with such directories, a project configuration or manual layouts can therefore get a different verdict from likec4 validate.
Add a new element, at the model level or as a child of --parent. --kind and --id are required; every other field of addElement has its flag.
likec4-mutator add-element --dir ./c4 \
--parent app \
--kind service \
--id myApi \
--title 'My API' \
--summary 'Short label shown on diagrams' \
--description 'REST API' \
--technology 'TypeScript' \
--tags internal,backend \
--links '[{"url":"https://docs.example.com/api"}]' \
--output ./outAdd a relationship between two elements; --source and --target are required, and every other field of addRelationship (kind, direction, placement, file, style, ...) has its flag.
likec4-mutator add-relationship --dir ./c4 \
--source app.myApi \
--target app.db \
--label 'reads/writes' \
--technology JDBC \
--output ./outUpdate properties of an existing element. Only the flags you provide are changed; all other properties are left intact. --tags replaces all tags of the element, including those added by extend blocks (see extend blocks). Every loaded file is written to the output directory.
likec4-mutator update-element --dir ./c4 --fqn app.api \
--title 'New Title' \
--description 'New description' \
--technology 'Go' \
--summary 'Updated summary' \
--tags deprecated,legacy \
--output ./outRemove an element (and its entire body block) from the model. A removal that other constructs refer to fails, naming them; --cascade removes them too, and lists them after the removal line (see removeElement).
likec4-mutator remove-element --dir ./c4 --fqn app.api --output ./out
likec4-mutator remove-element --dir ./c4 --fqn app.api --cascadeRemove a relationship matched by source and target FQN (searched across all files), together with extend a -> b blocks that applied only to it. When several relationships match, the command fails listing them; select one with the selector flags of removeRelationship (--match-kind, --match-title, --match-bidirectional, --position).
likec4-mutator remove-relationship --dir ./c4 --source app.api --target app.db --output ./out
likec4-mutator remove-relationship --dir ./c4 --source app.api --target app.db --match-bidirectional trueApply a batch of mutations from a JSON file. This is the most powerful command: every write of the library is an op, with all its options.
# Write to a separate output directory
likec4-mutator apply --dir ./c4 --mutations mutations.json --output ./out
# Overwrite source files in-place
likec4-mutator apply --dir ./c4 --mutations mutations.json --in-placeThe JSON file contains a mutations array. Each mutation has an op field and operation-specific parameters. Fields not listed for an op below (including inside style and links entries), and top-level keys other than mutations, are rejected before any .c4 file is touched, so a misspelled field such as tag fails the command instead of being silently ignored.
The whole file is validated before any mutation is applied: a missing required field or a value of the wrong type (e.g. "tags": "internal" instead of ["internal"]) aborts with exit code 1 and an error naming its location, e.g. mutations[2].links[0].url. Nothing is written in that case.
Adds a new element inside a parent, or at model level when parent is absent. All fields except op, kind, id are optional. Without title, LikeC4 shows the kind's title, else the name. file (a loaded file name, exactly as loaded) chooses the file of a model-level element — its first model block, else a new one at its end; without it the default file is used (see Placement and file choice). file together with parent fails on mutations[i].file: a child goes into the file of its parent.
{
"op": "addElement",
"parent": "app",
"kind": "service",
"id": "newApi",
"title": "New API",
"summary": "Short description for diagram",
"description": "Detailed description",
"technology": "TypeScript / Express",
"tags": ["internal", "backend"],
"links": [
{ "url": "https://github.com/example/api", "label": "Repository" },
{ "url": "https://docs.example.com/api" }
],
"style": {
"shape": "rectangle",
"color": "blue",
"icon": "tech:typescript",
"opacity": "80%",
"border": "solid",
"multiple": false,
"size": "md",
"padding": "sm",
"textSize": "md",
"iconPosition": "top",
"iconColor": "blue",
"iconSize": "sm"
},
"metadata": {
"owner": "platform-team",
"version": "v2",
"keywords": ["internal", "critical"]
}
}Updates properties of an existing element. Only specified fields are changed. tags, links and metadata apply to the effective values, including contributions of extend blocks (see extend blocks).
| Field | Semantics |
|---|---|
title, summary, description, technology |
REPLACE. Every declaration is rewritten (a body may repeat a property; LikeC4 reads the last one). A summary or technology written after the title (name = kind 'title' 'summary' 'technology') is what LikeC4 reads, so it is replaced there; an empty summary no longer overrides the body and is written into the body as well. |
tags |
REPLACE (v0.4.0 BREAKING — was append). [] clears all tags written for it (kind defaults still apply, see Specification defaults). |
links |
REPLACE. [] clears all links written for it (the kind links then apply). |
metadata |
MERGE. Map a key to null to delete it; map to a string or string[] to upsert. Keys absent from the patch are preserved verbatim (including original array formatting), and so are comments in the block: patched keys are edited in place, new keys added at the end of the block. A value with line breaks is written as a Markdown string (see Multi-line metadata values). |
style |
MERGE per-field (v0.4.0 BREAKING — was full replace). Pass a complete style object to reproduce the old replace-all behaviour. The first style { } block of the body (the one LikeC4 reads) is edited in place: a patched field gets its new value wherever the block declares it, a missing field is added at the end of the block, and other fields, comments, : / ; separators and indentation keep their text. |
{
"op": "updateElement",
"fqn": "app.api",
"title": "Updated Title",
"description": "Updated description",
"technology": "Go / Fiber",
"tags": ["deprecated"],
"links": [{ "url": "https://migration.example.com", "label": "Migration Guide" }],
"metadata": {
"team": "backend",
"keywords": ["internal", "critical"],
"deprecatedKey": null
},
"style": { "color": "red", "border": "dashed" }
}Updates fields on an existing relationship. Required: op, source, target, plus at least one update field. The selector fields are the same as for removeRelationship: when more than one relation matches source/target, supply matchKind, matchTitle, matchBidirectional and, for relationships nothing else tells apart, position. label, tags, links and metadata also apply to extend a -> b { ... } blocks of the relationship (see Relationships).
| Field | Semantics |
|---|---|
label, description, technology |
REPLACE. Every body declaration is rewritten (a body may repeat a property; LikeC4 reads the last one). A description or technology written after the title (a -> b 'title' 'description' 'technology') is what LikeC4 reads, so it is replaced there; an empty description no longer overrides the body and is written into the body as well. |
tags |
REPLACE. [] clears all tags written for it (kind defaults still apply, see Specification defaults). |
links |
REPLACE. [] clears all links written for it (the kind links then apply). |
metadata |
MERGE with null-deletion (same as updateElement). |
style |
MERGE per-field, in place (same as updateElement). |
{
"op": "updateRelationship",
"source": "app.api",
"target": "app.db",
"matchTitle": "reads/writes",
"label": "persists",
"description": "Reads and writes user data",
"technology": "JDBC",
"tags": ["internal"],
"links": [{ "url": "https://docs.example.com/db" }],
"metadata": { "sla": "99.9%", "deprecatedOwner": null },
"style": { "line": "dashed", "color": "red" }
}Removes an element and all its children. With "cascade": true the constructs that refer into the removed subtree are removed too, as the library's removeElement(fqn, { cascade: true }) does (see Removing referenced elements); without it such a reference fails on mutations[i].fqn and nothing is written.
{
"op": "removeElement",
"fqn": "app.oldService",
"cascade": true
}The four remove ops (removeElement, removeDeploymentNode, removeDeploymentInstance, removeView) take cascade (a boolean). A cascade prints one more line listing the references it removed, as file:line:column (role) at their positions before the op.
Renames an element and rewrites the references to it and to its subtree, as the library's renameElement(fqn, newName) does (see Renaming elements). A rejection fails on mutations[i].newName or mutations[i].fqn and nothing is written.
{
"op": "renameElement",
"fqn": "app.api",
"newName": "gateway"
}Moves an element under parent (an element FQN), or with "parent": null to the top level of file (a loaded file; the element's current file when absent), as the library's moveElement(fqn, { parent, file }) does (see Moving elements). parent is required, a string or null. A rejection fails on mutations[i].fqn, .parent or .file and nothing is written.
{
"op": "moveElement",
"fqn": "app.api",
"parent": null,
"file": "core.c4"
}Contribute through an extend block, as the library's addElementExtend(fqn, { file, … }) and addRelationshipExtend(selector, { file, … }) do (see Creating blocks). addRelationshipExtend takes the selector fields of updateRelationship (source, target, matchKind, matchTitle, matchBidirectional, position) and shared. A rejection fails on mutations[i].<field> and nothing is written.
[
{ "op": "addElementExtend", "fqn": "app", "file": "ext/ops.c4", "tags": ["internal"] },
{ "op": "addRelationshipExtend", "source": "app.api", "target": "app.db", "matchTitle": "reads", "file": "ext/ops.c4", "metadata": { "runbook": "db-1" } }
]Declare a kind or a tag and change a kind's defaults, as the library's addKind(type, name, { file, … }), updateKind(type, name, patch) and addTag(name, { file }) do (see Specification defaults › Writing). type is element, relationship or deploymentNode; in updateKind a string field set to null removes the default, and at least one field must be given. A rejection fails on mutations[i].<field> (type, name, summary, title, tags[i], links[i].url, file) and nothing is written.
[
{ "op": "addTag", "name": "backend" },
{ "op": "addKind", "type": "element", "name": "service", "title": "Service", "tags": ["backend"], "file": "spec.c4" },
{ "op": "updateKind", "type": "relationship", "name": "async", "title": null, "technology": "Kafka" }
]Rename or remove a kind or a tag, as the library's renameKind(type, name, newName), removeKind(type, name), renameTag(name, newName) and removeTag(name) do (see Renaming and removing kinds and tags). Tag names are written without #. A rejection fails on mutations[i].<field> (type, name, newName) and nothing is written; the removal of a used kind or tag fails on mutations[i].name, naming its uses.
[
{ "op": "renameKind", "type": "element", "name": "vm", "newName": "machine" },
{ "op": "renameTag", "name": "hot", "newName": "warm" },
{ "op": "removeKind", "type": "relationship", "name": "legacy" },
{ "op": "removeTag", "name": "unused" }
]Adds a relationship between two elements. All fields except op, source, target are optional. It is written at the end of the first model block of the first file, in LikeC4's document order, that has one; else in a new model block at the end of the first file. The fields kind, kindForm (bracket or dot), bidirectional, placement (top or nested), file and shared are those of the library (see Relationship forms and placement); a rejection fails on mutations[i].<field> and nothing is written.
[
{ "op": "addRelationship", "source": "app.api", "target": "app.db", "label": "reads", "kind": "calls", "bidirectional": true },
{ "op": "addRelationship", "source": "app.api", "target": "app.db", "label": "writes", "placement": "nested", "kind": "calls", "kindForm": "dot" },
{ "op": "addRelationship", "source": "app", "target": "ext", "label": "uses", "file": "model/app.c4", "shared": true }
]{
"op": "addRelationship",
"source": "app.api",
"target": "app.db",
"label": "reads/writes",
"description": "Queries user data",
"technology": "JDBC",
"tags": ["internal"],
"links": [{ "url": "https://docs.example.com/db", "label": "DB Docs" }],
"metadata": { "sla": "99.9%", "owners": ["platform", "data"] },
"style": {
"line": "dashed",
"color": "red",
"head": "diamond",
"tail": "none"
}
}Removes a relationship between two elements (matched by absolute source and target FQN, across all files; the reference text as written is accepted as a fallback). Exactly one relationship must match; extend blocks that applied only to it are removed with it.
| Selector field | Semantics |
|---|---|
source, target |
Required. A bidirectional relationship (<->) matches them in either order. |
matchKind |
The relationship kind as written (-[kind]-> or .kind). |
matchTitle |
The inline title as written (not the kind's default title). |
matchBidirectional |
true: only <-> relationships; false: only one-way ones. |
position |
{ "file", "line", "column" }, 1-based: where the relationship's declaration starts. Inside a mutations file it refers to the sources after the preceding mutations. |
More than one match fails with the path of the mutation's source and lists every candidate as file:line:column (with its kind, title and direction); pass one of them back as position to select it. No match fails on source (on position when one is given). Nothing is written in either case.
{
"op": "removeRelationship",
"source": "app.api",
"target": "app.oldService",
"matchTitle": "legacy sync",
"position": { "file": "model.c4", "line": 42, "column": 3 }
}Adds a new view. Type can be element, dynamic, or deployment. Required: op, id, type; target, extends, title, description, includes, autoLayout (a string, or null for none), file and folder (a string, or null for a block without folder) are optional, with the meaning and checks of the library's addView (see Adding views).
{
"op": "addView",
"id": "apiView",
"type": "element",
"target": "app.api",
"title": "API Overview",
"includes": ["*", "app.db", "app.api -> app.db"]
}includes is an array of strings; each item becomes one include rule of the view, in order. An item is what follows the keyword: one or more comma-separated predicates, as LikeC4 accepts them after include ("*", "app.db", "app.*, app.api -> app.db"). One leading include keyword followed by whitespace is stripped, so "include *" writes include *, not include include * ("include*" is not stripped and is rejected); surrounding whitespace is trimmed. Each item must form exactly one include rule of the view's type: an item that is empty or only include, that LikeC4 cannot parse, or that would add anything beyond that rule (another rule such as "* exclude x" or "*\n autoLayout LeftRight", a view property, or another view) is rejected before any file is touched (exit code 1, path mutations[i].includes[j]). Without includes (or with []) an element view gets include * and other view types get no include rule. The library's addView({ includes }) handles items the same way and throws on such an item.
Every view write of the library is an op with the same fields as its arguments — id, then its options (see Views › Writing for what each write does and rejects):
| op | fields besides op and id |
|---|---|
updateView |
title, description, autoLayout (a string, or null to remove), tags, links, order (a number or null), routing, variant (null removes), folder (a string, or null for a block without folder; see View folders and views blocks) |
addViewRule |
rule (a rule of any kind but autoLayout, see Writing rules: only the fields of its kind), before or into { index?, path?, text? } |
replaceViewRule |
address { index?, path?, text? }, rule |
updateViewRule |
address, patch (see Writing rules: kind and only the fields of that kind; null removes) |
moveViewRule |
from { index?, path?, text? }, to (a boundary path) |
removeViewRule |
address |
removeView |
cascade (boolean) |
addViewStep |
step { source, target, direction?, kind?, kindForm?, title?, description?, technology?, notes?, notation?, navigateTo?, color?, line?, head?, tail? }, path |
updateViewStep |
address { path, segment?, text? }, patch (the step fields; null removes kind, title, a body string, navigateTo or a style field) |
moveViewStep |
from (a step address), to (a path) |
removeViewStep |
address |
addViewParallel |
path, statements (top-level paths), steps; at least one of the last two |
The views block ops address a block instead of a view: block { file, index } in place of id (see View folders and views blocks):
| op | fields besides op and block |
|---|---|
updateViewsBlock |
folder (a string, or null to remove) |
addViewsBlockStyle |
rule (a style or globalStyle rule), before { index, text? } |
updateViewsBlockStyle |
address { index, text? }, patch (a style or globalStyle patch) |
removeViewsBlockStyle |
address |
The global ops name a definition by name (see Global block); file is optional:
| op | fields besides op |
|---|---|
addGlobalPredicateGroup, addGlobalDynamicPredicateGroup |
name, predicates (include / exclude rules), file |
addGlobalStyle |
name, targets, style, notation, file |
addGlobalStyleGroup |
name, styles (style rules), file |
updateGlobalStyle |
name, patch { targets?, style?, notation? } |
addGlobalRule |
type, name, rule, before { index, text? } |
updateGlobalRule |
type, name, address { index, text? }, rule (a whole predicate, or a style patch in a style group) |
removeGlobalRule |
type, name, address |
renameGlobal |
type, name, newName |
removeGlobal |
type, name, cascade (boolean) |
{ "op": "addViewStep", "id": "checkout", "step": { "source": "web", "target": "api", "title": "Pays" }, "path": [2, 0] }The whole file is checked before any file is touched: unknown fields (also inside rule, address, before, step, patch, links), values of the wrong type and missing required fields are rejected with their full JSON path, such as mutations[1].address.path[0]. The checks that need the loaded files — references, declared kinds, tags and colors, the par block rules — run when the op is applied; a rejected op exits 1, names mutations[i].<path> and writes nothing. moveViewStep and removeViewStep print the par blocks they removed.
Every deployment write of the library is an op with the same fields as its options (see Deployment model › Writing for what each write does and rejects). The arguments the library takes before its options are fields too:
| Op | Fields besides the library options | Library call |
|---|---|---|
addDeploymentNode |
parent (optional: without it the node is a root node) |
addDeploymentNode(parent ?? null, opts) |
updateDeploymentNode |
id |
updateDeploymentNode(id, patch) |
removeDeploymentNode |
id, cascade |
removeDeploymentNode(id, { cascade }) |
addDeploymentInstance |
node |
addDeploymentInstance(node, opts) |
updateDeploymentInstance |
id |
updateDeploymentInstance(id, patch) |
removeDeploymentInstance |
id, cascade |
removeDeploymentInstance(id, { cascade }) |
addDeploymentRelationship |
source, target |
addDeploymentRelationship(source, target, opts) |
updateDeploymentRelationship |
source, target, matchKind, matchTitle |
updateDeploymentRelationship({ source, target, kind: matchKind, title: matchTitle }, patch) |
removeDeploymentRelationship |
source, target, matchKind, matchTitle |
removeDeploymentRelationship({ source, target, kind: matchKind, title: matchTitle }) |
addDeploymentExtend |
node |
addDeploymentExtend(node, { file, tags, links, metadata }) |
removeDeploymentExtend |
— | removeDeploymentExtend({ node, file, occurrence }) |
sourceandtargetare endpoint objects{ "id": ..., "element": ... }:idis the deployment id of a node or instance,element(optional) the FQN of an element inside the instance's element. Other keys of an endpoint are rejected (mutations[i].source.x).- The selector of a deployment relationship names its kind and title
matchKindandmatchTitle, as inupdateRelationship, becausetitleofupdateDeploymentRelationshipis the new title. Both ops use the same selector. - An update needs at least one patch field;
addDeploymentExtendneeds at least one tag, link or metadata key. Otherwise the op is rejected atmutations[i]. occurrenceis a whole number from 1;bidirectionalis a boolean.addDeploymentInstancehas nofilefield (an instance is written in its node).- A value the library rejects is reported at the same path as its option:
mutations[i].metadata.<key>,mutations[i].file,mutations[i].source.id,mutations[i].target.element,mutations[i].occurrence; a selector that matches no relationship or several atmutations[i].source.
{
"mutations": [
{ "op": "addDeploymentNode", "parent": "prod", "name": "vm3", "kind": "vm", "title": "VM 3" },
{ "op": "addDeploymentInstance", "node": "prod.vm3", "element": "app.api", "name": "api" },
{
"op": "addDeploymentRelationship",
"source": { "id": "prod.vm3.api", "element": "app.api.handler" },
"target": { "id": "prod.vm2.db" },
"kind": "calls",
"title": "writes"
},
{
"op": "updateDeploymentRelationship",
"source": { "id": "prod.vm1.api" },
"target": { "id": "prod.vm2.db" },
"matchTitle": "reads",
"title": "queries"
},
{ "op": "addDeploymentExtend", "node": "prod.vm1", "file": "deployment.c4", "tags": ["internal"] },
{ "op": "removeDeploymentExtend", "node": "prod.vm2", "file": "deployment.c4", "occurrence": 1 }
]
}{
"mutations": [
{ "op": "addElement", "parent": "app", "kind": "service", "id": "gateway", "title": "API Gateway", "description": "Routes requests", "technology": "nginx" },
{ "op": "addRelationship", "source": "app.gateway", "target": "app.api", "label": "proxies" },
{ "op": "updateElement", "fqn": "app.api", "technology": "Go / Fiber" },
{ "op": "updateRelationship", "source": "app.gateway", "target": "app.api", "matchTitle": "proxies", "metadata": { "sla": "99.9%" } },
{ "op": "addView", "id": "gatewayView", "type": "element", "target": "app.gateway", "title": "Gateway" },
{ "op": "removeRelationship", "source": "app.api", "target": "app.legacy" },
{ "op": "removeElement", "fqn": "app.legacy" }
]
}Which LikeC4 DSL constructs the library can read, add, update and remove — rule by rule of the LikeC4 grammar, including what is not supported yet — is listed in the DSL coverage matrix.
| Property | Type | addElement | updateElement | DSL syntax |
|---|---|---|---|---|
| title | string | yes | yes (replace) | = kind 'Title' |
| summary | string | yes | yes (replace) | summary 'text' or = kind 'Title' 'summary' |
| description | string | yes | yes (replace) | description 'text' |
| technology | string | yes | yes (replace) | technology 'text' or = kind 'Title' 'summary' 'technology' |
| tags | string[] | yes | yes (replace) | #tagname |
| links | {url, label?}[] | yes | yes (replace) | link url 'label' |
| style | ElementStyle | yes | yes (merge per-field) | style { shape ... } |
| metadata | Record<string, string | string[]> |
yes | yes (merge, null deletes a key) |
metadata { key 'val' } or metadata { key ['v1', 'v2'] } |
getElement, listElements and getRelationships report title, summary, description and technology as LikeC4 reads them: common indentation removed and trimmed, a technology written inline (= kind 'Title' 'summary' 'technology', -> target 'label' 'description' 'technology') joined into one line, a Markdown string ('''...''') as its content. summary ' text ' reads as 'text'; a whitespace-only Markdown summary or description reads as ''; an empty Markdown title or technology is no value.
A metadata value (or array item) with line breaks — YAML, JSON, any multi-line text — is written as a LikeC4 Markdown string, one level deeper than its key, wherever the library writes metadata (addElement, addRelationship, updateElement, updateRelationship):
mutator.updateElement('app', { metadata: { manifest: 'apiVersion: v1\nkind: Deployment' } }); metadata {
manifest '''
apiVersion: v1
kind: Deployment
'''
}
LikeC4 (and the library) read it back as the value written. As for any metadata value, LikeC4 removes the indentation shared by all lines and trims the value, so leading and trailing whitespace and common indentation are not kept. Line breaks are written as the file's line ending, so in a file with CRLF line endings the value reads back with \r\n line breaks. A value without line breaks stays a single-quoted string.
| Property | Values |
|---|---|
| shape | rectangle, component, person, browser, mobile, cylinder, storage, queue, bucket, document |
| color | primary, secondary, muted, slate, blue, indigo, sky, red, gray, green, amber, or a custom color declared in a specification (color brand #3b82f6) |
| icon | An icon of LikeC4's built-in library (tech:postgresql, aws:lambda), a URI (https://…, /…, ./…, ../…, @alias/…; not file://) or none |
| opacity | Percentage from 0% to 100% (40%) |
| border | solid, dashed, dotted, none |
| multiple | true, false (a boolean) |
| size | xs, sm, md, lg, xl, xsmall, small, medium, large, xlarge |
| padding | Same as size |
| textSize | Same as size |
| iconPosition | left, right, top, bottom |
| iconColor | Same as color |
| iconSize | Same as size |
Values are checked before writing (see Rejected writes); the keyword sets are taken from the grammar of the installed LikeC4.
| Property | Type | addRelationship | updateRelationship | DSL syntax |
|---|---|---|---|---|
| label | string | yes | yes (replace) | -> target 'label' |
| description | string | yes | yes (replace) | description 'text' or -> target 'label' 'description' |
| technology | string | yes | yes (replace) | technology 'text' or -> target 'label' 'description' 'technology' |
| tags | string[] | yes | yes (replace) | #tagname |
| links | {url, label?}[] | yes | yes (replace) | link url 'label' |
| metadata | Record<string, string | string[]> |
yes | yes (merge, null deletes a key) |
metadata { key 'val' } or metadata { key ['v1', 'v2'] } |
| style | RelationshipStyle | yes | yes (merge per-field) | style { line ... } |
addRelationship(source, target, label?, opts) also takes the kind, the direction and the place of the new relationship:
mutator.addRelationship('app.api', 'app.db', 'reads', { kind: 'calls' }); // app.api -[calls]-> app.db 'reads'
mutator.addRelationship('app.api', 'app.db', 'reads', { kind: 'calls', kindForm: 'dot' }); // app.api .calls app.db 'reads'
mutator.addRelationship('app.api', 'ext', 'syncs', { bidirectional: true }); // app.api <-> ext 'syncs'
mutator.addRelationship('app.api', 'ext', 'syncs', { kind: 'calls', bidirectional: true }); // app.api -[calls]<-> ext 'syncs'
mutator.addRelationship('app.api', 'app.db', 'reads', { placement: 'nested' }); // inside app.api: -> db 'reads'
mutator.addRelationship('app', 'ext', 'uses', { file: 'model/app.c4' }); // top level of that filekind. A declared relationship kind, written-[kind]->by default or.kindwithkindForm: 'dot'. The dot form has no bidirectional spelling, sobidirectionalwithkindForm: 'dot'is rejected.bidirectional. Writes<->, or-[kind]<->with a kind.placement: 'nested'. Writes the relationship without a source inside the body of the source element's declaration:-> target,<-> target,-[kind]-> target,-[kind]<-> targetor.kind target.- A source without a body is given one, keeping its declaration form.
- The target is written in the shortest form that resolves there to the requested element: its name (a sibling), else a longer tail of its FQN (
other.api), else the FQN. fileis rejected withnested: the source's declaration decides the file.
file. Places a top-level relationship at the end of the firstmodelblock of that loaded file. Amodelblock is created when the file has none. Withoutfile, the default file is used (see Placement and file choice).shared. When anextend a -> bblock already has the identity of the new relationship — endpoints, kind, title (the kind's title when it has none), direction — LikeC4 would apply the block's tags, links and metadata to it. Such a write is rejected onshared, withrelatedlisting the blocks (construct: 'extend-block'). Withshared: trueit is written, and the blocks apply.
The endpoints are resolved from the first model block of the chosen (top-level) or default (nested) file, as for a top-level relationship.
updateRelationship(selector, patch) and removeRelationship(selector) address exactly one model relationship of the workspace (removeRelationship(source, target) is the same as { source, target }):
mutator.removeRelationship({ source: 'app.api', target: 'app.db', matchTitle: 'reads' });
try {
mutator.updateRelationship({ source: 'app.api', target: 'app.db' }, { technology: 'JDBC' });
} catch (e) {
if (e instanceof RelationshipAmbiguityError) e.candidates; // [{ file, line, column, kind?, title?, effectiveTitle?, bidirectional }, ...]
}source,target— the absolute FQNs, else the reference text as written. A bidirectional relationship matches them in either order.matchKind— the kind as written (-[kind]->or.kind);matchTitle— the inline title as written, not the kind's title;matchBidirectional—truefor<->relationships only,falsefor one-way ones only.position—{ file, line, column }, 1-based: where the relationship's declaration starts. It tells apart relationships no other field does.- Result. Both return
{ changedFiles }: the files whose text changed, in load order — forremoveRelationshipthe file of the declaration and the files of theextend a -> bblocks removed with it. The changes are in memory;serialize()gives the texts. - Outcome. No match is an
InvalidWriteErroronpositionwhen one was given, else onsource. More than one match is aRelationshipAmbiguityError(anInvalidWriteError) onsource. Itscandidateslist every match in LikeC4's document order, then source order. Passing one candidate's position back, with the same other fields, selects it.
Deployment relationships have their own selector (see Updating deployment relationships).
| Property | Values |
|---|---|
| line | solid, dashed, dotted |
| color | Same as the element color |
| head | normal, onormal, diamond, odiamond, crow, open, vee, dot, odot, none |
| tail | Same as head |
getElement / listElements and getRelationships report styles as LikeC4 1.60.0's model holds them before theme defaults:
const api = mutator.getElement('app.api')!;
api.ownStyle; // { color: 'red', icon: 'tech:go' } — the first style { } block, then a body-level icon
api.fromSpecification?.style; // the kind's style { } block
api.style; // effective: the kind's style overridden field by field by the own style
const [rel] = mutator.getRelationships({ sourceFqn: 'app.api' });
rel.ownStyle; // { line: 'dashed' } — the relationship's first style { } block
rel.fromSpecification?.style; // line, color, head and tail written in the relationship kind
rel.fromSpecification?.multiple; // the relationship kind's multiple flag, as written
rel.style; // effective; a bidirectional relationship always has a tail- Element. The own style is the first
style { }block (a later property overrides an earlier one), then a body-levelicon. The bodyiconwins overstyle { icon }, as in LikeC4. - Relationship. The effective style is the kind's
line,color,headandtailoverridden by the relationship's own. A bidirectional relationship gets atail: the one written, else thehead, else'normal'. - Values. As written: opacity as
'40%', a size alias as its token. Theme defaults and configuredstyles.defaultsare not applied. An absent field is no value. - Where kind styles appear. The kind's style and
multipleare reported on the element or relationship, infromSpecification.getSpecification()keeps reporting names only. - Updating an icon.
updateElement(fqn, { style: { icon } })on an element that has a body-leveliconrewrites thaticonand adds nostyle { icon }; LikeC4 would warnRedundant as icon defined on elementabout one. Astyle { icon }already next to it is left as written. An element without a bodyicongets the icon in its style block, as before.
A kind declared in a specification block can carry defaults, and LikeC4 applies them to every element or relationship of that kind:
specification {
element service {
#backend
title 'Service'
technology 'Node'
link https://wiki.example.com/services 'Service guide'
}
relationship async {
#queue
title 'Asynchronous'
technology 'Kafka'
}
tag backend
tag queue
tag critical
}
model {
api = service {
#critical
}
db = service 'DB'
api -[async]-> db
}
getElement / listElements / getRelationships report the values LikeC4 1.60.0 computes from them, and fromSpecification tells where they come from:
const api = mutator.getElement('api')!;
api.title; // 'Service'
api.technology; // 'Node'
api.tags; // ['backend', 'critical']
api.links; // [{ url: 'https://wiki.example.com/services', label: 'Service guide' }]
api.fromSpecification; // { kind: 'service', file: 'spec.c4', sourceRange: {...}, title: 'Service', technology: 'Node', tags: ['backend'], links: [...] }
const [rel] = mutator.getRelationships({ sourceFqn: 'api', targetFqn: 'db' });
rel.title; // 'Asynchronous'
rel.tags; // ['queue']Rules (LikeC4's own, applied before any extend block):
| Property | Element | Relationship |
|---|---|---|
title |
own when non-empty (after dedent and trim); else the kind's when non-empty; else the element name — so an element title is always defined |
own when non-empty; else the kind's; else own ('' or none) |
summary |
own, else the kind's. An empty summary written after the title (x = s 'T' '') is no summary; an empty body summary '' is a summary |
— (a relationship kind has none) |
description |
own (an empty body description '' included), else the kind's |
own (an empty one in the body included; an empty one written after the title is none), else the kind's |
technology |
own ('' included), else the kind's |
own ('' included), else the kind's |
tags |
the kind's, then own, then extend blocks — without duplicates |
same |
links |
own; the kind's only when the element has none of its own; then extend blocks |
same, with the extend link rule for relationships |
metadata |
not affected (a kind declares none) | not affected |
fromSpecification(KindDefaults) holds the kind name, its file andsourceRange, the strings normalized like the effective values, and tags and links as written. It is present whenever a specification declares the kind (also without defaults) and absent otherwise: an element of an undeclared kind (LikeC4 leaves it out of its model; the library still reports it, with its name as title), a relationship without a kind or with an undeclared one.- A kind declared more than once (a LikeC4 validation error the library does not report) is taken as LikeC4's model builder takes it: the declaration of the last file (ordered as for
extendblocks); within a file the last one for an element kind, the first one for a relationship kind. - The kind's
styleis reported infromSpecification.style, and a relationship kind'smultipleinfromSpecification.multiple; the effective style combines it with the own one (see Reading styles). - Not covered:
notationdefaults (not read) and the technology LikeC4 derives from an element's icon. With the project settinginferTechnologyFromIcon(on by default), LikeC4 replaces an element's missing or empty technology by one derived from its icon (tech:postgresql→Postgresql). The library does not read project settings and reports the technology as written or inherited from the kind: an owntechnology ''is reported as''.
Kinds and tags are declared and their defaults changed with their own calls:
mutator.addTag('backend'); // => { changedFiles }
mutator.addKind('element', 'service', { // 'element' | 'relationship' | 'deploymentNode'
title: 'Service', summary: 'Runs code', description: 'A service', technology: 'Node',
tags: ['backend'], links: [{ url: 'https://wiki.example.com/services', label: 'Service guide' }],
file: 'spec.c4', // optional
});
mutator.updateKind('relationship', 'async', { title: null, technology: 'Kafka' });- Where. A new kind or tag goes to the end of the first
specificationblock offile, else of the first file in LikeC4's document order that has aspecificationblock, else of the first file with amodelblock, else of the first file; a block is created when that file has none, never a second one in a file (LikeC4 warnsPrefer one specification per document). - Names. A name must be one LikeC4's grammar accepts for that declaration —
element modelis accepted,element viewis not — and a kind name none of LikeC4's reserved words (this,it,self,super,likec4lib,global), which it rejects for kinds but not for tags. Element kinds, relationship kinds, deployment node kinds and tags are separate name spaces: a name is taken only by a declaration of the same type, in any loaded file. - Defaults.
title,summary(not for a relationship kind, which LikeC4 gives none),description,technology,tags(declared) andlinks.updateKindedits the one declaration of the kind where it is: a string replaces the kind's value andnullremoves it;tagsandlinksreplace the written ones ([]removes them). The kind's style,notation,multipleand colors are kept as written. - Rejected (
InvalidWriteError, nothing changed): ontype, a type other than the three; onname, a name the grammar does not accept, a name already declared for the type, an update of an undeclared kind or of one declared more than once; onpatch, an empty update; onsummary, a relationship kind summary; ontags[i]/links[i].url, an undeclared tag or an invalid link; onfile, a file that is not loaded; ontitle, a relationship kind title change that would make anextend a -> bblock start or stop applying to a relationship of that kind written without a title — LikeC4 matches the blocks by the title the relationship takes from its kind — withrelatedlisting those blocks (construct: 'extend-block').
updateElement and updateRelationship edit the declaration and its extend blocks as described below, never the specification. The patch is written as given, and the effective value afterwards follows the rules above:
| Patch | Effective value after the update |
|---|---|
tags: T |
kind tags, then T, without duplicates — tags: [] leaves the kind tags |
links: L |
L when non-empty; links: [] brings back the kind links |
element title: '' / relationship label: '' |
the kind title; for an element of a kind without one, the element name |
element summary: S / description: S |
S, '' included when written in the body (an empty summary written after the title reads as the kind summary) |
element technology: S, relationship description: S / technology: S |
S, '' included (an empty relationship description written after the title reads as the kind description) |
metadata |
as without kind defaults |
mutator.renameKind('element', 'vm', 'machine'); // => { changedFiles }
mutator.renameTag('hot', 'warm'); // names without '#'
mutator.removeKind('relationship', 'calls');
mutator.removeTag('legacy');Where a kind or tag is named. A rename rewrites, and a removal looks for, every place where a reference names the kind or tag, in every loaded file:
- the kind token of an element or deployment node declaration (
api = vm 'API',vm api 'API'); - the kind of a relationship connector (
-[calls]->,-[calls]<->,.calls) of a model, deployment orextendrelationship, a dynamic step or a relation predicate; - every tags list (
#hot): of elements, relationships, deployment nodes, instances and deployment relationships, views,extendblocks and kind defaults; - the expressions
element.kind,element.tag,where … kind is,where … tag is, relationwherekind and tag conditions, participant kind and tag conditions (source.kind is vm) — negated forms (!=,!==,is not,not (…)) included — in include and exclude rules, style rule targets andranktargets.
Each place has a type: an element kind, a deployment node kind, a relationship kind or a tag. where … kind is and participant kind conditions name element kinds and deployment node kinds at once (LikeC4 matches them by name against both). A rename rewrites the places of the kind's own type and, for an element or deployment node kind, these shared conditions; they never name a relationship kind. A same-spelled name of another type (a tag x beside a kind x, an element kind vm beside a deployment node kind vm) is untouched, and so is text inside string and markdown values. A tag keeps its color block; each changed file is written once.
Element and deployment node kinds with one name. When the old or the new name is also a kind of the other of these two types, LikeC4 would match a shared condition against both. Neither rewriting it nor keeping it preserves what it selects, so the rename is rejected while such a condition names the old or the new name. related lists the conditions (construct: 'where-condition'). The field is name when the old name is the other type's, else newName. A kind condition written where the library does not resolve references — an import, a dynamic view's flow block other than par, unparsed text — that names the new name while the new name is the other type's rejects the rename on newName the same way, without related. Without such a condition the rename is accepted.
Removal. Only a kind or tag that no place names is removed. The emptied specification { } block stays. A used one is rejected with a ReferencedRemovalError on name whose references list every use, all with cascadable: false. The role of a use is its place name, <construct>:<context>:
| Construct | Contexts |
|---|---|
declaration |
element, deploymentNode |
connector |
model-relationship, deployment-relationship, extend-relationship, step, predicate |
tags |
element, relationship, deploymentNode, instance, deployment-relationship, view, extend, kind-default |
element.kind, element.tag, where-kind, where-tag, relation-where-kind, relation-where-tag, participant-kind, participant-tag |
predicate, style-target, rank-target |
For example, connector:step or where-tag:predicate. A name written where the library does not resolve references — an import, a dynamic view's flow block other than par, unparsed text — is a use with role opaque-flow, global-or-import or unrecovered. A use inside a named view carries its view id; one inside global { } is a modelled place (where-tag:predicate, element.kind:style-target, …) and carries its definition, global: { type, name }. The type KindPlaceRole is exported.
Rejected (InvalidWriteError, nothing changed):
- on
type: not one of the three kind types; - on
name:- no such kind or tag is declared, or it is declared more than once;
- for a rename, a construct the library does not resolve names it;
- the shared-condition case above;
- on
newName:- a name the grammar does not accept for the declaration, or one already declared for the type;
- the shared-condition case above, at a resolved place or at one the library does not resolve;
- an edit that would not parse.
A removal of an undeclared kind or tag is a plain InvalidWriteError, not a ReferencedRemovalError.
An element can get tags, links and metadata from extend X { ... } blocks, in the same or other files:
// base.c4
model {
app = service 'App' {
#internal
metadata { owner 'team-a' }
}
}
// ext/ops.c4
model {
extend app {
#critical
link https://runbooks.example.com/app 'Runbook'
metadata { owner 'ops' }
}
}
getElement / listElements report the effective tags, links and metadata — what LikeC4 itself builds for the element — plus their provenance:
const app = mutator.getElement('app')!;
app.tags; // ['internal', 'critical']
app.links; // [{ url: 'https://runbooks.example.com/app', label: 'Runbook' }]
app.metadata; // { owner: ['team-a', 'ops'] }
app.declared; // { tags: ['internal'], metadata: { owner: 'team-a' } } — the declaration body only
app.extendedBy; // [{ file: 'ext/ops.c4', sourceRange: {...}, tags: ['critical'], links: [...], metadata: { owner: 'ops' } }]Merge rules (LikeC4 1.60.0):
- The defaults of the element's kind come first (see Specification defaults), then the declaration body, then every
extendblock of exactly this element — files ordered by path the way LikeC4 orders documents (natural and segment by segment:a/x.c4beforea.c4,ext9.c4beforeext10.c4; independent of the order passed tofromFiles), then source order within a file. tags: union without duplicates. Within one body, comma-separated groups (#a, #b #c) are taken last group first, as LikeC4 does (['b', 'c', 'a']);declaredandextendedBylist them in source order.links: concatenated; duplicates are kept.metadata: every value of a key is collected (a key repeated inside one block too); when a key appears in more than one body, duplicate values are dropped. A key with one value maps to a string — also when written askey ['v1']— otherwise to an array.declaredandextendedBykeep the form as written.- Only the first
metadata { ... }block of a body counts, as in LikeC4 — for the effective values,declared,extendedByand relationship metadata alike. Later blocks are ignored, even when the first block is empty. - Values are normalized as LikeC4 does: metadata values are dedented and trimmed and empty ones dropped (
k ' x 'reads as'x',k ''not at all); a link label is dedented, trimmed and joined into one line, an empty label is dropped.declaredandextendedBykeep strings as written. getElementSourceandsourceRangestill refer to the declaration; eachextendedByentry carries the range of its block. Blocks that only declare nested elements, or nothing, are listed too.- File names must denote distinct paths:
fromFiles({ 'a.c4': ..., './a.c4': ... })throws. - A standalone
new C4Query(ast)merges only theextendblocks of that document and reports them withoutfile; pass aWorkspaceIndexbuilt from{ file, ast }documents for the whole project. - A workspace with syntax errors is read best effort: what the parser recovers is merged.
- Relationships have
extend a -> b { ... }blocks with their own matching and merge rules — see Relationships.
updateElement keeps its documented semantics for the effective values:
| Patch | Declaration body | Every extend X { ... } of exactly this element, in every file |
|---|---|---|
title, summary, description, technology, style |
updated as before | untouched (the grammar does not allow them there) |
tags: [...] / tags: [] |
replaced / removed | tags removed |
links: [...] / links: [] |
replaced / removed | links removed |
metadata: { k: value } |
k upserted |
k removed |
metadata: { k: null } |
k removed |
k removed |
| metadata keys not in the patch | kept verbatim | kept verbatim |
mutator.updateElement('app', { tags: ['internal'], metadata: { owner: 'platform' } });
// base.c4: #internal, metadata { owner 'platform' }
// ext/ops.c4: extend app { link https://runbooks.example.com/app 'Runbook' }
// => { changedFiles: ['base.c4', 'ext/ops.c4'] }- New values always go into the declaration;
extendblocks only lose the patched properties / keys. Nested elements, relationships, comments and other keys in the blocks are kept; a block that ends up empty (extend app { }) stays in place — remove it by hand if you do not want it. - Extend blocks of descendants (
extend app.api) are not touched byupdateElement('app', ...). - A body may hold several
metadata { ... }blocks; LikeC4 reads only the first. A patched key is upserted into the first block and removed from every block of the declaration and of theextendblocks. A block left without attributes is removed — except a first block while a later block of the same body still has attributes: it stays as an emptymetadata { }, so the later block does not start counting.updateRelationshiphandles a relationship's blocks the same way. - After the update, reading the element returns what LikeC4 makes of the written value: e.g.
metadata: { k: ['v1'] }reads back ask: 'v1'(declaredkeeps['v1']). updateElementreturns{ changedFiles }: the files whose text changed, in load order ([]when nothing changed). It describes the in-memory state — use it to save only those files fromserialize().- An update of
tags,linksormetadatais rejected, before anything changes, while any loaded file has syntax errors (validate()is not empty): anextendblock in that file could not be found reliably. Other properties can still be updated. - The update is atomic in memory: when any file's edit fails, all files are restored. Writing files to disk (e.g. the CLI's
--output/--in-place) happens file by file and is not atomic. removeElementdeletes everyextendblock of the element's subtree;addElementandgenerateElementwrite only the new declaration —extendblocks that already target the new FQN start contributing once it exists.
addElementExtend(fqn, { file, tags?, links?, metadata? }) and addRelationshipExtend(selector, { file, tags?, links?, metadata?, shared? }) contribute to an element or a model relationship through an extend block of the loaded file (required). Both return { changedFiles, merged }.
mutator.addElementExtend('app', { file: 'ext/ops.c4', tags: ['internal'], metadata: { runbook: 'ops-12' } });
mutator.addRelationshipExtend({ source: 'app.api', target: 'app.db', matchTitle: 'reads' }, { file: 'ext/ops.c4', links: [{ url: 'https://runbooks.example.com/db' }] });
// ext/ops.c4: extend app { #internal ... } and extend app.api -[jdbc]-> app.db 'reads' { link ... }- One block per target and file. When
filealready has a block of the element (exactly its FQN), or one applying to the relationship, the contributions are merged into its first one: new tags after its tags, new links and metadata keys at its end (ametadata { }block is created when it has none). A tag or link the block already has is not repeated; the same link in a block of another file is kept, as LikeC4 keeps duplicates. Otherwise a new block goes to the end of the file's firstmodelblock, created when the file has none.mergedtells which. - The relationship block is selected with the selector of
updateRelationship(source,target,matchKind,matchTitle,matchBidirectional,position) and written with the relationship's identity: endpoints as absolute FQNs, the bracket connector with its kind and direction (-[kind]->,-[kind]<->, or->/<->without a kind), and its own title — so it also applies to a relationship written asa .kind b. LikeC4 applies a block to every relationship of its identity: when others share it, the call is rejected onsharedwithrelatedlisting them ({ file, line, column, construct: 'relationship' }), and withshared: truethe block applies to all of them. - Rejected (
InvalidWriteError, nothing changed): onfqn, an element no loaded file declares; onsource/position, no relationship or several (RelationshipAmbiguityErroronsource), and a relationship whose only title is its kind's default title (LikeC4 1.60.0 ignores a block without that title and warns about one with it); onfile, a missing or unloaded file; ontags[i],links[i].url,metadata.<key>, an undeclared tag, an invalid link or metadata value, and a metadata key the element or relationship already has in its declaration or in anyextendblock of any file (withshared, also a key of the other relationships the block applies to) (a second value would turn LikeC4's value into an array — change it with an update); ontags, nothing to add.
A relationship can get tags, links and metadata from extend a -> b { ... } blocks (only directly in a model block):
// base.c4
model {
api -[calls]-> db 'reads' {
metadata { sla '99.9%' }
}
}
// ext/ops.c4
model {
extend api -[calls]-> db 'reads' {
#critical
metadata { owner 'ops' }
}
}
Every relationship getRelationships() reports carries its direction: bidirectional is true for a <-> b and a -[kind]<-> b, false for ->, -[kind]-> and .kind — LikeC4's isBidirectional, the field deployment relationships report too. Each extendedBy entry of a relationship carries the direction of its block (extend a <-> b → bidirectional: true); entries of element and deployment node blocks have no such field.
getRelationships() reports effective tags, links and metadata, declared and extendedBy, as for elements. LikeC4 1.60.0 decides which relationships a block applies to, and merges, as follows:
- A block applies to every relationship with the same source and target (resolved to FQNs), kind, title and direction. No kind matches only relationships without a kind (
-[calls]->and.callsare the same kind); a kind no specification declares counts as no kind, as LikeC4 resolves it (kindingetRelationships()still reports it as written). Titles are compared dedented and trimmed; the title may be written after the target or as atitlebody property, and a relationship without a title is compared with thetitleof its kind's specification when that declares one. A bidirectional block (extend b <-> a) matchesa <-> b; a directed block never matches a bidirectional relationship. - The defaults of the relationship's kind come first (see Specification defaults), then the relationship's own values — its tags are those written on the relation line (
a -> b 'x' #t) or else those of its body — then every matching block in the order used for elements.updateRelationshipreplaces tags where the relationship has them: on the relation line when it has any there (body tags in the same relationship, which LikeC4 reports as an error, are removed so they cannot take over), otherwise in the body. tagsandmetadatamerge as for elements.linksdiffer: a block's link is skipped when a link with the same url and label is already present; the relationship's own duplicates are kept.- The kind's tags and links take part as described in Specification defaults: a block's link equal to a kind link is skipped too.
updateRelationship treats these blocks like updateElement treats extend X blocks — same table and rules (new values go into the relationship; patched tags, links and metadata keys leave every matching block in every file; empty blocks stay; rejected while a file has syntax errors; atomic in memory) — and returns { changedFiles }. In addition:
- The title identifies the relationship for its blocks, so a
labelthat changes the title is written into every matching block as well (extend api -[calls]-> db 'queries' { ... }); otherwise they would stop applying. - A block applies to every relationship with the same identity (e.g.
a -> b 'x'anda -> b { title 'x' }). When an update would change such a shared block, it is rejected before anything changes, because the other relationship would change too. - A
labelthat changes the identity is rejected, before anything changes, when the relationship's blocks would then also apply to another relationship that already has the new identity, or when blocks of the new identity with tags, links or metadata exist (even if no relationship has it yet): they would start applying to the renamed relationship. removeRelationshipalso removes the blocks that applied to the removed relationship and apply to no remaining one (they would match nothing).removeElementremoves, besides those of the relationships it removes, every block whose source or target is in the removed subtree. Blocks that matched nothing before are left alone.
The deployment { ... } part of the model is read and written through workspace-level methods: ids span files, so they are not per-file operations. Nodes and instances are addressed by their LikeC4 deployment id (prod.eu.vm1), relationships by their endpoints.
| Nodes | Instances | Relationships | extend <node> blocks |
|
|---|---|---|---|---|
| Read | getDeploymentNode, listDeploymentNodes; kinds: getSpecification().deploymentNodeKinds, getDeploymentNodeKind |
getDeploymentInstance, listDeploymentInstances |
listDeploymentRelationships |
extendedBy of a node |
| Add | addDeploymentNode |
addDeploymentInstance |
addDeploymentRelationship |
addDeploymentExtend |
Update ({ changedFiles }) |
updateDeploymentNode |
updateDeploymentInstance |
updateDeploymentRelationship |
— |
Remove ({ removedRelationships }) |
removeDeploymentNode |
removeDeploymentInstance |
removeDeploymentRelationship |
removeDeploymentExtend |
Every write is also an apply operation with the same fields — see Deployment operations.
Where new text goes. A child node and an instance go into the body of their parent's declaration; file is not accepted for them. A root node, a relationship and an extend block go into a deployment block, and there the explicit file decides: the first deployment block of that file, else a new block at its end (the file must be loaded; no file is created). Without file — not allowed for addDeploymentExtend — the first deployment block of the first file in LikeC4's document order that has one; else a new block at the end of the first file with a model block; else of the first file. Details per write under Writing.
getSpecification() lists the deployment node kinds (deploymentNode <kind>) in deploymentNodeKinds, in order of first declaration. The field is present only when at least one is declared, so the result of a specification without deployment node kinds is unchanged; a specification that declares only deployment node kinds no longer reads as null. getDeploymentNodeKind(kind) returns the declaration and its defaults (DeploymentNodeKindDefaults), or null for an undeclared kind:
specification {
element service
deploymentNode environment
deploymentNode vm {
#infra
title 'Virtual machine'
technology 'Linux'
style {
shape rectangle
color secondary
opacity 40%
}
}
tag infra
}
mutator.getSpecification();
// { elementKinds: ['service'], tags: ['infra'], relationshipKinds: [], deploymentNodeKinds: ['environment', 'vm'] }
mutator.getDeploymentNodeKind('vm');
// { kind: 'vm', file: 'spec.c4', sourceRange: {...}, title: 'Virtual machine', technology: 'Linux',
// tags: ['infra'], style: { shape: 'rectangle', color: 'secondary', opacity: '40%' } }- The defaults are the values LikeC4 computes for the kind: title, summary, description and technology normalized as for an element kind; tags of every comma-separated group in LikeC4's order (the last group first) without duplicates —
#a, #breads as['b', 'a']; link labels read as one line; andstyle: the kind's firststyle { ... }block, the last value of a repeated field, no theme defaults, withopacityandiconas written (see Style values as written). ThefromSpecificationof a node reports the kind's tags and links as written. - A kind declared more than once is taken as for an element kind: the last declaration of the last file in LikeC4 document order.
The style of a deployment node kind, a node and an instance is reported as LikeC4 computes it (no theme defaults; size aliases such as small read as sm; a hex color inside style { ... } is ignored, as LikeC4 ignores it), except for two fields, which keep the form they are written in — a value the library reads is a value it can write back:
opacitykeeps its written spelling:opacity 40%reads as'40%',opacity 040%as'040%'andopacity 150%as'150%', where LikeC4 computes the numbers 40, 40 and 100 (clamped to 0…100).iconkeeps relative paths (./img/db.svg), root-relative paths (/img/db.svg) and image aliases (@/db.svg) as written; LikeC4 resolves them to URLs. Library icons (tech:postgresql),noneand absolute URLs read as LikeC4 reads them.
A relative icon path is relative to the file that declares it: a node or instance that inherits the icon of a kind or element declared in another file reports the path written there (./img/db.svg), which LikeC4 resolves against that other file. Copied into another file, the same text can resolve to a different URL. Root-relative paths and image aliases depend on the consumer's project — its root folder and its imageAliases (@ stands for ./images by default) — which the library does not read.
getDeploymentNode(id) returns a node by its LikeC4 deployment id — the parent's id + . + name, e.g. prod.vm1 — or null. listDeploymentNodes({ kind?, parentId? }) lists nodes of every file in LikeC4 document order (a parent before its children); parentId matches direct children only.
// model.c4
specification {
element service
deploymentNode environment
deploymentNode vm {
#infra
title 'Virtual machine'
style {
color secondary
}
}
tag infra
tag eu
}
model {
api = service 'API'
}
deployment {
environment prod 'Production' {
vm vm1 {
technology 'Ubuntu'
instanceOf api
}
}
}
// regions.c4
deployment {
extend prod.vm1 {
#eu
metadata {
region 'eu-west'
}
}
}
const vm1 = mutator.getDeploymentNode('prod.vm1')!;
vm1.title; // 'Virtual machine' (the kind title: vm1 has no title of its own)
vm1.technology; // 'Ubuntu'
vm1.tags; // ['infra', 'eu']
vm1.metadata; // { region: 'eu-west' }
vm1.style; // { color: 'secondary' }
vm1.extendedBy; // [{ file: 'regions.c4', sourceRange: {...}, tags: ['eu'], metadata: { region: 'eu-west' } }]
vm1.instances; // ['prod.vm1.api']
vm1.parentId; // 'prod'
mutator.listDeploymentNodes({ parentId: 'prod' }); // [prod.vm1]
mutator.listDeploymentNodes({ kind: 'environment' }); // [prod]The effective values are LikeC4's (DeploymentNodeInfo):
| Property | Rule |
|---|---|
title |
own when written ('' included, inline or in the body); else the node name. A title equal to the node name — written or by default — is replaced by the kind title when the kind has one |
summary, description, technology |
own ('' included), else the kind's; summary and description are reported field by field, without the display fallback from one to the other |
tags |
own — or the kind's when the node has none — then those of the extend blocks, then the kind's appended, without duplicates |
links |
own — or the kind's when the node has none — then those of the extend blocks |
metadata |
own, then the extend blocks, merged as for elements |
style |
the kind's style overridden field by field by the node's own style { ... }; opacity and icon as written (see Style values as written) |
extendedBylists everyextend <node>block whose written path is exactly the node's id —extend prod.vm1extendsprod.vm1, never another node namedvm1— including blocks that only add children.children(nodes) andinstancesinclude those declared inextendbodies.declaredholds the tags, links and metadata of the node's own body as written,fromSpecificationthe kind's declaration (DeploymentNodeKindDefaults).- Only what LikeC4 keeps in its model is reported. A node whose kind no specification declares is left out, and with it everything below it — child nodes and instances — and every relationship with an endpoint there; so is a node declared inside an
extendblock of a node that does not exist. An id declared twice (a LikeC4 error) is listed once per declaration;getDeploymentNodereturns the first in document order.
getDeploymentInstance(id) returns an instance (instanceOf <element>) by its deployment id — the id of its node + . + name — or null. listDeploymentInstances({ nodeId?, element? }) lists instances of every file in LikeC4 document order; nodeId matches the instances directly in that node, element the FQN the instanceOf reference resolves to (not the text as written). An instance written without a name is named after the last segment of its reference as written: instanceOf app.api is api.
specification {
element service
deploymentNode vm
tag backend
tag replica
}
model {
api = service 'API' {
#backend
summary 'Public API'
technology 'Go'
metadata {
owner 'team-a'
}
style {
shape browser
}
}
}
deployment {
vm vm1 {
instanceOf api
replica = instanceOf api 'API replica' {
#replica
metadata {
region 'eu'
}
style {
color red
}
}
}
}
const api = mutator.getDeploymentInstance('vm1.api')!;
api.element; // 'api'
api.title; // 'API' (inherited)
api.technology; // 'Go' (inherited)
api.metadata; // { owner: 'team-a' } (inherited)
const replica = mutator.getDeploymentInstance('vm1.replica')!;
replica.title; // 'API replica'
replica.summary; // 'Public API' (inherited)
replica.tags; // ['replica', 'backend']
replica.metadata; // { region: 'eu' } — an own map replaces the element's
replica.style; // { shape: 'browser', color: 'red' }
mutator.listDeploymentInstances({ element: 'api' }); // [vm1.api, vm1.replica]The effective values are LikeC4's (DeploymentInstanceInfo):
| Property | Rule |
|---|---|
title |
own when written ('' included); else the element's title |
summary, description, technology, links |
own, else the element's (as getElement reports it) |
metadata |
the own map, else the element's map — an own map replaces the element's whole map, keys are not merged |
tags |
own, then the element's, without duplicates |
style |
the element's style (its kind's style overridden by its own) overridden field by field by the instance's own style { ... }; opacity and icon as written (see Style values as written) |
- Three documented differences from LikeC4's computed values: summary and description are inherited field by field — LikeC4 shows the description as the summary (and the reverse) when only one of them is set, the library does not; no technology is derived from an icon (LikeC4's
inferTechnologyFromIcon, on by default), as for elements; and styleopacityandiconkeep their written form, also when inherited from the element (see Style values as written).
// model/shop.c4
specification {
element store
deploymentNode vm
}
model {
db = store 'Database' {
description 'Primary store'
icon tech:postgresql
}
files = store 'Files' {
icon ./img/files.svg
}
}
// deployment.c4
deployment {
vm vm1 {
instanceOf db
instanceOf files
}
}
const db = mutator.getDeploymentInstance('vm1.db')!;
db.description; // 'Primary store'
db.summary; // undefined — LikeC4 shows 'Primary store' as the summary too
db.technology; // undefined — LikeC4 derives 'Postgresql' from the icon
mutator.getDeploymentInstance('vm1.files')!.style;
// { icon: './img/files.svg' } — relative to model/shop.c4, where LikeC4 resolves it;
// written as is into deployment.c4 it would point into the folder of deployment.c4- An instance whose
instanceOfreference does not resolve is not reported, as LikeC4 drops it. Instances cannot be extended;declaredholds the tags, links and metadata of the instance's own body as written.
listDeploymentRelationships({ source?, target?, kind? }) lists the relationships of the deployment model in LikeC4 document order; getRelationships() keeps returning the logical model only. Each endpoint is { id, element? }: the deployment id of a node or instance, plus the element FQN when the endpoint steps into the element of an instance (vm1.db.replLog). A source / target filter by an instance id also matches endpoints that step into its element.
specification {
element service
deploymentNode vm
relationship replicates {
#data
technology 'TCP'
line dotted
}
tag data
}
model {
db = service {
replLog = service
}
}
deployment {
vm vm1 {
instanceOf db
}
vm vm2 {
instanceOf db
-> vm1 'heartbeat'
}
vm2.db -[replicates]-> vm1.db.replLog 'streams WAL'
vm1.db <-> vm2.db 'sync'
}
mutator.listDeploymentRelationships();
// [
// { source: { id: 'vm2' }, target: { id: 'vm1' }, bidirectional: false, title: 'heartbeat', ... },
// { source: { id: 'vm2.db' }, target: { id: 'vm1.db', element: 'db.replLog' }, kind: 'replicates',
// bidirectional: false, title: 'streams WAL', technology: 'TCP', tags: ['data'], style: { line: 'dotted' }, ... },
// { source: { id: 'vm1.db' }, target: { id: 'vm2.db' }, bidirectional: true, title: 'sync', style: { tail: 'normal' }, ... },
// ]
mutator.listDeploymentRelationships({ target: 'vm1.db' }); // ['streams WAL']The effective values are LikeC4's (DeploymentRelationshipInfo):
| Property | Rule |
|---|---|
source |
as written; for a relationship written without a source (-> vm1), the enclosing node or instance |
kind |
-[kind]->, -[kind]<-> or .kind, as written |
title |
own (after the target, else in the body), else the kind's; an empty one is no title |
description |
the body description, else the kind's. A description or technology written on the relation line is ignored, as LikeC4 ignores it |
technology |
the body technology when non-empty, else the kind's |
tags |
the kind's, then the tags written on the relation line — or, when there are none there, those of the body — without duplicates |
links |
own, else the kind's |
metadata |
the first metadata { ... } block |
style |
the kind's style overridden field by field by the own style { ... }. A bidirectional relationship always has a tail, as LikeC4 computes it: the one written, else the head, else 'normal' |
- A relationship whose source or target does not resolve (an unknown or ambiguous name), or resolves to a node or instance LikeC4 leaves out of its model, is not listed, as LikeC4 drops it. Deployment relationships cannot be extended.
declaredholds the tags, links and metadata written in the relationship,fromSpecificationthe kind's declaration with its style.
Deployment writes address nodes and instances by their deployment id, as the reads do. A rejected write throws an InvalidWriteError naming the option (see Rejected writes) and changes no file.
The examples below run on one workspace. deployment.c4 declares the environment prod with the zone prod.eu and the hosts prod.eu.vm1 (instances api and api2 of shop.api, and db of shop.db) and prod.eu.vm2 (instance web of shop.web), relationships between them, and a deployment view whose rules name prod.eu.vm1 and elements inside it. ext/eu.c4 and ext/eu-extra.c4 extend prod.eu — the first with the tag #internal, the metadata key owner, the host vm3 and the relationship vm3.web -> vm1.api 'proxies', the second with the tag #edge. The logical model declares shop.web, shop.api with its child shop.api.handler, and shop.db.
addDeploymentNode(parentId, opts) adds a node under the node parentId, or a root node when parentId is null, and returns its id. It is written in the name = kind form: the title inline (an empty title is written as ''), summary, description, technology, tags, links, style and metadata in the body — a node has no inline technology.
mutator.addDeploymentNode('prod.eu', {
name: 'vm4',
kind: 'host',
title: 'VM 4',
technology: 'KVM',
tags: ['primary'],
style: { color: 'blue' },
});
// 'prod.eu.vm4', written at the end of the body of `eu`:
// vm4 = host 'VM 4' {
// #primary
// technology 'KVM'
// style {
// color blue
// }
// }
mutator.addDeploymentNode(null, { name: 'stage', kind: 'environment', file: 'deployment.c4' });
// 'stage', written at the end of the first deployment block of deployment.c4:
// stage = environment- A child node goes at the end of the body of its parent's declaration; a declaration without a body gets one. Children the parent has in
extendblocks do not change this place.fileis not accepted for a child node. - A root node goes into a
deploymentblock. Withfile(one of the loaded files; no file is created): the firstdeploymentblock of that file, else a new block at the end of that file. Withoutfile: the firstdeploymentblock of the first file in LikeC4's document order that has one; else a new block at the end of the first file (in that order) with amodelblock; else of the first file. - Rejected, with nothing changed: a
namethat is not one identifier or is reserved, or whose id is already used by a node or instance of a loaded file — children declared inextendblocks included (name); akindno specification declares as a deployment node kind (kind); an undeclared tag (tags[i]); an invalid style value (style.<field>); aparentIdthat is not declared, is an instance or is declared more than once (parent, naming the declarations);fileon a child node, or afilethat is not loaded (file). - References stay as they are. A new node can change how LikeC4 links a reference that is already written: with
prod { inner { x } y },prod.xlinks toprod.inner.x, the onlyxbelowprod, untilprod.y.xexists. The write is rejected onnamewhen a reference that resolved before — a deployment relationship endpoint, aninstanceOftarget, anextendtarget, a deployment view rule or a reference of the logical model — would then resolve to another target or not at all.
updateDeploymentNode(id, patch) patches a node with the semantics of updateElement, on the node's effective values, and returns { changedFiles }:
title,summary,description,technologyreplace every declaration LikeC4 reads — inline (after the kind inname = kind 'Title', after the name inkind name 'Title') and in the body. A new title is written inline; summary, description and technology go into the body.tagsandlinksreplace;metadatamerges,nulldeletes a key;stylemerges per field.style.iconis written into the body-leveliconwhen the node has one (it overridesstyle { icon ... }), else into the style block.- The kind's defaults keep applying, as LikeC4 reads them:
tags: []clears the node's own tags and those of itsextendblocks, but the kind's tags stay;links: []clears own andextendlinks, and the kind's links apply again. Atitleequal to the node's name reads as the kind's title when the kind has one; an emptytitle('') reads as''. - Patched tags, links and metadata keys are removed from every
extend <node>block whose path is exactlyid, in every file, so that the patched value is the effective one. Blocks of other nodes, descendants included, are not touched. - The kind is not changed. A node declared in an
extendblock is addressed by its id like any other.
mutator.updateDeploymentNode('prod.eu', { title: 'Europe', tags: ['primary'], metadata: { owner: null } });
// { changedFiles: ['deployment.c4', 'ext/eu-extra.c4', 'ext/eu.c4'] }
// the tags of both extend blocks of prod.eu and the owner key of ext/eu.c4 are removedRejected, with nothing changed: an id no node has, that is an instance or that is declared more than once (id, naming the declarations); an undeclared tag or an invalid style value; a tags, links or metadata update while any loaded file has syntax errors (field tags, links or metadata: an extend block could hide in that file); the other fields can still be updated then.
removeDeploymentNode(id, { cascade? }) removes a node with its whole subtree — child nodes, instances and the relationships declared in them — and returns { removedRelationships } (with cascade: true also cascaded). Removed with it, in every file:
- every
extend <node>block of the node or of a node of its subtree, with what is declared in it; - every deployment relationship whose source or target is in the subtree — a node or instance of it, or an element stepped into through an instance of it.
removedRelationships lists each removed relationship as listDeploymentRelationships() reported it before the call: { source, target, title? }, endpoints as { id, element? }.
mutator.removeDeploymentNode('prod.eu.vm3'); // declared in the extend block of ext/eu.c4
// { removedRelationships: [{ source: { id: 'prod.eu.vm3.web' }, target: { id: 'prod.eu.vm1.api' }, title: 'proxies' }] }
mutator.removeDeploymentNode('prod.eu.vm1');
// rejected on id (ReferencedRemovalError): the deployment view refers to prod.eu.vm1 and to elements inside it
mutator.removeDeploymentNode('prod.eu.vm1', { cascade: true });
// removes those view items too, unless one is the view's last includeRejected, with nothing changed (field id):
- an
idno node has, that is an instance or that is declared more than once; - without
cascade, a rule of a deployment view (include,exclude, a relationship predicate,style) refers to the node or anything in its subtree — aReferencedRemovalErrorlists the references; withcascadethe item or target is removed (an emptied rule too), unless that removes a deployment view's lastinclude; - in both modes, an id of the subtree written in text the parser could not recover (a whole identifier or any dotted segment);
- the removal would change what a surviving reference links to. A name can become unique: with
vm nat the root andprod { a { n } b { n } c { -> n } },-> nlinks to the rootnwhilenis ambiguous belowprod; removingprod.bwould make it link toprod.a.n.
addDeploymentInstance(nodeId, opts) deploys the element opts.element in the node nodeId and returns the instance's id. The instance is written at the end of the body of the node's declaration (a declaration without a body gets one), also when the node has children in extend blocks: name = instanceOf element, or instanceOf element without a name, with the title inline (an empty title is written as '') and summary, description, technology, tags, links, style and metadata in the body — an instance has no inline technology. file is not accepted.
mutator.addDeploymentInstance('prod.eu.vm2', { element: 'shop.db' });
// 'prod.eu.vm2.db', written at the end of the body of `vm2`:
// instanceOf shop.db
mutator.addDeploymentInstance('prod.eu.vm1', { element: 'shop.api', name: 'api3', title: 'API 3', tags: ['replica'] });
// 'prod.eu.vm1.api3':
// api3 = instanceOf shop.api 'API 3' {
// #replica
// }elementis written as given and resolved as LikeC4 linksinstanceOffrom the node: in the model blocks of the node's file and among the root elements, then each further segment among the unique descendants of the previous one. Nodes and instances are never candidates, soinstanceOf vm1does not name the instancevm1.- Without
namethe instance is unnamed, and LikeC4 names it after the last segment ofelementas written (instanceOf shop.dbisdb). That id must be free; when a node or instance already has it, give aname. - Rejected, with nothing changed: a
namethat is not one identifier or is reserved, or an id — given or implicit — already used by a node or instance of a loaded file, children declared inextendblocks included (name); anelementthat is not identifiers joined by., or does not resolve to exactly one element (element); an undeclared tag (tags[i]); an invalid style value (style.<field>); anodeIdthat is not declared, is an instance or is declared more than once (node, naming the declarations); anyfile(file). - References stay as they are, as for nodes: the write is rejected on
namewhen a reference that resolved before would then resolve to another target or not at all. Withn1 { instanceOf app.db }and a top-leveln2.web -> db,dblinks to the only instance nameddb; an unnamedinstanceOf app.dbin another node would make it ambiguous, whiledb2 = instanceOf app.dbis accepted. A rule of a deployment view that names an instance by its name alone is protected the same way.
updateDeploymentInstance(id, patch) patches an instance and returns { changedFiles }. Only the instance's declaration is edited: the element it deploys and its instanceOf target are never changed, and instances have no extend blocks.
title,summary,description,technologyreplace the instance's own values, inline (after the element ininstanceOf shop.web 'Title' 'Summary') and in the body. A new title is written inline; summary, description and technology go into the body.tagsreplace the instance's own tags. LikeC4 always appends the element's tags, so they stay in the read value: an element tagged#publicreads['replica', 'public']aftertags: ['replica'], and['public']aftertags: [].linksreplace the instance's own links;links: []removes them, and the element's links apply again.stylemerges per field into the instance's own style;style.iconis written into the body-leveliconwhen the instance has one.metadatais patched on the effective map — the one the read reports. LikeC4 reads the instance's own map when it has one and the element's whole map otherwise, so when the instance has no own map the element's keys are first copied into it, then the patch is applied: a string or list upserts a key,nullremoves it. An ownmetadata { ... }block left without attributes is removed.
// element shop.api: metadata { owner 'team-a' tier 'gold' }; instance prod.eu.vm1.api has no own metadata
mutator.updateDeploymentInstance('prod.eu.vm1.api', { metadata: { tier: 'platinum' } });
// written into the instance: metadata { owner 'team-a' tier 'platinum' }
// effective: { owner: 'team-a', tier: 'platinum' }LikeC4 cannot express an empty own map: an empty metadata { }, or values that are empty after trimming, count as absent and the element's map applies again. So a metadata patch is accepted only when every patched key reads as requested afterwards — an upserted key with its value, a null key absent — and is otherwise rejected on metadata.<key>. Keys of the element the patch does not name can come back:
// element app.db: metadata { region 'eu' }; instance prod.db: metadata { tier 'gold' }
mutator.updateDeploymentInstance('prod.db', { metadata: { tier: null } });
// accepted: the own block is removed, effective { region: 'eu' }
// element app.db: metadata { region 'eu' }; instance prod.other has no own metadata
mutator.updateDeploymentInstance('prod.other', { metadata: { region: null } });
// rejected on metadata.region: without an own map LikeC4 reads the element's, where region is 'eu'Rejected, with nothing changed: an id no instance has, that is a node or that is declared more than once (id, naming the declarations); an undeclared tag or an invalid style value; a metadata key that would not read as requested (metadata.<key>); a tags, links or metadata update while any loaded file has syntax errors (field tags, links or metadata: the element values the instance inherits could hide in that file); the other fields can still be updated then.
removeDeploymentInstance(id, { cascade? }) removes an instance with the relationships declared in its body, and every deployment relationship in any file whose source or target is the instance or an element stepped into through it (prod.eu.vm1.api.handler). The element it deploys is not touched. It returns { removedRelationships }, listed as for removing nodes, and with cascade: true also cascaded, the references the cascade removed.
mutator.removeDeploymentInstance('prod.eu.vm1.db');
// { removedRelationships: [
// { source: { id: 'prod.eu.vm1.api' }, target: { id: 'prod.eu.vm1.db' }, title: 'queries' },
// { source: { id: 'prod.eu.vm1.api2' }, target: { id: 'prod.eu.vm1.db' }, title: 'replicates' },
// ] }Rejected, with nothing changed (field id):
- an
idno instance has, that is a node or that is declared more than once — two unnamed instances of one element in one node share an id, and the error names both; - without
cascade, a rule of a deployment view refers to the instance or to an element through it (style prod.eu.vm1.api.handler) — aReferencedRemovalErrorlists the references; withcascadethe item or target is removed (an emptied rule too), unless that removes a deployment view's lastinclude; - in both modes, the instance's id written in text the parser could not recover (a whole identifier or any dotted segment);
- the removal would change what a surviving reference links to. With
outer { n = instanceOf app.db prod { a { n = ... } b { n = ... } c { -> n } } },-> nlinks toouter.nwhilenis ambiguous belowprod; removingouter.prod.b.nwould make it link toouter.prod.a.n. A removal that only makes an ambiguous reference resolve — one that did not resolve before — is accepted.
addDeploymentRelationship(source, target, opts?) writes a relationship at the top level of a deployment block, chosen like the block of a root node (see Adding nodes): opts.file when given (one of the loaded files, a block is created at its end when it has none), otherwise the first deployment block in LikeC4's document order. The connector is ->, <-> (bidirectional: true), -[kind]-> or -[kind]<->; the title is written inline (an empty title as ''), and description, technology, tags, links, metadata and style go into the body — LikeC4 ignores a description or technology written on the relationship line.
Each endpoint is { id, element? }, the form listDeploymentRelationships reports:
idis written as given and must resolve, from the place it is written and the way LikeC4 links deployment references, to a node or an instance: the full id (prod.eu.vm1) or a shorter reference LikeC4 links there (vm1where that name is unique). A logical element (shop.api) is not an endpoint.elementsteps into the element the instance deploys. It is the FQN of an element below that element (as reads report it), and it is written as the path from the instance's element: withapi = instanceOf shop.api,{ id: 'prod.eu.vm1.api', element: 'shop.api.handler' }is writtenprod.eu.vm1.api.handler.
mutator.addDeploymentRelationship({ id: 'prod.eu.vm2.web' }, { id: 'prod.eu.vm1.db' }, {
kind: 'calls',
title: 'reads',
technology: 'SQL',
tags: ['internal'],
});
// at the end of the first deployment block:
// prod.eu.vm2.web -[calls]-> prod.eu.vm1.db 'reads' {
// #internal
// technology 'SQL'
// }
mutator.addDeploymentRelationship({ id: 'vm2' }, { id: 'prod.eu.vm1.api', element: 'shop.api.handler' }, { bidirectional: true });
// vm2 <-> prod.eu.vm1.api.handlerRejected, with nothing changed:
- an
idthat is not a reference, does not resolve to one node or instance from the insertion point (an unknown or ambiguous name, a logical element, a name visible only in another file'sdeploymentblocks), or itself steps into an element —source.id/target.id; - an
elementthat is not an FQN, is given for a node, is not below the instance's element, or is not reached by the written path —source.element/target.element; - endpoints that are the same node or instance, or a node and something below it (LikeC4:
Invalid parent-child relationship; only theidparts count, so two elements of one instance are rejected too) —target; - an undeclared
kind, an undeclared tag, an invalid style value, metadata LikeC4 cannot hold, afilethat is not loaded —kind,tags[i],style.<field>,metadata.<key>,file.
updateDeploymentRelationship(selector, patch) changes one deployment relationship and returns { changedFiles }. The selector is { source, target, kind?, title? }: the endpoints exactly as listDeploymentRelationships reports them ({ id, element? }, the element part being the FQN), narrowed when needed by the reported kind and title (the own title, else the kind's). A bidirectional relationship matches its endpoints in either order.
mutator.updateDeploymentRelationship(
{ source: { id: 'prod.eu.vm1' }, target: { id: 'prod.eu.vm2' }, title: 'mirrors' }, // matches `prod.eu.vm2 -[syncs]<-> prod.eu.vm1`
{ title: 'Mirrors', technology: 'rsync', tags: ['public'] },
);
// prod.eu.vm2 -[syncs]<-> prod.eu.vm1 'Mirrors' #public {
// technology 'rsync'
// }titlereplaces the title, written inline after the target (LikeC4 reads it over atitlein the body).description,technologyreplace the body values. A description or technology written on the relationship line, which LikeC4 ignores, is left as it is.tagsreplace the tags where LikeC4 reads them: on the relationship line when the line has tags, otherwise in the body.linksreplace the links;[]clears either. The kind's tags and links keep applying as LikeC4 reads them.metadatamerges,nulldeleting a key;stylemerges per field.- The endpoints, kind and direction are never changed.
Rejected, with nothing changed:
- no relationship matches, or several do —
source; the error names the candidates. Relationships with the same endpoints, kind and title cannot be told apart by a selector: change one of them by other means first; - a malformed endpoint —
source.id,source.element,target.id,target.element; - an undeclared tag, an invalid style value, metadata LikeC4 cannot hold —
tags[i],style.<field>,metadata.<key>; - a
tags,linksormetadataupdate while a loaded file has syntax errors (validate()is not empty) — that field. A title, description, technology or style update is still accepted.
removeDeploymentRelationship(selector) removes the one relationship the selector picks — the same selector as for updating — wherever it is declared: at the top level of a deployment block, in a node or instance body, or in an extend block. Nothing else changes. It returns { removedRelationships } with that relationship, as for removing nodes.
mutator.removeDeploymentRelationship({ source: { id: 'prod.eu.vm1.api' }, target: { id: 'prod.eu.vm1.db' } });
// { removedRelationships: [{ source: { id: 'prod.eu.vm1.api' }, target: { id: 'prod.eu.vm1.db' }, title: 'queries' }] }Rejected, with nothing changed: no relationship matches, or several do — source, naming the candidates; a malformed endpoint — source.id, source.element, target.id, target.element.
addDeploymentExtend(nodeId, { file, tags?, links?, metadata? }) adds an extend <node> block that contributes tags, links and metadata to a deployment node. file is required and must be loaded: the block goes into its first deployment block, or a new block at its end. The target is written as the node's id, which LikeC4 resolves as a strict path; strings and style are never written (the grammar allows none in an extend body). The node's reads then include the contribution and list the block in extendedBy.
mutator.addDeploymentExtend('prod.eu', { file: 'ops.c4', tags: ['public'], metadata: { region: 'west' } });
// in ops.c4:
// deployment {
// extend prod.eu {
// #public
// metadata {
// region 'west'
// }
// }
// }Rejected, with nothing changed: a node that is not declared, is declared more than once or is an instance (LikeC4: ExtendDeployment allows only DeploymentNode) — node; nothing to contribute (no tag, link or metadata key) — tags; an undeclared tag or metadata LikeC4 cannot hold — tags[i], metadata.<key>; a missing or unloaded file — file.
removeDeploymentExtend({ node, file, occurrence? }) removes one block, selected by the node id written after extend and its file; when the file holds several blocks of the node, occurrence picks one, counted from 1 in source order. What is declared in the block goes with it, following the rules of removing nodes: the nodes and instances declared there with their subtrees and the extend blocks of those subtrees, the relationships declared there, and every relationship whose endpoint resolves into what was declared there. It returns { removedRelationships }.
mutator.removeDeploymentExtend({ node: 'prod.eu', file: 'ext/eu.c4' });
// removes `extend prod.eu { ... host vm3 { ... } vm3.web -> vm1.api 'proxies' }`
// { removedRelationships: [{ source: { id: 'prod.eu.vm3.web' }, target: { id: 'prod.eu.vm1.api' }, title: 'proxies' }] }Rejected, with nothing changed: a malformed node or a file without such a block — node; an unloaded file — file; several blocks without occurrence, or an occurrence that is not a whole number from 1 or exceeds the blocks — occurrence (the error lists the blocks); a deployment view rule that refers to something declared in the block, or a removal that would change what a surviving reference links to — node.
listViews(opts?) lists every view declaration of every file — element, dynamic and deployment views — in LikeC4 document order, then source order; opts.type keeps one view type, opts.file the views of one file (exact file name). getView(id) returns the view declared with that id, or null.
const views = mutator.listViews({ type: 'dynamic' });
const view = mutator.getView('index');
// { id: 'index', type: 'element', title: 'Landscape', tags: ['next'], folder: 'Overview',
// file: 'views.c4', sourceRange: { ... }, inModel: true, rules: [ ... ] }A view reports its own values, as LikeC4 parses the declaration:
id— the declared id;nullfor an unnamed element view (view of app { … }), which can be read but not addressed by writes;type—element,dynamicordeployment;of,extends— the reference as written (text) and what it resolves to (target: an element FQN, an element view id;nullwhen it does not resolve, includingextendsof a view that is not an element view);title— single line, an escaped slash\/kept, without the folder prefix LikeC4 adds (views 'Ops' { view x { title 'T' } }readstitle: 'T',folder: 'Ops');description—{ md }for a Markdown string,{ txt }for a plain string;tags— without duplicates, in the order LikeC4's parse returns them: comma-separated groups last group first (#next, #deprecatedreads['deprecated', 'next']);links—{ url, label? };folder— the folder string of the enclosingviewsblock;file,sourceRange— where the declaration is written;inModel—falsefor a declaration without a body (view v): LikeC4 builds no view from it;order—{ value?, inModel }:valueis the numeric literal as written after the keyword (3,-1,1.5; absent when none is written),inModelwhether LikeC4 applies it — a negative or non-integerorderis a LikeC4 error that drops the property (with a comment betweenorderand-1, LikeC4 applies1);routing— the view's ownroutingproperty,splineorortho; when it is absent, LikeC4 uses the routing of the lastautoLayoutrule, which is reported on that rule (both written: LikeC4 uses the property and warns);variant— a dynamic view'svariant,diagramorsequence;rules— see below;steps— dynamic views only, see below.
order, routing and variant are read from their first occurrence, as LikeC4 reads them; a view that extends another reports only its own.
Absent fields mean the view declares none. Values a view gets through extends from its parent, the element title LikeC4 shows for an untitled view of X, and the default title of index are not applied. Views LikeC4 generates — an index when none is declared, implicit views — are not listed. An id declared more than once (a LikeC4 error) is listed once per declaration; getView reports its first declaration in LikeC4 document order.
Reads are best effort on files with syntax errors: views the parser recovers are listed.
listViewsBlocks(opts?) lists the views blocks of every file, in LikeC4 document order, then source order; opts.file keeps the blocks of one file (exact file name). A block is addressed by its file and its index among the views blocks of that file. Each block reports:
file,index,sourceRange;folder— as LikeC4 reads it, on one line; absent when none is written or it is blank (views '' { … });styles— the shared styles (styleandglobal stylerules) in source order, with the fields of view rules (see Rules) and paths[i]; their references resolve as LikeC4 scopes aviewsblock — an element in the document scope, then a deployment node, then an instance (targetin the{ model }/{ deployment }shape). LikeC4 applies them before the own rules of each element and dynamic view of the block, and not to its deployment views; they are not listed among the rules of the views. A target that links to a deployment node or instance is reported, but LikeC4 drops it from the style;views— the ids of the views the block declares, in source order (nullfor an unnamed view).
mutator.listViewsBlocks({ file: 'views.c4' });
// [{ file: 'views.c4', index: 0, folder: 'Overview', styles: [ ... ], views: ['index', 'flow'], sourceRange: { ... } }]getGlobals() returns the definitions of every global { } block in four lists — predicateGroups, dynamicPredicateGroups, styles, styleGroups — each in LikeC4 document order, then source order. Each definition has its name, file, sourceRange and declarationCount:
predicates— of a predicate group (include/exclude) or a dynamic predicate group (include), as view rules with paths[i];targets,style,notation— of a global style, as a viewstylerule;styles— of a style group, itsstylerules with paths[i].
Names are case-sensitive and project-wide; predicate groups of both kinds share one namespace, global styles and style groups another, so predicateGroup g and style g coexist. A name defined more than once in its namespace (LikeC4's Duplicate … error) is reported for each definition, with declarationCount above 1. A definition LikeC4 drops — a repeated name, or a group written empty — is reported as written. References inside resolve as LikeC4 scopes global { }: an element in the document scope, then a deployment node, then an instance (target { model } or { deployment }).
const { predicateGroups, styles } = mutator.getGlobals();
// predicateGroups[0]: { name: 'core', file: 'spec.c4', sourceRange: { ... }, declarationCount: 1, predicates: [ ... ] }rules lists the rules of the view body in source order — for a dynamic view its rules only, its steps are reported separately. Each rule has:
index— its 0-based position in this list (for a rule inside a group, in the group's list), andtext— its exact source text, withsourceRange. A rule is addressed by{ index, text? }: whentextis given it must equal the rule's text as read, otherwise a write is rejected;path— the rule's address at any depth:[i]at the top level of the view,[i, j]for rulejof the group ati,[i, j, k]one group deeper, and so on;kind—include,exclude,autoLayout,style,group,rank,globalPredicate,globalStyleorincludeAncestors, with the fields of its kind below;autoLayout—{ direction, rankSep?, nodeSep?, routing? }(direction as written, e.g.LeftRight;routingsplineororthowhen written); a view may have severalautoLayoutrules, LikeC4 uses the last;stylerules —targets(each with itstext,sourceRangeandexpression, an element expression as foritems; deployment views target nodes, instances, elements through an instance and model elements, which LikeC4 applies to their instances),style(the style fields as written:color,shape,border,opacitysuch as'40%',icon,iconColor,iconSize,iconPosition,multiple,size,padding,textSize;{}forstyle * { };sizingis kept in the text but not reported) andnotation(single line, the first one written);group—titlewhen written,color,border,opacityas written, andrules: its predicates,global predicatereferences and nested groups in source order, recursively, each with its ownindexandpath(a group with props only hasrules: []);rank—value(same,min,max,source,sink) only when written — LikeC4 usessamewhen none is — andtargetsas forstyle;includeAncestors—value, its boolean (written twice, both are reported; LikeC4 uses the last);globalPredicate,globalStyle—global: the name as written (text) and the definition it resolves to (target:{ type, name },nullwhen none): an element view'sglobal predicatenames a predicate group, a dynamic view's a dynamic predicate group,global stylea global style or a style group; names are case-sensitive and project-wide;items— the items of aninclude/excludein source order (a trailing comma adds none), each with itstext,sourceRangeand structure:expression— an element expression (wildcard;elementwith its reference and selectorchildren.*,descendants.**orexpanded._;elementKind/elementTagwith=or!=) or a relation expression (direct,incoming,outgoing,inOut, with the relationship kind and the form it is written in —bracket-[k]->ordot.k— and the bidirectional flag);where— the condition tree:{ and: [...] },{ or: [...] },{ not }, and leaves{ field: 'tag' | 'kind' | 'metadata', participant?, key?, operator?, value? }with the operator as written (=,!=,is,is not);with— the properties of thewith { … }block:title,description,technology,notation,notes,navigateTo(resolved to a view id), style fields as written,multipleof a relation.
References in rules resolve as LikeC4 scopes them inside the view: a name unique in the same document, the element of view … of X (and of an extends parent's of), qualified names; deployment views resolve deployment nodes and instances first (the target is then { deployment }, or { model } for an element). Rules of a views { style … } block are not rules of its views. Items LikeC4 ignores — a relation predicate or a with on a wildcard, kind or tag in a dynamic view's include — are reported as written.
steps lists the step statements of a dynamic view in source order, each with path, text and sourceRange:
step— a single step;chain—a -> b -> c, itssegmentsin order, each with itssegmentnumber and the text from its connector on;parallel— apar/parallelblock (keywordas written) with itsstatements, addressed[i, j];inModelisfalsewhen the block contributes no step to LikeC4 (par { }, or a block holding only blocks LikeC4 discards, such aspar { opt { } }), which LikeC4 drops;opaque— a stage-6 block (opt,loop,alt,trywith itscatch/finally,break) with itskeyword; its inner steps are not addressable.
A step statement is addressed by { path, segment?, text? }: [i] at the top level, [i, j] inside the par block at i, and a segment number inside a chain; text, when given, must match.
Each step (or chain segment) reports source and target as LikeC4 means them — the element the interaction goes from and the one it goes to, so a <- b has source b and target a — each as written and resolved in the document scope; direction (forward or backward, as LikeC4 parses it: a chain segment that returns to the element it came from is backward, its arrow stays ->); the written arrow; kind with its form; the inline title; the body (title, description, technology, notes, notation, navigateTo, style); and sequence, its position in LikeC4's step sequence (step-NN[:par.MM]: a par or stage-6 block takes one number), absent when LikeC4 drops the step.
View writes address a view by its id; an unnamed view cannot be addressed. A rejected write throws an InvalidWriteError naming the option (see Rejected writes) and changes no file. That includes an edit the edited file would not parse after (for example while it already has syntax errors): it is refused on the input that addresses the text — id for updateView and removeView, file for addView, rule.expression / address for the rule writes, step, patch, to, address or statements for the step writes.
View writes are allowed while other loaded files have syntax errors. Every view write that adds or removes text other than view properties — all but updateView without folder — resolves the references of the loaded files again, view rules, steps, navigateTo, extends and of included, and is rejected when one that survives the write would then link to something else or no longer resolve; references inside the text a write removes do not survive it. The error names the option that writes the text: id (addView, removeView), folder (updateView), rule.expression or address (rule writes), step, patch, to, address or statements (step writes).
addView(opts) adds a view: id, type (element, dynamic or deployment), and optionally target (the of element of an element view), extends (the element view an element view extends), title, description (a single-line text), includes, autoLayout, file and folder.
mutator.addView({
id: 'appDetails',
type: 'element',
extends: 'appView',
title: 'App details',
description: 'The services of the app',
includes: ['app.db'],
file: 'views.c4',
});
// written at the end of the first views block of views.c4:
// view appDetails extends appView {
// title 'App details'
// description 'The services of the app'
// include app.db
// autoLayout TopBottom
// }- Placement. With
file(one of the loaded files; no file is created): the firstviewsblock of that file, else a newviewsblock at its end. Withoutfile: the firstviewsblock of the first file in LikeC4's document order that has one; else a new block at the end of the first file (in that order) with amodelblock; else of the first file. Withfolder, the view goes into the block of that folder of the file so chosen (see View folders and views blocks). - Includes are checked as LikeC4 reads them in the new view: each item forms one
includerule; its references resolve in the chosen file with the scope of theofelement, or of theextendsparent'sofelement (a name unique in the document, the frame's descendants, qualified names; in a deployment view deployment nodes and instances — a logical element is not accepted in aninclude); kinds, tags, relationship kinds and custom colors are declared, library icons exist, an icon URI does not start withfile://, an opacity lies within 0%..100%, awithbody gives its icon once; anavigateTonames a declared view (from a relation'swith, a dynamic view). Rejected as well are the items LikeC4 drops without an error: a relation predicate in a dynamic view,withon a wildcard,element.kindorelement.tagin a dynamic view,withonelement.kind/element.tag, andwithin a deployment view. extendsneeds an element view withouttarget; the parent must be declared once, as an element view with a body (LikeC4 makes no view ofview p), and its ownextendschain must not lead back to the new view: LikeC4 drops the views of anextendscycle without an error.- Rejected, with nothing changed: a bad or already declared
id(id); atargetthat is not a reference or does not resolve (target);extendswithtarget, on a dynamic or deployment view, or naming no element view with a body, or closing a cycle (extends); afilethat is not loaded (file); anincludesitem as above (includes[i]); a badautoLayout(autoLayout); afolderwith a line break (folder). - A
navigateToorextendsalready written with the new id resolves once the view exists; that is not a change.
updateView(id, patch) changes the own properties of the named view id and returns { changedFiles } (the view's file, or [] when nothing changed):
title,description— REPLACE;nullremoves the property,''is written as an empty string;tags— REPLACE (declared tags only;[]removes them);links— REPLACE ({ url, label? };[]removes them);autoLayout— replaces the view's lastautoLayoutrule in place (the one LikeC4 uses), or is appended as the last rule;nullremoves everyautoLayoutrule;order— a non-negative safe integer, REPLACE;nullremoves it. LikeC4 reads the firstorder: it is replaced and later ones are removed. An invalid literal already written (order -1,order 1.5, with comments or a line break before it) is replaced or removed over exactly the keyword and the literal: a;after it is kept by a replacement and removed with it, a line the property stands alone on goes with it, a rule or}after it on its line is kept;routing—splineorortho, REPLACE;nullremoves it. Written next to anautoLayoutrouting, LikeC4 uses the property (and warns); theautoLayoutrouting is written withautoLayout;variant— a dynamic view'sdiagramorsequence, REPLACE;nullremoves it;folder— moves the declaration into theviewsblock of that folder in the same file (see View folders and views blocks).
mutator.updateView('appView', { title: 'App', tags: ['next'], autoLayout: 'LeftRight' });
// { changedFiles: ['views.c4'] }Properties go where the grammar puts them: tags first in the body, then the other properties, before any rule or step; a view declared without a body (view v) gets one, and LikeC4 then makes it a view. Other text and comments of the body are kept. The update is allowed while another loaded file has syntax errors; an edit that would leave the view's own file unparsable is refused, on id. Rejected, with nothing changed: an id that names no view, an unnamed view or a view declared more than once (id); an undeclared tag (tags[i]); an invalid link URL (links[i].url); an invalid autoLayout, '' included (autoLayout); an order that is negative, not an integer or not a safe integer (order); another routing (routing); another variant, or a variant of an element or deployment view (variant); a folder with a line break, or a move that would change what a reference links to (folder).
LikeC4 takes a view's folder from its views block: views 'Ops' { view a { … } } is the view a in the folder Ops, and LikeC4 shows its title as Ops / <title or id>. A folder that is absent, '' or blank is no folder. So a view changes folder by moving: updateView(id, { folder }) moves the view's declaration — its text as written, with the comments directly above it, re-indented — to the end of the first views block of the same file whose folder is folder as LikeC4 reads both, or into a new views '<folder>' { … } block at the end of the file when there is none. null, '' and a blank folder choose the first block without folder, or a new views { … } block. Views never move to another file.
// views.c4: views { view index { … } } views 'Ops' { view runtime { … } }
mutator.updateView('runtime', { folder: 'Team' });
// views { view index { … } } views 'Ops' { } views 'Team' { view runtime { … } }
mutator.addView({ id: 'flow', type: 'dynamic', folder: 'Ops' });
// … views 'Ops' { view flow { … } } …- The block a view leaves stays, emptied or not; a view whose block already has that folder is not moved (
changedFiles: []). - The folder is written as a single-quoted string, escaped (
views 'It\'s' {); a folder with a line break is rejected (folder). - References inside the moved declaration keep what they link to — it stays in the same document — and the move is checked like the other view writes (rejected on
folderotherwise). - The view gets the shared styles of its new block (
views { style … }) and loses those of the old one; LikeC4 applies them before its own rules. addView({ folder })writes the new view into the first block of the chosen file with that folder, or a new block at its end; withoutfolder, into the firstviewsblock of the file, whatever its folder.
A block itself is written by its address { file, index } — index its position among the views blocks of that file, as listViewsBlocks reports it. Each write returns { changedFiles }:
updateViewsBlock(block, { folder })sets the block's folder, replacing the written string or writing it after the keyword (views 'Ops' {);null,''or a blank folder remove it (views {). Every view of the block then reads that folder; a folder equal to the block's changes nothing.addViewsBlockStyle(block, rule, opts?)adds a shared style: astyleorglobalStylerule as for Writing rules, written right after the block's last shared style (before its first view when it has none), or before the shared style atopts.before{ index, text? }.updateViewsBlockStyle(block, address, patch)patches the shared style ataddress{ index, text? }in place, asupdateViewRulepatches a view rule;removeViewsBlockStyle(block, address)removes it with its lines.
mutator.addViewsBlockStyle({ file: 'views.c4', index: 0 }, { kind: 'style', targets: 'app.db', style: { shape: 'cylinder' } });
mutator.updateViewsBlockStyle({ file: 'views.c4', index: 0 }, { index: 0 }, { kind: 'style', style: { color: 'amber' } });
mutator.updateViewsBlock({ file: 'views.c4', index: 1 }, { folder: null });Shared styles are checked as view rules are — target lists, references, declared kinds, tags and colors, style values, single-line notation, a global style naming a global style or style group — with two differences: a block takes style and globalStyle only, and its references resolve as LikeC4 scopes a views block (an element, then a deployment node, then an instance); a target that links to a deployment node or instance is rejected, as LikeC4 drops it from the style. LikeC4 applies the shared styles before the own rules of each element and dynamic view of the block, and not to its deployment views. There is no move of a shared style: its place is set by addViewsBlockStyle. Rejected, with nothing changed: a file that is not loaded (block.file), an index out of range (block.index), a folder with a line break (folder), a kind other than style and globalStyle (rule.kind), the rule's values (rule.*, patch.*), an address out of range or a text that does not match (address.index, address.text, before.*).
addViewRule(id, rule, opts?), replaceViewRule(id, address, rule) and removeViewRule(id, address) write the rules of the named view id and return { changedFiles }. A rule is given by its kind (every kind but autoLayout, which is written with updateView):
{ kind: 'include' | 'exclude', expression }— the predicates written after the keyword, as given ('app.api, app.db','* where tag is #next');{ kind: 'style', targets, style?, notation? }—targetsone comma-separated list of element expressions ('*','app.api','app.*','app.**','app._','element.kind = service','element.tag != #legacy'), the style fields (color,shape,border,opacity,icon,iconColor,iconSize,iconPosition,multiple,size,padding,textSize) and a single-line notation;{ kind: 'group', title?, color?, border?, opacity?, rules? }— a single-line title, the props and the group's rules, which may be predicates, global predicates and groups;{ kind: 'rank', value?, targets }—same,min,max,sourceorsink(none written: LikeC4 usessame) and the targets as forstyle;{ kind: 'includeAncestors', value }— a boolean;{ kind: 'globalPredicate' | 'globalStyle', name }— the name of a global definition.
A rule is written one construct per line — a style with one field per line, then its notation; a group with its props first, then its rules one level deeper. A rule is addressed by { index?, path?, text? } as getView reports it: index in the view's top-level rule list, path at any depth ([i, j] is rule j of the group at i); given both, they must name the same rule; text, when given, must equal the rule's text.
// appView's rules: include *, autoLayout TopBottom
mutator.addViewRule('appView', { kind: 'exclude', expression: 'app.db' });
// include *, exclude app.db, autoLayout TopBottom
mutator.addViewRule('appView', { kind: 'include', expression: 'app.api with { navigateTo checkout }' }, { before: { index: 0 } });
// include app.api with { navigateTo checkout }, include *, exclude app.db, autoLayout TopBottom
mutator.replaceViewRule('appView', { index: 2, text: 'exclude app.db' }, { kind: 'group', title: 'Data', color: 'amber', rules: [{ kind: 'include', expression: 'app.db' }] });
mutator.addViewRule('appView', { kind: 'style', targets: 'app.db', style: { shape: 'cylinder' } }, { into: { path: [2] } });
// ✗ rejected on rule.kind: a group holds predicates, global predicates and groups only
mutator.addViewRule('appView', { kind: 'include', expression: 'app.api' }, { into: { path: [2] } });
// … group 'Data' { color amber, include app.db, include app.api } …
mutator.removeViewRule('appView', { path: [2, 0] });- Position.
addViewRulewrites the rule before the rule atopts.before(any depth: the rule joins that rule's group), at the end of the group atopts.into(after its props), or by default at the top level after the last item of the body, or before it when that item is anautoLayoutrule — so in a dynamic view after the last step. A view declared without a body gets one; a group written on one line is laid out over several. - Checks of
addViewRuleandreplaceViewRule, at the place the rule is written — what LikeC4 1.60.0 reports or drops silently is rejected:- the kind: element views take
include,exclude,globalPredicate,group,style,globalStyle,rank; dynamic viewsinclude,globalPredicate,style,globalStyle; deployment viewsinclude,exclude,style,includeAncestors; a groupinclude,exclude,globalPredicate,group; - predicates as Adding views checks
includes— references resolved in the view's scope (itsofelement or itsextendsparent's, its document), declared kinds, tags and custom colors, typednavigateTo, no item LikeC4 drops; also nowithin anexclude, and in a deployment view a logical element only inside a relation predicate of anexclude(exclude app.api -> app.db). An expression ending with a comma is rejected: it would join the next line of the body to the rule; so is one whose text reaches past the rule; - targets: exactly one list of element expressions (no
where,with, relation, trailing comma or further text), each reference resolving in the view (a deployment view's targets are its nodes and instances;element.kind/element.tagthere are rejected — LikeC4 drops the whole view), declared kinds and tags; - style and group prop values: theme colors or declared custom colors, library icons, no
file://icon, an opacity between 0% and 100%, the keywords of each field; rank same: its element targets must share one written parent —rank same { api, cloud.db }is rejected even whenapiiscloud.api(LikeC4:All targets must have the same parent rank same); a rank without a value is not checked;- a global reference: a definition of the type the view takes (a predicate group for an element view's
global predicate, a dynamic predicate group for a dynamic view's, a global style or style group forglobal style); aglobal predicateto a group with a predicate that names a deployment node, an instance or an element through an instance (prod.vm.i.api) is rejected — except at a relation end of a dynamic predicate group — as LikeC4 1.60.0 then stops computing the view, without an error; - a notation or a title with a line break.
- the kind: element views take
element.kindandelement.tagin a deployment view. LikeC4 1.60.0 leaves a deployment view out of its computed views, without an error, when anincludeorexcluderule or a style target of it uses anelement.kindorelement.tagexpression. The library accepts, reads, renames and removes such expressions in rules as written, and rejects them as new style targets; LikeC4 still does not show the view.- Replace and remove take any rule at any depth —
autoLayoutincluded; a group goes with its rules; a removed rule's lines go, its trailing comma with it. - Move —
moveViewRule(id, from, to)moves the rule atfrom— any kind,autoLayoutincluded, at any depth — to the boundaryto, both in the state before the move:[i]before the top-level rulei([n]after the last one),[i, j]before rulejof the group ati([i, n]at its end), and so on. Between top-level positions, into, out of and between groups. The rule's text moves as written, re-indented. A move right before or after the rule itself changes nothing (changedFiles: []). Rejected onto: a boundary that does not exist, one inside the moved rule (a group into itself or a descendant), or in a container that does not take the kind (styleorautoLayoutinto a group). - Patch —
updateViewRule(id, address, patch)changes a rule in place, itspatch.kindthe kind of the rule at the address: astyle'stargetsreplaced, itsstylemerged per field (nullremoves a field; removing the last one leaves{ }), itsnotationreplaced (nullremoves it); agroup'stitle,color,border,opacityreplaced (nullremoves; a new prop goes before the group's rules); arank'svaluereplaced (nullremoves it: LikeC4 then usessame) andtargetsreplaced; anincludeAncestors'svalue; a global reference'sname. Every other byte of the rule — comments, separators such asopacity: 40%;, field order,sizing— is kept. Each patched value is checked as foraddViewRule, therank sameparent check on the patched value and targets included; aninclude/excludeis replaced instead (patch.kind), anautoLayoutwritten withupdateView; a field of another kind is rejected onpatch.<field>. - Rejected, with nothing changed: an
idthat names no view, an unnamed view or a view declared more than once (id); an address out of range, through a rule that is not a group, withindexandpathnaming different rules, or with atextthat does not match (address.index,address.path,address.text, likewisebefore.*,into.*); a kind the place does not take,autoLayoutincluded (rule.kind,rule.rules[i].kindinside a group); the rule's values (rule.expression,rule.targets,rule.style.<field>,rule.color/rule.border/rule.opacity,rule.value,rule.name,rule.notation,rule.title).
The definitions of global { } blocks are written by name. Four adds write a new definition at the end of the first global block of the chosen file and return { changedFiles }:
addGlobalPredicateGroup(name, predicates, opts?)—predicateGroup <name> { … }withinclude/excluderules ({ kind, expression }), checked as predicates of an element view;addGlobalDynamicPredicateGroup(name, predicates, opts?)—dynamicPredicateGroup <name> { … }withincluderules, checked as predicates of a dynamic view;addGlobalStyle(name, { targets, style?, notation? }, opts?)—style <name> <targets> { … }, checked as a viewstylerule;addGlobalStyleGroup(name, styles, opts?)—styleGroup <name> { … }withstylerules.
mutator.addGlobalPredicateGroup('services', [{ kind: 'include', expression: 'app.*' }, { kind: 'exclude', expression: 'app.db' }]);
mutator.addGlobalStyle('accent', { targets: 'app.api', style: { color: 'amber' }, notation: 'Accent' }, { file: 'globals.c4' });
// global {
// …
// style accent app.api {
// color amber
// notation 'Accent'
// }
// }-
Placement. With
opts.file: the firstglobalblock of that file, else a new block at its end. Without it: the firstglobalblock of the first file in LikeC4's document order that has one; else a new block at the end of the first file with amodelblock; else of the first file. A file with severalglobalblocks (LikeC4 warns) gets the definition in its first one. -
References inside resolve as LikeC4 scopes
global { }: an element, then a deployment node, then an instance, from any file; kinds, tags and custom colors must be declared. A style target that links to a deployment node or instance is rejected, as LikeC4 drops it from the style; so is a predicate of a group that links to one or to an element through an instance (prod.vm.i.api), as LikeC4 then stops computing every view that uses the group. Groups written by hand with such a predicate are read, renamed and removed. -
Names are one identifier, case-sensitive, and free in their namespace: predicate groups and dynamic predicate groups share one, global styles and style groups another (LikeC4 reports
Duplicate …within a namespace), sopredicateGroup gandstyle gcoexist. Existing definitions are addressed by theirtype—predicateGroup,dynamicPredicateGroup,styleorstyleGroup— andname; a name defined more than once in its namespace (LikeC4'sDuplicate …) is ambiguous and rejected (name). A rule of a group is addressed{ index, text? }, asgetGlobalslists it: -
updateGlobalStyle(name, patch)patches a global style in place asupdateViewRulepatches a viewstylerule:targetsreplaced,stylefields merged (nullremoves one),notationreplaced (nullremoves it); comments and the other bytes are kept. -
addGlobalRule(type, name, rule, opts?)adds a rule to a group, at its end or before the rule atopts.before:include/excludein a predicate group,includein a dynamic predicate group,stylein a style group (rule.kindotherwise). -
updateGlobalRule(type, name, address, rule)replaces a predicate whole — the new{ kind, expression },include↔excludein a predicate group — so the group's last predicate can be changed without emptying it; in a style groupruleis astylepatch. -
removeGlobalRule(type, name, address)removes a rule; the last rule of a group is not removed (address): LikeC4 drops an empty group silently.
A rule is checked as addGlobalPredicateGroup checks the rules of a new group; an invalid one changes nothing, the group keeping its rule. Rules inside a group are not moved: a rule's place is set by addGlobalRule.
mutator.updateGlobalRule('predicateGroup', 'services', { index: 1 }, { kind: 'include', expression: 'app.db' });
mutator.updateGlobalStyle('accent', { style: { color: 'red', opacity: null } });- Rejected, with nothing changed: a name that is not one identifier or is already used in its namespace (
name); an empty definition — a group without rules or a style without targets, which LikeC4 drops silently and whose references it ignores (predicates,styles,targets); a rule kind the group does not take —excludein a dynamic predicate group, anything butstylein a style group (predicates[i].kind,styles[i].kind); the values of a rule (predicates[i].expression,styles[i].targets,styles[i].style.<field>, …) or of a global style (targets,style.<field>,notation); afilethat is not loaded (file).
The step writes — addViewStep, updateViewStep, moveViewStep, removeViewStep and addViewParallel — take the id of a dynamic view: an element or deployment view is rejected on id, as an id that names no view is (apply: mutations[i].id), with nothing changed.
addViewStep(id, step, opts?) adds a step to the named dynamic view id and returns { changedFiles }. A step is given by source and target as LikeC4 means them — the element the interaction goes from and the one it goes to — written as references; direction: 'backward' is written target <- source, so a step read with getView and written back keeps its meaning. Optional: kind (a declared relationship kind) with kindForm 'bracket' (-[kind]->, default) or 'dot' (.kind); title (after the target); description, technology, notes, notation, navigateTo (a dynamic view), color, line, head, tail (in the step's body).
mutator.addViewStep('checkout', { source: 'web', target: 'api', kind: 'https', title: 'Places the order' });
// web -[https]-> api 'Places the order'
mutator.addViewStep('checkout', { source: 'web', target: 'api', direction: 'backward', title: 'Confirms' }, { path: [2, 0] });
// api <- web 'Confirms', first in the par block at [2]- Where.
opts.pathis the boundary the step is written at:[i]before the top-level step statementi([n]after the last one),[i, j]before statementjof theparblock ati([i, n]at its end). Without it the step goes right after the last top-level step statement. A view declared without a body gets one. - Rejected, with nothing changed: an
idthat names no view, an unnamed view, a view declared more than once or a view that is not a dynamic view (id); an endpoint that does not resolve in the view's document — LikeC4 links step endpoints there: a name unique in that document, or a qualified one (step.source,step.target); a parent and its descendant (step.target; a step from an element to itself is valid); an undeclared kind, or a kind on a backward step, which no connector writes (step.kind); anavigateTothat is not a dynamic view (step.navigateTo); an invalid style value (step.color, ...); a path that does not exist or leads into a single step, a chain or a block such asopt(path).
updateViewStep(id, address, patch) patches the step at address in place and returns { changedFiles }: a single step { path, text? }, or one segment of a chain { path, segment, text? } (as getView reports them). Each field of patch replaces the step's value, null removes an optional one (kind, title, a body string, navigateTo, a style field); only the tokens a field concerns are rewritten — the references, the connector, the title, one body property — and the rest of the step, comments included, is kept.
mutator.updateViewStep('checkout', { path: [0] }, { title: 'Pays', technology: null, color: 'green' });
mutator.updateViewStep('checkout', { path: [1] }, { direction: 'backward', kind: null }); // api <- web- On a segment of a chain only the title, the kind, body strings,
navigateToand style change; changing its endpoints or direction is rejected (patch.source,patch.target,patch.direction), as they belong to the chain. A segment LikeC4 reads as returning stays returning. - A step that would end up backward with a kind is rejected (
patch.kind, orpatch.directionwhen the patch turns a kind-bearing step backward) unless the same patch removes the kind or makes the step forward. - The patched values are checked as
addViewStepchecks them, onpatch.<field>; a chain addressed without a segment is rejected onsegment, atextthat does not match ontext, a path to something other than a step or chain onpath.
moveViewStep(id, from, to), removeViewStep(id, address) and addViewParallel(id, opts) move, remove and group whole step statements — a single step, a chain, a par block, a block such as opt or alt:
Each call below is a separate example, starting from the statements in its comment:
// [A, B, C] at the top level
mutator.moveViewStep('checkout', { path: [0] }, [2]); // [B, A, C]
// [A, B, C]
mutator.moveViewStep('checkout', { path: [0] }, [3]); // [B, C, A]
// [A, par { B }, C]: removing the block's last statement removes the block
mutator.removeViewStep('checkout', { path: [1, 0] }); // [A, C]; { changedFiles, removedParallelBlocks: [[1]] }
// [A, B, C]: A and C go into a new par block, with a new step after them, at the end
mutator.addViewParallel('checkout', { statements: [[0], [2]], steps: [{ source: 'web', target: 'cache' }], path: [3] });
// [B, par { A, C, web -> cache }]- Addresses.
fromandtoare paths in the view as it is before the move;tois the boundary "before the statement at this path" ([n]after the last top-level statement,[i, n]at the end of theparblock ati), so[0] → [2]puts the first statement after the second. A move to the statement's own boundary changes nothing and writes nothing. A chain is moved or removed whole; one of its segments is rejected (segment). parblocks. LikeC4 drops aparblock that gives it no step — an empty one, or one holding only blocks it discards, such asopt { }— without an error. So a block a move or removal empties is removed in the same write, and its pre-write path is reported inremovedParallelBlocks; a move or removal that would leave the block with only such statements is rejected (from,address), naming the block.addViewParallelwritespar { … }at the top-level boundaryopts.path(by default after the last top-level statement): the top-level statements atopts.statements, moved in the order given, then the newopts.steps; rules between moved statements stay where they are. A block that would give LikeC4 no step is rejected (statements); so are nested blocks — aparmoved into apar(to,statements[i]).- Rejected as well, with nothing changed: a path that does not exist (
from,address,to,statements[i]), a destination inside the moved statement (to), a duplicate statement (statements[i]), an invalid new step (steps[i].<field>), atextthat does not match (text).
removeView(id, { cascade? }) removes the declaration of the named view id and returns { changedFiles } — with cascade: true also cascaded, the references the cascade removed (see Removing referenced elements for the shapes). A manual layout snapshot of the view (a file kept by LikeC4's layout tooling) is not touched.
References to the view from outside its declaration follow the reference policy:
- a
navigateToin an element predicate'swith(any view, or a global predicate group), or in a relation predicate'swith, a dynamic step, the body of a relationship or a deployment relationship (a dynamic view) rejects the removal by default; withcascade: truethenavigateToproperty is removed, and a predicate'swith { … }it leaves empty goes with it (a step or relationship body keeps its braces); extendsof an element view rejects the removal in both modes, listing every view of theextendschain;- a
navigateToin an opaque flow block (opt,alt, …), and the view id written there or in text the parser could not recover, reject it in both modes.
A rejection is a ReferencedRemovalError on id listing each reference with its file, line, column, role, whether cascade removes it, and the view it is written in (or global: { type, name }, the definition). References inside the removed declaration itself (a view that navigates to itself) go with it and do not block. A view declared more than once, or not at all, is a plain InvalidWriteError on id.
In a view title, and in an element title that names an implicit view, LikeC4 reads / as a folder separator and \/ as a literal slash. Title values (addView({ title }), addElement / updateElement title) use the same notation: \/ is written as is and every other backslash is escaped, so LikeC4 reads the title given.
mutator.addView({ id: 'costs', type: 'element', target: 'app', title: 'Cost \\/ Benefit' }); // view "Cost / Benefit", no folder
mutator.addView({ id: 'prod', type: 'element', target: 'app', title: 'Deployment / Prod' }); // view "Prod" in folder "Deployment"getElement().title reports such a title with / ('Cost / Benefit'), as LikeC4's model does; write \/ again when passing it back as a title that should not create a folder.
Text the library writes into a file uses that file's line ending — the one of its first line break (\r\n or \n; \n when the file has none). Text kept from the file is never changed, so a file that already mixes line endings stays mixed.
The library writes only the files it was given. A file option must equal a loaded file name exactly; no file is created, and a file that is not loaded is rejected on file. LikeC4's document order, used below, orders files by path, naturally and segment by segment (a/x.c4 before a.c4, ext9.c4 before ext10.c4). It is not the order the files were loaded in.
| Write | With file |
Without file |
|---|---|---|
model-level addElement, top-level addRelationship |
the first model block of that file, else a new one at its end |
the default file for a model block |
addKind, addTag |
the first specification block of that file, else a new one |
the default file for a specification block |
addView |
the first views block of that file, else a new one; with folder, the first block of that file with the folder, else a new one |
the default file for a views block; with folder, the block of that folder in it, else a new one |
updateView with folder |
— | the first views block of the view's own file with that folder, else a new one at its end; a view never changes file |
addGlobalPredicateGroup, addGlobalDynamicPredicateGroup, addGlobalStyle, addGlobalStyleGroup |
the first global block of that file, else a new one |
the default file for a global block |
root addDeploymentNode, addDeploymentRelationship |
the first deployment block of that file, else a new one |
the default file for a deployment block |
addElementExtend, addRelationshipExtend |
the first model block of that file, else a new one; an existing block of the same target in that file is extended instead |
rejected: file is required |
addDeploymentExtend |
the first deployment block of that file, else a new one |
rejected: file is required |
child element, child deployment node, deployment instance, addRelationship with placement: 'nested' |
rejected: the parent's (the source's) declaration decides the file | the end of the body of the parent's (the source's) declaration; a declaration without a body gets one, keeping its form and inline strings |
moveElement to the top level (parent: null) |
the first model block of that file, else a new one |
the element's current file |
moveElement under a parent |
rejected | the end of the body of the parent's declaration |
- The default file is the first file in LikeC4's document order that has a block of the kind being written. Without one, it is the first file with a
modelblock, else the first file, and a new block goes at its end. - Moves. A top-level element may move to another file. A move that changes neither the parent nor the file is rejected. Moving text into another file is rejected when it holds a relative
iconorlink(./…,../…), which LikeC4 resolves against the file it is written in (see Moving elements). - Updates, renames and removals edit each construct where it is written, in every file, together with its
extendblocks.updateKindedits the kind's one declaration, wherever it is.
removeElement, removeDeploymentNode, removeDeploymentInstance and removeView share one policy for the references into what they remove: a subtree of elements, of deployment nodes or one instance, or a view. What the removed construct owns goes with it in both modes. Every other reference rejects the removal by default; with cascade: true it is removed where the table allows it.
| Reference into the removed construct | Default | cascade: true |
|---|---|---|
model relationship endpoint, at any level and in an extend body |
removed (owned) | removed |
extend <element> target; extend a -> b endpoint; an extend a -> b block left matching no relationship |
removed (owned) | removed |
| deployment relationship endpoint in a removed deployment subtree | removed (owned) | removed |
extend <node> target in a removed node subtree |
removed (owned) | removed |
instanceOf of an element in the removed subtree |
rejected | the instance is removed, as removeDeploymentInstance with cascade removes it |
| deployment relationship endpoint that steps through an instance into the removed element subtree | rejected | the relationship is removed |
view of |
rejected | rejected |
view extends (removeView) |
rejected | rejected |
include or exclude item — an element, a selector, a relation predicate, an element.* expression with a reference — in an element, dynamic or deployment view, at the top level or in a group |
rejected | the item is removed with its with { … } and where; an emptied rule and an emptied group too |
navigateTo (removeView) in an element's or a relation's with, a step, a model or deployment relationship body |
rejected | the property is removed; an emptied predicate with { } too |
dynamic step endpoint: a single step, a chain segment, a step in par / parallel |
rejected | the step statement is removed; an emptied par / parallel too |
style rule target, in a view or in the views block; rank target |
rejected | the target is removed; the rule when it was its last target |
a reference in an opaque flow block (opt, loop, alt with if / when / else, try / catch / finally, break) |
rejected | rejected |
| a reference in a project import | rejected | rejected |
where conditions are not references: they name kinds, tags and metadata only.
A view's last content. A cascade that would remove a view's last content-producing statement is rejected, naming the view: the last include of an element or deployment view, or the last step or include of a dynamic view; a global predicate that names a non-empty predicate group (or, in a dynamic view, a non-empty dynamic predicate group) counts as content too. Without it LikeC4 would show other content. Content the view takes from extends does not count, nor does a global predicate to an empty or absent group, so such a cascade is rejected on purpose, also when the view would still inherit content.
Errors. A rejection is a ReferencedRemovalError, an InvalidWriteError on the removed target's field (fqn or id). Its references lists every reference with its position, its role, whether cascade removes it, and the view it is written in. With cascade: true the result lists every reference the cascade removed in cascaded. The shapes are under Removing referenced elements.
Every reference class the library models in views is modelled inside global { } too — LikeC4 resolves a name there as an element, then a deployment node, then an instance. Each operation keeps its own policy and modes; the references inside globals join what it already handles:
Reference inside global { } |
Operation | Default | cascade: true |
|---|---|---|---|
element (predicate items, style targets, where / with subjects) |
renameElement, moveElement |
rewritten like references in views | — |
| element | removeElement |
rejected, listing them | the predicate item or style target is removed; an emptied rule goes with it |
| deployment node or instance | removeDeploymentNode, removeDeploymentInstance |
rejected, listing them | the item or target is removed |
deployment node or instance declared in the removed extend block |
removeDeploymentExtend |
rejected (no cascade mode) | — |
navigateTo in a with { } of a global predicate |
removeView |
rejected, listing it | the navigateTo is removed; a with { } it empties goes with it |
kind and tag (element.kind, element.tag, where kind is …, where tag is …, negated and participant forms) |
renameKind, renameTag |
rewritten, with the protections of views | — |
| kind and tag | removeKind, removeTag |
rejected while used, the use named as a modelled place | — |
A listed reference inside a definition carries global: { type, name } instead of a view. A cascade that would leave a global definition empty — its last predicate, the last target of a global style, the last style rule of a style group — is rejected in both modes: LikeC4 drops an empty definition silently. An addition (addElement, addDeploymentNode, addDeploymentInstance, addView) whose name is written inside global { } is not rejected for that: like a reference in a view, it is accepted unless it would change what a reference links to.
A global predicate <name> or global style <name> reference — in a view rule at any depth, or in the shared styles of a views block — follows the same policy as other references:
-
Rename.
renameGlobal(type, name, newName)rewrites the definition's name and every reference that resolves to it, in every loaded file, in one write; a reference with the same text that resolves elsewhere — a definition of the other namespace, or none — is left as it is. The new name is one identifier free in its namespace (newName); an unknown definition or a name defined twice in its namespace is rejected (name). The write is atomic: when a file would not parse after its edit, or any surviving reference would link elsewhere, no file changes (newName). -
Remove.
removeGlobal(type, name, { cascade? })removes a definition. While a reference resolves to it, the removal is rejected with aReferencedRemovalErroronnamelisting every reference —role: 'global-reference',cascadable: true, and theviewit is written in, orviewsBlock: { file, index }for a shared style of aviewsblock (with views, without views, or with only deployment views). Withcascade: trueevery referring rule and shared style is removed, and agroupit empties goes with it; the result lists them incascaded. A view that would lose its last content is protected in both modes (see A view's last content). The removal is atomic over every file.
mutator.renameGlobal('predicateGroup', 'services', 'backends');
// predicateGroup backends { … } and every `global predicate services` that named it, in every fileThe library resolves the references of the model, the deployment model, the views and global blocks. It does not resolve:
- imports;
- the flow blocks of a dynamic view other than
par/parallel:opt,loop,alt,try/catch/finally,break; - text the parser could not recover.
A name written in such a place is compared as text, outside comments and string values. It blocks a write, which is then rejected naming the file and line:
- remove, rename, move: when it is the affected name — of the removed, renamed or moved element and everything below it, node, instance, view, kind or tag — as a whole identifier or any dotted segment (
x.apiblocks removingapp.api). This holds in both modes. - new names: when it is the new name as a bare identifier or the leading segment of a dotted name. New names are those of an added element, deployment node, instance or view, the new name of a rename, and the names of a moved subtree at their new place. A kind or tag addition is not checked.
A longer identifier that only contains the name does not block. The rule errs on the safe side: a move checks every name of the moved subtree, so opt { other.api -> x } blocks moving app.api, although it names another element.
Every write that adds, removes, renames or moves an element, a deployment node or instance, or a view resolves again every reference of the table above. That covers relationship endpoints, extend targets, instanceOf, deployment endpoints, view of and extends, rule items, steps, navigateTo, style and rank targets. The write is rejected when a reference that resolved before would then resolve to another target, become ambiguous or stop resolving. What the write removes or rewrites on purpose is the exception. The field is the one that introduces the name: name for addElement, addDeploymentNode and addDeploymentInstance, id for addView. References that did not resolve before the write are neither rewritten nor checked.
removeElement(fqn, { cascade? }) removes the element with its subtree and what it owns, in both modes: the relationships with an endpoint in the subtree (and those declared in it), the extend blocks of the subtree, and the extend a -> b blocks that lose an endpoint or their relationship. Every other reference into the subtree follows the reference policy:
- an
instanceOfof an element in the subtree rejects the removal; withcascadethe instance goes, with its deployment relationships and its deployment-view items; - a view
ofthe subtree rejects it in both modes, and so do the views thatextendssuch a view; - a name of the subtree written where the library does not resolve references, as a whole identifier or any dotted segment (
x.apiblocks removingapp.api), rejects it in both modes; - view items, steps, style and
ranktargets, the items and targets of global definitions, and deployment relationships through an instance are removed by the cascade, unless a view would lose its last content or a global definition would be left empty.
A rejection is a ReferencedRemovalError (an InvalidWriteError on fqn) whose references lists every reference: { file, line, column, role, cascadable, view?, viewsBlock?, global? }, 1-based, role naming the place (instance-of, predicate-item, step-endpoint, style-target, rank-target, view-of, view-extends, opaque-flow, global-or-import, unrecovered, …), cascadable whether cascade removes it, view the view it is written in. With cascade: true the result has cascaded: every reference the cascade removed, { file, line, column, role }, at its position before the write; without cascade the result has no such key. When the cascade removes deployment relationships with the instances it removes (or one that steps through an instance into the subtree), the result also has removedDeploymentRelationships, listed as removeDeploymentInstance reports them ({ source, target, title? }, endpoints { id, element? }). Nothing is written on a rejection.
renameElement(fqn, newName) replaces the name of the element's declaration (api = service and service api alike) and rewrites, in every loaded file, each reference whose target the rename changes: the element, everything below it, and an instance declared without a name (instanceOf app.api), which LikeC4 names after the element — its id changes with the name, and so do the deployment paths through it (prod.vm.api.handler). It returns { fqn, changedFiles } with the new FQN.
Each rewritten reference keeps the shortest change that still links to the new target at its place:
- its text, when that still resolves there (
handlerinside the renamed element's body stayshandler); - else its text with the segments that name the renamed element (or such an instance) replaced, a selector suffix kept (
app.api.*→app.gateway.*,api -> db→gateway -> db); - else the full FQN (or deployment id) of the new target;
- else the rename is rejected.
The targets of extend app.api { … } blocks are rewritten too. References that did not resolve before the call are left as they are; every other reference must still link to what it linked to before.
The element keeps its own values and those of its kind. An element without a title of its own, whose kind has none either, shows its name as its title, and that title follows the new name; the old name is not written as a title. Manual layouts are not read or updated (see Moving elements).
Rejected, with nothing changed (InvalidWriteError):
| Field | When |
|---|---|
fqn |
no element fqn is declared; a construct the library does not resolve — an import, an opaque flow block of a dynamic view (opt, loop, alt, try / catch / finally, break), text the parser could not recover — writes the old name as an identifier or any dotted segment, or holds a reference into the renamed subtree |
newName |
not a valid element name (see Rejected writes); an element with the new FQN is already declared; such a construct writes the new name as a bare identifier or the leading segment of a dotted name (opt { gateway -> other } blocks renaming to gateway); an instance declared without a name would get the id of another node or instance of its node, extend blocks of the node in any file included (LikeC4: Duplicate node name / Duplicate instance name); a reference cannot be written so that it links to its new target; another reference would link to something else |
moveElement(fqn, { parent, file? }) moves the element's declaration — with its whole body and the comment lines directly above it (no blank line between), plus a comment ending its last line — to the end of the body of parent (a body is created when the parent has none), or, with parent: null, to the end of the first model block of file (a block is created when the file has none). Without file, a move to the top level stays in the element's current file. The text is indented for its new place and written with the new file's line ending; a file the element leaves keeps its model block, even when it is empty.
A comment moves with the declaration only when it is a whole-line comment (// … or /* … */, possibly over several lines) directly above it, with no blank line or code in between; a comment that ends another declaration's line (db = service /* database */) stays with that declaration. The lines inside a multi-line string value ('…' or '''…''' over several lines) are written as they are, not re-indented, so the value does not change. It returns { fqn, changedFiles } with the new FQN.
The element and everything below it get new FQNs. Every reference to them, in every file, and every reference written in the moved text, is written so that it links to the same element as before from its place: its text when that still resolves there (a relationship between two children of the moved element usually keeps api -> db), else the text with the segments up to the moved element written as its new path (app.api.handler → core.api.handler), else the full FQN; else the move is rejected. The targets of extend blocks of the subtree follow. References that did not resolve before are left as they are.
What LikeC4 derives from the hierarchy changes with a move, as it would by hand: with app.api moved to the top level, include app.* no longer shows api, and wildcards in scoped views, x.**, x._ and implicit relationships follow the new tree. The explicit relationships, the element's properties and every written reference keep their targets. A move is not rejected because such derived view contents change.
Manual layouts. The library reads and writes .c4 sources only. A manual layout that LikeC4's tooling saved for a view (a .likec4.snap file) is neither read nor updated by a rename, a move or a removal.
Rejected, with nothing changed (InvalidWriteError):
| Field | When |
|---|---|
fqn |
no element fqn is declared; a construct the library does not resolve — an import, an opaque flow block of a dynamic view, text the parser could not recover — writes the name of the element or of anything below it as an identifier or any dotted segment, or holds a reference into the subtree. The rule is on the safe side: opt { other.api -> x } blocks moving app.api even though it names another element. |
parent |
no element parent is declared; parent is the element or lies below it; the move changes neither the parent nor the file; an element with the new FQN exists; a relationship or a dynamic step would join an element and its ancestor (LikeC4: Invalid parent-child relationship); a deployment path through an instance (prod.vm.app.api) would name an element outside the instance's element — the error's related lists those paths ({ file, line, column, construct: 'deployment-path' }); a reference cannot be written so that it links to its target; another reference would link to something else; the moved text, going to another file, holds an icon or a link starting with ./ or ../ (LikeC4 resolves those against the file they are written in) |
file |
given with a parent; not a loaded file; the element's own file for an element already at the top level; and, for a move to the top level with file, every reason listed under parent after the first two |
Every write call checks the values it introduces before anything changes. A rejected call throws an InvalidWriteError (exported): field names the offending option in the terms of the call (name, kind, id, target, source, autoLayout, tags[1], style.color, includes[0]), detail says what is wrong, and no file changes. apply reports the same as mutations[i].<field> (the element name of addElement is its id) with exit code 1 and writes nothing; the CLI commands report it with the flag in place of the mutation path (--id, --tags[1], --style.color).
| Value | Accepted |
|---|---|
element name (addElement), newName (renameElement), view id (addView) |
One LikeC4 identifier (letters, digits, _, -; not starting with a digit or -; no .; not a keyword such as title), not a reserved word (this, it, self, super, likec4lib, global), and not used yet: no element of a loaded file has the same FQN (a sibling in the parent's body or in an extend of the parent, or another root element), no view of any type has the same id. |
node name (addDeploymentNode), instance name (addDeploymentInstance) |
One LikeC4 identifier, not a reserved word, and an id (the parent's id + . + name; for an unnamed instance the last segment of element) no node or instance of a loaded file has — children declared in extend blocks included. |
kind (addElement, addDeploymentNode) |
One identifier. |
element (addDeploymentInstance), endpoint id and element (deployment relationships), node (addDeploymentExtend, removeDeploymentExtend) |
Identifiers joined by .. |
occurrence (removeDeploymentExtend) |
A whole number from 1. |
relationship source / target (addRelationship), view target (addView) |
Identifiers joined by . (app.api). |
autoLayout (addView) |
A direction (TopBottom, LeftRight, BottomTop, RightLeft), optionally followed by a whole-number rankSep and nodeSep (LeftRight 120 40). |
includes items (addView) |
Exactly one include rule of the view's type, whose references, kinds, tags and with values LikeC4 resolves in the new view, and no item LikeC4 drops (see Adding views). |
style values (addElement, updateElement, addRelationship, updateRelationship and the add / update writes of deployment nodes, instances and relationships) |
See Element style properties and Relationship style properties; a field the style type does not have is rejected. |
A value that would add other DSL than the property asked for (autoLayout: 'LeftRight\n exclude a', style: { color: 'red\n shape cylinder' }) is rejected by these checks, and so is a style value with a comment (// ..., /* ... */) or a separator (color: 'red;'): a style value is written in place of the existing one, where red // x would comment out a field that follows on the same line. Only what LikeC4 lexes as a comment counts: // inside a URI (icon: 'https://example.com/a.svg') is accepted. autoLayout and includes items are written on lines of their own, so a trailing comment there ('* // every element') is accepted and ends with the line.
Writes LikeC4 would reject are refused the same way:
| Call | Rejected when |
|---|---|
addElement |
kind is not declared as an element kind by a specification (element service); a tag is not declared (tag internal); the new name would change what an existing reference links to, or is written where the library does not resolve references (field name, see Reference policy). |
updateElement, updateRelationship, updateDeploymentRelationship |
a tag of tags is not declared. |
addRelationship |
source or target does not resolve to an element (LikeC4: Could not resolve reference); they resolve to the same element or to a parent and its descendant (LikeC4: Invalid parent-child relationship); a tag or kind is not declared; kindForm: 'dot' without a kind or with bidirectional; file with placement: 'nested', or a file that is not loaded; an extend a -> b block with the new relationship's identity without shared (field shared, see Relationship forms and placement); the edited file would not parse, as when it already has a syntax error (field file, or source for placement: 'nested'). |
addView |
an element view's target does not resolve to an element; an includes item LikeC4 would not accept, resolve or would drop; extends with target, on a dynamic or deployment view, to no element view with a body, or closing an extends cycle (see Adding views); the new id is written where the library does not resolve references (field id, see Reference policy). |
updateView |
id names no view, an unnamed view or a view declared more than once; a tag is not declared; a link URL or autoLayout is invalid; an order that is not a non-negative safe integer, another routing or variant, a variant outside dynamic views; a folder with a line break, or a folder move that would change what a reference links to (see Updating views). |
addViewRule, replaceViewRule, updateViewRule, moveViewRule, removeViewRule |
id as for updateView; the address names no rule, its index and path disagree or its text does not match; the place has no such rule kind (autoLayout is written with updateView); the targets, values, names or expressions are not what LikeC4 resolves at that place and keeps; a move into the moved rule itself (see Writing rules). |
updateViewsBlock, addViewsBlockStyle, updateViewsBlockStyle, removeViewsBlockStyle |
the block address names no views block of a loaded file (block.file, block.index); a folder with a line break; a kind other than style and globalStyle; a style rule's values, resolved in the scope of a views block; a shared-style address out of range or a text that does not match (see View folders and views blocks). |
addGlobalPredicateGroup, addGlobalDynamicPredicateGroup, addGlobalStyle, addGlobalStyleGroup |
a name that is not one identifier or is used in its namespace; an empty definition; a rule kind the group type does not take; a rule's or the style's values in the global scope; a file that is not loaded (see Global block). |
updateGlobalStyle, addGlobalRule, updateGlobalRule, removeGlobalRule |
type or name names no definition, or one defined more than once in its namespace; a rule address out of range; a rule kind or value the group does not take; the last rule of a group (removeGlobalRule) (see Global block). |
renameGlobal, removeGlobal |
type or name as above; a newName that is not one identifier or is used in its namespace, or an edit a file would not parse (newName); a reference to the definition that the mode does not remove, or a view that would lose its last content (ReferencedRemovalError on name, see References to global definitions). |
addViewStep, updateViewStep |
id as for updateView, or a view that is not a dynamic view; an endpoint does not resolve in the view's document; a parent and its descendant; an undeclared kind, or a kind on a backward step; an endpoint or direction change of a chain segment; an invalid path or style value (see Dynamic view steps). |
moveViewStep, removeViewStep, addViewParallel |
id as for updateView, or a view that is not a dynamic view; a path that does not exist, a chain segment, a destination inside the moved statement, a nested par; a par block left giving LikeC4 no step (see Dynamic view steps). |
removeView |
id names no view or a view declared more than once (InvalidWriteError); a reference to the view that the mode does not remove (ReferencedRemovalError, see Removing views). |
| every view write | the edited file would not parse; a surviving reference would link to something else (see Views › Writing). |
addDeploymentNode |
kind is not declared as a deployment node kind (deploymentNode vm); a tag is not declared; the new node would change what an existing reference links to, or its name is written where the library does not resolve references (field name, see Adding nodes and Reference policy). |
addDeploymentInstance |
element does not resolve to one element as LikeC4 links instanceOf (LikeC4: Could not resolve reference); a tag is not declared; the new instance would change what an existing reference links to, or its id is written where the library does not resolve references (field name, see Adding instances and Reference policy). |
addElementExtend, addRelationshipExtend |
see Creating blocks. |
addKind, updateKind, addTag |
see Specification defaults › Writing. |
renameElement |
see Renaming elements. |
moveElement |
see Moving elements. |
renameKind, renameTag, removeKind, removeTag |
see Renaming and removing kinds and tags. |
removeElement |
fqn is not a declared element, or an edit would leave a file that does not parse (InvalidWriteError); a reference into the subtree that the mode does not remove (ReferencedRemovalError, see Removing referenced elements). Field fqn. |
updateDeploymentNode |
id is not one declared node; a tag is not declared; tags, links or metadata while a loaded file has syntax errors (see Updating nodes). |
updateDeploymentInstance |
id is not one declared instance; a tag is not declared; a patched metadata key would not read as requested, as LikeC4 cannot hold an empty own map (metadata.<key>); tags, links or metadata while a loaded file has syntax errors (see Updating instances). |
removeDeploymentNode, removeDeploymentInstance |
id is not one declared node (instance); the removal would change what a surviving reference links to (InvalidWriteError, field id); a reference into the subtree that the mode does not remove (ReferencedRemovalError, see Removing referenced elements). |
addDeploymentRelationship |
an endpoint does not resolve to a node or instance, or its element part to an element of that instance (LikeC4: DeploymentRelation target '…' not resolved); the endpoints are one node or instance, or a parent and its descendant (LikeC4: Invalid parent-child relationship); kind is not declared as a relationship kind; a tag is not declared (fields source.id, source.element, target.id, target.element, target, kind, tags[i]; see Adding deployment relationships). |
updateDeploymentRelationship, removeDeploymentRelationship |
the selector matches no relationship or several (field source, naming the candidates); tags, links or metadata of an update while a loaded file has syntax errors. |
addDeploymentExtend |
node is not one declared node, or is an instance (LikeC4: ExtendDeployment allows only DeploymentNode); nothing to contribute (tags); a tag is not declared; file is missing or not loaded. |
removeDeploymentExtend |
the file has no such block, or a rule of a deployment view refers to something declared in it, or the removal would change what a surviving reference links to (node); several blocks of the node in the file and no valid occurrence (occurrence). |
Where new text goes is described in Placement and file choice.
Endpoints of addRelationship are resolved the way LikeC4 links them from the first model block of the chosen or default file: a name is looked up among the children of that block and the names unique below it, then the names unique across the file's model blocks, then the root elements of every loaded file; each further segment among the unique descendants of the previous one. So addRelationship('app.gateway', 'app.cache') is rejected when cache is declared only inside app.gateway: LikeC4 links app.cache to app.gateway.cache, a child of the source. this / it do not resolve at model level.
A new element can change how LikeC4 links references that are already written: with app = service { api = service }, a model-level api -> other links api to app.api, the only element of that name; once other.api exists, api is ambiguous and LikeC4 reports Could not resolve reference. A new direct child can also shadow a unique descendant (app.api linking to app.inner.api would link to a new app.api). addElement therefore resolves every reference of every loaded file again with the new element in place — view rules, dynamic steps, navigateTo and style and rank targets included — and is rejected, with nothing changed, when one that resolved before then resolves to another element or not at all. addView, addDeploymentNode and addDeploymentInstance do the same (see Every write keeps resolved references). References that did not resolve before the call are not considered.
Only what the call introduces is checked. Problems already in the files — undeclared tags or kinds, dangling references, duplicates — are neither reported nor a reason to reject a valid write, so a workspace with unrelated LikeC4 errors still accepts valid edits. validate() still reports syntax errors only; validateModel() reports what likec4 validate reports.
Only the loaded files are known. Declarations and elements of files that were not passed to fromFiles (or are outside --dir) are invisible: a kind, tag, custom color or endpoint declared only there is rejected, as the library cannot tell it from a typo. Load every file of the project (the CLI loads the whole --dir tree).
- Parse —
.c4source → AST + CST via@likec4/language-server(Langium standalone, no LSP) - Query — find elements by FQN, walk AST, build index
- Mutate — compute text edits from CST positions (
$cstNode.offset/end) - Apply — splice edits into source text (end → start to preserve offsets)
- Reparse — verify result is valid
.c4
npm install
npm run build # tsdown → ESM + TypeScript declarations
npm test # vitest
npm run lint # tsc --noEmitMIT