Calm Docify MVP for CLI v1.0.0

[LeighFinegold]

Introduction

This issue defines the MVP scope for the Calm Docify for the cli v1.0.0 release.

---

Background

• CALM Templating (CALM Templating #890) introduced template bundles—a structured package (defined by index.json) that encapsulates templates, transformers, and custom helpers—alongside the calm template CLI command for generating outputs from CALM models.

• Dereferencing Enhancement (Extend calm template to support dereferencing #1026) added automatic resolution for JSON documents, ensuring that all referenced models are recursively merged and exposed to templates without manual imports.

• Widgets Proposal (CALM Widgets - Simplified Handlebars Template Library for Architecture Documentation #1416) outlined the standalone calm-widgets project for registering reusable templates and helps with simplifying syntax, bracket notation, array indexing for traversing the document you are templating.

---

1. CLI Usage End‑State

• Inline file rendering

  calm docify --input architecture.json --template my-doc.md
  

  Renders a single markdown file, injecting data inline. (this doesn't need to be an md file specifically)

• Directory‑wide rendering

  calm docify --input architecture.json --templates docs/
  

  Processes every template file under docs/, preserving folder structure and injecting data into each.

• Default website output

  calm docify --input architecture.json
  

  • Generates a basic Docify website bundle (HTML/CSS/JS) using built‑in templates.
  • Any current widgets which are known to have bugs e.g. C4 architecture diagram will not be included in the default website, but will be reintroduced in a minor version.

Note: for custom bundles, continue to use the existing
calm template --bundle <bundle-folder> … workflow.

---

2. CLI Path Handling

• Template authors can navigate the architecture model with either:

  • Dot‑notation

    {{ architecture.metadata.name }}
    {{ architecture.nodes.0['node-type'] }}
    

    This would be a self-maintained capability and syntax would have to be maintained by calm developers

  • JSONPath via helper

    {{ jsonpath architecture '$.nodes[?(@.node-type=="service")].name' }}
    

    JSONPath is a standard (even if the expression syntax looks complicated)

• The CLI will normalize dot‑paths under the hood to JSONPath for consistent lookup semantics, so both styles yield the same results.

• The traversing will be based on the CALM schema and not on an abstraction model.

Note: the same change will be applied to calm template, but we could provide a helper function or a cli option to convert to the abstract model for backwards compatibility

---

3. Document Dereferencing

All external Calm documents and schemas (detailed-architecture, config-url) are automatically fetched and inlined into your architecture object.

Root document example:

{
  "nodes": [
    {
      "unique-id": "systemA",
      "node-type": "system",
      "name": "System A",
      "description": "Top‑level system",
      "details": {
        "detailed-architecture": "./systemA-details.json"
      }
    }
  ],
  "relationships": [],
  "metadata": {},
  "controls": {},
  "flows": []
}

systemA-details.json might look like:

{
  "$schema": "https://calm.finos.org/release/1.0-rc2/meta/core.json",
  "nodes": [
    {
      "unique-id": "component1",
      "node-type": "service",
      "name": "Component One",
      "description": "Handles incoming API requests"
    },
    {
      "unique-id": "component2",
      "node-type": "database",
      "name": "Component Two",
      "description": "Stores transaction data"
    }
  ],
  "relationships": [],
  "metadata": {},
  "controls": {},
  "flows": []
}

After dereferencing, in your template you can write:

{{!-- list components of systemA --}}
{{#each architecture.nodes[0].details['detailed-architecture'].nodes}}
- {{ this.name }} ({{ this['node-type'] }})
{{/each}}

---

4. Injecting Widgets

• Syntax

  {{> widgetName dataPath widgetAttribute1=[x] widgetAttribute2=[y]}}
  

  – where

  • widgetName is the name of the widget (e.g. table, list)
  • dataPath is the path into your architecture model (dot or bracket notation)
  • widgetAttribute pairs control formatting, columns, etc.

• Default widgets shipped in v1.0.0:

  • table: renders an array of objects as a table
  • list: renders an array of values or objects as a Markdown list
  • json: renders the following part of the document as a json document

• Examples

  {{> table architecture.nodes columns="unique-id,name,node-type"}}
  {{> list architecture.flows format="bullet"}}
  {{> table architecture.nodes[0].details['detailed-architecture'].nodes headers=false}}
  {{> json architecture.relationships}}
  

• Context binding expectation
  Users must specify the correct path to the data that each widget will render.

• Future v1.x
  We’ll add a capability to allow folks to register additional widgets.

---

5. Offline Support

• Reference documents often use URLs or document IDs.

• Users can supply a directory.json mapping file for offline mode:

  calm docify --input architecture.json --template doc.md --mapping directory.json
  

• Example directory.json:

  {
    "https://calm.finos.org/release/1.0-rc1/meta/control-requirement.json": "../release/1.0-rc1/meta/control-requirement.json",
    "https://calm.finos.org/workshop/controls/micro-segmentation.config.json": "controls/micro-segmentation.config.json",
    "https://calm.finos.org/workshop/controls/micro-segmentation.requirement.json": "controls/micro-segmentation.requirement.json",
    "https://calm.finos.org/workshop/controls/permitted-connection.requirement.json": "controls/permitted-connection.requirement.json",
    "https://calm.finos.org/workshop/controls/permitted-connection-http.config.json": "controls/permitted-connection-http.config.json",
    "https://calm.finos.org/workshop/controls/permitted-connection-jdbc.config.json": "controls/permitted-connection-jdbc.config.json"
  }
  

• During dereferencing, the CLI resolves references via directory.json entries first, falling back to network fetch only if no mapping exists.

---

Aim: Confirm the above scope for the v1.0.0 MVP.

[rocketstack-matt]

This seems pretty comprehensive to me . . . couple of notes

{{ architecture.metadata.name }}
{{ architecture.nodes.0['node-type'] }}

The second example should be by index, unique-id or filter, the example seems to be a cross of index and filter, e.g.

{{ architecture.nodes[0] }}
{{ architecture.nodes['node-unique-id'] }}
{{ architecture.nodes filter='node-type:service' }}

For traversing documents, I think we can be slightly less verbose . . .

{{ architecture.nodes[0].details['detailed-architecture'].nodes}}

can be

{{ architecture.nodes[0].details.nodes}}

[markscott-ms]

2. CLI Path Handling

For traversing documents, I think we can be slightly more verbose . . .

{{ architecture.nodes[0].details['detailed-architecture'].nodes}}

can be

{{ architecture.nodes[0].details.nodes}}

In this case though, details has two properties (required-pattern and detailed-architecture), both of which are another document. I don't think the conciseness is wise/possible.

dot notation vs JSONPath

A proprietary dot notation has the following drawbacks:

• ongoing maintenance
• documentation/training materials
• it's not a transferrable skill for a CALM user to take elsewhere or bring from elsewhere.

On the other hand, it looks much nicer than JSONPath, particularly because of the unique-id indexing support.

If it is implemented in a way that just translates to JSONPath, I like it. If its implementation is tightly coupled to the CALM schema, that's a problem. Is there prior art?

5. Offline Support

Support for directory.json to have domain to filesystem mappings would be useful, so rather than every file being spelled out, a domain or folder can be mapped:

{
   "https://calm.finos.org/" : "../my/local/copy/of/calm.finos.org/",
}

[rocketstack-matt]

You're not looking at the pattern when traversing the model, that property is needed to allow validation not for rendering.

Also, we're not trying to make folks json experts /compliant. Quite the opposite, we want creating documents from CALM models to be super simple so folks use it . . . there is a reason we've created visualisation and MCP tools - JSON is hard and folks don't want to work with it.

It absolutely provides value as a strongly typed model for us, but if we want folks to understand JSON for writing simple human renderings of the model then in my opinion it just won't get used.

Speaking as someone who knows JSON pretty well and is trying to write docs in real world, the current implementation which is basically pure handlebars just doesn't work from a usability perspective and should be reserved for SMEs proving reusable bundles for others like with the docusaurus generation.

[markscott-ms]

You're not looking at the pattern when traversing the model, that property is needed to allow validation not for rendering.

Okay. In this specific scenario is it a surprise to the user that the inner architecture document has been in-lined at the parent details node? i.e. would it be consistent with interfaces and controls?

Also, we're not trying to make folks json experts /compliant. Quite the opposite, we want creating documents from CALM models to be super simple so folks use it . . . there is a reason we've created visualisation and MCP tools - JSON is hard and folks don't want to work with it.

Agreed.

It absolutely provides value as a strongly typed model for us, but if we want folks to understand JSON for writing simple human renderings of the model then in my opinion it just won't get used.

Speaking as someone who knows JSON pretty well and is trying to write docs in real world, the current implementation which is basically pure handlebars just doesn't work from a usability perspective and should be reserved for SMEs proving reusable bundles for others like with the docusaurus generation.

I've looked at your PR #1417 and see that the dot notation is implementable and I think templates can use it and/or jsonpath as required [need to explore the PR more]