Literate Model

Traditional modeling has focused primarily on the description of structure, often separating design intentions and rationales into supplementary documents or inline comments. The Literate Model bridges this divide by integrating structure (the model) and narrative within a single coherent document.

Through this integration, a model becomes more than a static set of definitions—it evolves into a narrative model that conveys reasoning, context, and decision-making. AI can analyze these narrative components to comprehend the model’s intent and relationships, and to reconstruct or refine them accordingly.

The Literate Model extends the philosophy of Literate Programming, proposed by Donald E. Knuth, into the field of modeling. In Literate Programming, programs are written as human-readable narratives that integrate code and explanations within the same document. The Literate Model develops this idea further, shifting its focus from code to models themselves.

The Literate Model transcends Literate Programming by redefining modeling itself as a literate activity. Documents and models are generated from the same source, enabling a new form of cyclic knowledge evolution through writing, modeling, and AI collaboration.

The term “Literate Modeling” has been used in the past, but most prior attempts focused on describing models in UML (Unified Modeling Language) while supplementing their meaning with comments or external explanatory texts. These approaches positioned documentation as a means to make models more understandable, without treating the document itself as a model structure.

Representative studies include the following:

While these works were pioneering in improving the readability and expressiveness of models, they still treated the model and the narrative as separate layers, positioning natural language merely as supplementary explanation. Similar directions occasionally appeared in educational and DSL (Domain Specific Language)-related contexts, but systematic research on integrated literate modeling remained limited.

In contrast, the Literate Model in SimpleModeling fundamentally differs by unifying narrative and structure—making the document itself a structured model. The section and table structures of SmartDox directly correspond to model elements, while natural-language narratives are also analyzed by AI as part of the model data.

In short, while conventional Literate Modeling aimed to describe models, the Literate Model views narration itself as modeling—turning the act of writing into an act of modeling.

At the core of the Literate Model lies the Cozy Modeling Language. CML (Cozy Modeling Language) is a domain-specific language designed to describe the Object–Functional Model defined by the SimpleModeling method. It uses SmartDox as its metalanguage, allowing natural-language narratives and structured model definitions to coexist within a single document.

Models described in CML can be processed by Cozy to automatically generate programs, design documents, and other development artifacts. This enables a seamless workflow in which literate modeling and model-driven development are treated as a single continuous process.

The foundation that supports CML consists of SmartDox and ModelDox.

SmartDox is a structured document language with a lightweight syntax similar to Markdown. It provides precise handling of sections, tables, attributes, and code blocks, enabling clear hierarchical representation of technical documents. All articles and guides on SimpleModeling.org are written in SmartDox, which can be converted into HTML or AsciiDoc and published via Antora. Through AsciiDoc, SmartDox documents can also be exported as PDFs, supporting both web and print publication.

In short, SmartDox serves both as the literary foundation of the model and as a versatile document language that connects human-readable narrative with machine-processable structure.

ModelDox, on the other hand, represents the structural layer extracted and reconstructed from SmartDox documents. It sits above the SmartDox metamodel and provides a structured data representation for downstream use by DSLs and AI analysis tools. In essence, ModelDox transforms SmartDox’s human-oriented structure into machine-oriented data models.

Together, SmartDox, ModelDox, and CML form a three-layered architecture for literate modeling:

In this architecture, SmartDox provides the narrative and document structure, ModelDox converts that structure into formal data, and CML defines domain models atop it. Cozy then interprets these models to automatically generate code, documentation, and configuration artifacts. Moreover, this foundation enables the creation of additional DSLs for domain-specific, design-assistive, or technical-specification purposes.

Thus, SmartDox, ModelDox, and CML work in unison to bridge human-centered narrative with machine-centered generation and analysis, establishing the textual foundation of literate modeling.

CML is a domain-specific language that uses SmartDox as its metalanguage. It directly utilizes SmartDox’s structure—sections, tables, and attributes—as model constructs, allowing model definitions to appear naturally within the flow of prose. No special markup or external modeling tool is required; the same document serves as both readable explanation and executable model.

The following example shows how a Person entity can be described in CML as part of a literate model. The structure of headings and tables in SmartDox directly maps to the model elements interpreted by Cozy.

In this example, the hierarchical structure (Entity → Person → Attribute) and the table’s key–value definitions are automatically parsed as part of the model. At the same time, the surrounding text provides a human-readable explanation of the entity’s purpose and semantics. The document, therefore, simultaneously serves as readable documentation and as a formal model.

This approach exemplifies the essence of literate modeling: unifying human narrative and formal definition within a single text source. Every description written in SmartDox can, through ModelDox and CML, become part of a living model that AI and tools like Cozy can interpret and evolve.

CML provides a text-based domain-specific language for describing the Object–Functional Model defined in the SimpleModeling method. By using SmartDox as its metalanguage, CML unifies natural-language narratives and structured model definitions within a single document, enabling seamless collaboration between humans and AI throughout the modeling process.

Models written in CML can be processed by Cozy to automatically generate programs, documents, and configuration artifacts. In this workflow, literate modeling and implementation are directly connected, transforming written descriptions into executable structures.

Because CML is purely text-based, it requires no specialized editing tools. Models can be created and edited with any standard text editor, making it easy to adopt and maintain across different environments. Built on SmartDox syntax, both narrative and structure are preserved in plain text, which allows version control systems like Git to track every change in wording, structure, and intent. This ensures transparency, traceability, and collective evolution of design knowledge.

While CML and Cozy serve as the practical modeling and generation tools, SimpleModeling.org functions as the knowledge base (BoK (Body of Knowledge)) of the overall method. The site organizes and publishes conceptual, analytical, and procedural knowledge on modeling, design, AI collaboration, and development processes. All of its articles are written in SmartDox and deployed through Antora, forming a living, literate repository of domain knowledge.

In this ecosystem, SmartDox provides the expressive medium, CML provides the formal modeling syntax, and Cozy provides automated generation. Together, they create a continuous feedback loop in which human-authored narratives and AI-processed structures inform and refine one another. This text-based collaboration enables sustainable modeling practices where knowledge, design, and implementation coevolve.

Cozy directly operates on models written in CML. CML defines the structure and semantics of the Object–Functional Model in the SimpleModeling method, and because it uses SmartDox as its metalanguage, it inherits SmartDox’s expressive structure and textual flexibility. This layered design—Cozy ⇢ CML ⇢ SmartDox—provides both formal precision and literary readability.

Cozy interprets CML models to automatically generate artifacts such as program code, design documents, and configuration files. Through CML’s unified syntax and semantics, Cozy can treat modeling, documentation, and generation as parts of a single process, minimizing gaps between design and implementation.

The fact that CML itself is written in SmartDox brings multiple benefits:

Through this design, Cozy operates entirely on CML’s formal model data, while still inheriting SmartDox’s advantages in narrative integration and human–AI collaboration. Cozy can thus interpret text as structured knowledge—bridging the gap between written intent and executable artifacts.

Ultimately, Cozy realizes the core principle of the Literate Model: to write is to model, and to model is to generate.

Literate Model–Driven Development is a unified development process centered on the Cozy Modeling Language. It connects SmartDox, ModelDox, Cozy, and AI into a continuous pipeline—from design to generation—enabling documentation, modeling, and implementation to evolve together as a single literate process.

CML, as the modeling DSL, defines the Object–Functional Model of the SimpleModeling method using SmartDox as its metalanguage. SmartDox documents serve both as narrative and as structured data sources, from which ModelDox extracts the formal model structure. Cozy interprets this structure to generate code, documentation, and configurations, while AI ensures consistency between narrative and structure by analyzing their semantic coherence.

Because all components are text-based, version control systems such as Git can manage every change in both natural-language description and formal model definition. This allows the entire modeling lifecycle—from idea to implementation—to remain transparent, reproducible, and collaborative.

The following diagram illustrates the overall structure of the LMDD pipeline, showing how SmartDox, ModelDox, CML, Cozy, AI, and Git interact to form a literate and generative development environment.

This pipeline represents the full realization of literate modeling: writing becomes modeling, modeling becomes generation, and generation feeds back into knowledge. Through this cycle, both human understanding and AI reasoning evolve in tandem.

The Literate Model unifies narrative and structure, providing a form of knowledge representation that both humans and AI can understand and evolve together. It bridges the gap between documentation, modeling, and implementation through an integrated, text-based approach.

Using SmartDox as its foundation, Literate Modeling allows natural-language explanations and formal model structures to coexist within a single document. ModelDox extracts structural data from SmartDox, CML defines domain models as literate DSLs, and Cozy generates software artifacts based on those models. Together, they form a cohesive ecosystem for literate model–driven development.

Through this ecosystem, AI can analyze narratives, verify structural consistency, and assist in model improvement. Text-based documents thus become living artifacts—simultaneously readable, executable, and evolvable.

In essence, the Literate Model positions software development as a continuous process in which writing, understanding, and generation are interconnected. Within this framework, humans and AI collaboratively refine knowledge through an integrated cycle of expression and modeling.