Introduction and Concepts

Why generate documents from the model

A systems engineering report — a mass rollup, a requirements traceability matrix, an interface listing — restates what the model already knows. Writing it by hand means it is wrong the day after the model changes. OpenSysML's document-generation engine instead treats the report itself as part of the model: queries say what to collect, a document definition says how to arrange it, and rendering is a compilation step. Regenerating the document is rerunning one command.

The pipeline

model → queries → document plan → document tree → Markdown or HTML → (PDF)

1. The model is ordinary SysML v2: parts, attributes, requirements, connections, views. Nothing about it is document-specific.
2. Queries are calc defs specializing DocumentQueries::Query. Each one composes library operations — collect owned elements or descendants, filter by type, name, metadata or attribute value, traverse relationships, order, project columns — into a reusable, parameterized question about the model, or about the objects a session has instantiated from it: bound to one, the same operations read the values it holds now and Verdicts checks its constraints and requirements.
3. A document definition is a part def specializing DocumentQueries::Document. Its nested parts are the document's content in declaration order: sections, paragraphs, tables, lists and diagrams. Blocks that carry data name a query and bind its parameters.
4. The engine compiles the definition into an immutable document plan, validating structure, query references and bindings up front — a mistake is a typed error at planning time, not a half-rendered artifact.
5. Evaluating the plan runs every query and produces an immutable, backend-neutral document tree: the fully-resolved title, sections, text runs, table rows, list items and diagram renderings.
6. A backend writes the tree out. The Markdown backend writes deterministic CommonMark; the HTML backend writes semantic HTML whose sysml- classes and data- attributes keep each node's model facts, so a stylesheet can address them. The PDF path converts the Markdown with an external engine (WeasyPrint, pandoc or Prince).

The vocabulary

Everything the engine understands is declared in one bundled library package, DocumentQueries. It is a non-normative OpenSysML extension — the types are ordinary SysML v2 declarations, so a model using them still parses everywhere, but only OpenSysML gives them document semantics.

Query operations (each a calc def taking and returning ordered element sequences):

Operation	What it does
OwnedElements	The direct children of each source element
Descendants	Children transitively, to a depth bound
Ancestors	Owners transitively, to a depth bound
RelatedElements	Elements reachable over one named relationship kind — specialization, subsetting, redefinition, typing, connection, allocation, satisfaction or verification — outgoing or incoming, to a depth bound
WhereType	Keep elements of a metamodel type
WhereMetadata	Keep elements annotated with a metadata definition
WhereName	Keep elements whose name passes a comparison
WhereFeature	Keep elements whose attribute value passes a comparison
OrderBy	Sort by a property, with explicit missing- and multiple-value policies
Project	Turn elements into rows of named, typed columns — declared properties, computed Column expressions, typed row cells and member-path paths, and RelatedColumn cells holding the elements a relationship reaches from each row, their count or whether there are any
Objects	The objects the session holds that are of a type, each under its path; every other operation accepts an object where it accepts an element and reads what the object holds (Objects the session holds)
Verdicts	One row per assertion checked on the object behind each source row — its verdict, path, kind and reason (Which constraints and requirements hold)
WhereRelated	Keep elements by whether at least one element is reachable over a named relationship kind (exists = true, the default) or none is (exists = false) — the coverage filter behind "which requirements does nothing satisfy" (Coverage)
Except	The rows of one sequence not present in another, once each in order
Union	One sequence followed by the rows of another not already present, each once

Document queries are one of several query surfaces the project has; Which query is which draws the boundaries between them.

Document content blocks (each a part def nested inside a document or section):

Block	What it renders
Section	A titled heading with nested content
Paragraph	Static text, inline runs, or one query's values
Span, Link, Ref	Inline runs inside a paragraph: styled text, a URL link, a cross-reference to another block
Table	A query's rows as a table, optionally grouped by a column
List	A query's values as a bullet or numbered list
Diagram	A view or element drawn by the view engine, as a Mermaid diagram or table

What "deterministic" means here

The same model renders to byte-identical Markdown or HTML every time: queries preserve model declaration order unless an OrderBy says otherwise, ordering policies for missing and duplicate keys are explicit parameters rather than accidents, and the renderer escapes content so model text can never corrupt document structure. PDF output adds an external converter to the loop; its guarantees are narrower and spelled out in Outputs.

Where to go next

Getting started builds the smallest working document. If you already have the shape in mind, the query cookbook and document authoring chapters are reference-style and can be read in any order.