Chapter 16. Specifications and Dashboards That Update Themselves

16.1 The reactive-documentation concept

Conventional MBSE practice produces specifications and reports as static documents (Word files, PDFs, PowerPoints) that are authored from the engineering artifacts and drift away from them as the project evolves. That drift is the principal reason late-cycle artifact changes are politically expensive. Change a requirement and you must also change the safety case document that cites it, and the documentation change costs more than the engineering change. If you've ever hesitated over a late requirement fix because of the paperwork behind it, you've felt this.

Reactive documentation inverts the relationship. The documentation isn't authored from the artifacts; it queries them at render time. Change a requirement and you've changed the artifact, and on its next render the safety case document picks up the new value automatically. The cost of late-cycle change falls dramatically, because the document maintenance has been automated away.

.spec: structured specifications

A .spec file declares a specification: a structured document built from nested def section clauses. Each section can contain def spec (free-form sections summarized from source files), def diagram (diagrams rendered from .fml, .fun, .blk, .smd, .fta and .haz files) and def table (tabular queries over the artifact set).

Sylang

hdef specification EpbSpec
  name "EPB System Specification"
  version "1.0"

  def section SafetyChain
    name "2. ISO 26262 Safety Chain"

    def table HazardsTable
      name "2.3 Hazards with ASIL allocation"
      source "System/EpbHazards.haz"
      where safetylevel in [ASIL-C, ASIL-D]
      orderby safetylevel desc
      columns identifier, name, hazardclass, malfunctionof, safetylevel

Each def table carries a source (a file path or glob naming the files to query), a where (a predicate that filters the rows), an orderby (the sort order), an optional groupby, and columns (the columns to render). At render time, the renderer reads the source files, applies the filter and produces the table. My working estimate is that even a document with fifty tables and a dozen diagrams renders in a few seconds. It re-renders identically until the underlying artifacts change.

.dash: live dashboards

A .dash file declares a dashboard: a widget grid of def metric (single-value tiles), def chart (visualizations) and def table (tabular widgets). The grid <rows>x<cols> property on the hdef sets the layout. The renderer computes each widget's position and span, and you can add an explicit span property to make a widget wider.

Sylang

hdef dashboard EpbDashboard
  grid 4x4

  def metric APPROVED_REQS
    name "Approved Requirements"
    type count
    sourcetype requirement where status = approved
    source "**/*.req"

  def chart REQS_BY_ASIL
    name "Requirements by Safety Level"
    type pie
    sourcetype requirement
    source "**/*.req"
    groupby safetylevel
    span 1x2

What follows

Subchapter 16.2 covers the shared query vocabulary: source, where, groupby, orderby and columns. Subchapter 16.3 covers the integration pattern of building the safety case as a .spec. Subchapter 16.4 closes with the EPB walkthrough and the cross-anchor mirror examples.

16.2 The query vocabulary: source, where, groupby, orderby, columns

Both .spec and .dash files use a small query vocabulary to say which artifacts a widget displays and how: source, where, groupby, orderby and columns. It is intentionally limited (not a full database query language) and intentionally consistent across the two file types, so you learn it once and use it everywhere. This subchapter takes each clause in turn.

source: which files to query

source names the file or files the query reads. It takes three forms: a single file path (source "System/EpbHazards.haz"), a list of paths (source "a.req", "b.req"), or a glob pattern (source "**/*.req"). The glob form matches every .req file anywhere in the project, because the ** wildcard matches any number of directories.

A good convention: prefer specific paths when the query is naturally bounded, and use globs for cross-cutting queries. A spec section about one block reads that block's specific .blk file, while a coverage table can query every .req file in the project. Globs are convenient, but they can reach wider than you intended. A misconfigured glob can pull in irrelevant content.

where: filtering

where applies a predicate that filters the rows returned. The predicate uses a small expression language: comparison operators (=, !=, <, <=, >, >=), set membership (in [a, b, c]) and boolean composition (and, or, not). You reference properties on the row by name.

Sylang

where safetylevel = ASIL-D
where status in [approved, implemented]
where reqtype = safety and safetylevel >= ASIL-C
where rpn >= 100
where testresult != pass

The expression language is deliberately limited: no joins, no subqueries, no arbitrary function calls. That keeps queries inspectable, because an auditor can read a where clause and understand exactly what it selects. It also keeps the renderer simple. If a query outgrows the language, factor it into several widgets or build it through .spec section composition.

groupby, orderby, columns

groupby <property> groups the rows by the named property, and the output renders one sub-section per group. Use it to organize a table by safety level, status or owner.

orderby <property> [asc|desc] sorts within each group, or globally if there's no grouping. The default direction is ascending. orderby identifier asc gives a stable order for diffing across renders, while orderby rpn desc puts the highest-priority items first.

columns <prop1>, <prop2>, ... names the properties to render as table columns in a .spec's def table widgets. The order you list them in is the column order. For column headers, the renderer uses each property's display label, typically a humanized version of the property name.

What follows

Subchapter 16.3 covers the safety-case construction pattern: the .spec file that produces the rendered safety case document. Subchapter 16.4 then walks the EPB anchor's .spec and .dash files in detail.

16.3 Constructing the safety case as a .spec file

The safety case is the principal deliverable the regulated industries require for any safety-critical item. It's a structured argument, supported by evidence drawn from the engineering artifacts, that the item is safe enough for its intended use. A conventional safety case is a Word document of several hundred to several thousand pages. A Sylang safety case is a .spec file of one or two hundred lines that renders to the same multi-hundred-page document automatically.

Safety case structure

A safety case is organized hierarchically (sections, subsections, sub-subsections) to match the content the safety standard expects. ISO 26262 safety cases roughly follow this order: overview, item definition, hazard analysis with ASIL assignment, safety goals, functional safety concept, technical safety concept, hardware safety analysis, software safety analysis, FMEA, FTA, verification, validation, conclusion. The structure is largely standardized across organizations; only the specific content differs.

A Sylang safety case .spec mirrors this structure with nested def section clauses. Each section's content materializes from the underlying artifact files through def spec, def diagram and def table widgets. The EPB anchor's EpbSpec.spec (in the companion repository) is a working example: seven top-level sections, each with two to five sub-widgets, for about twenty rendered components in all. My working estimate is that the rendered document runs to about eighty pages of structured content.

Mapping safety case sections to artifacts

Each section of the safety case maps to one or more artifact types in your project.

Safety case section	Source artifacts	Spec widget type
Overview	.ple, .fml	def spec + def diagram
Item definition	.itm	def spec
Hazard analysis	.haz	def diagram + def table
Safety goals	.sgl	def spec
Safety requirements	.req (filtered by reqtype=safety)	def table
FMEA	.flr	def diagram + def table
FTA	.fta	def diagram
Safety mechanisms	.sam	def spec + def table
Verification coverage	.tst, .req (joined via satisfies)	def table grouped by status
Conclusion + sign-off	(manual prose)	def spec

Rendering and review

Sylang Studio renders the .spec file to PDF (or HTML, or DOCX, depending on the export target) at any moment. My working estimate is a few seconds per render for a typical safety case. The safety manager reviewing the case opens the rendered PDF, scrolls through the sections and marks open issues against specific artifacts (tracking those open issues is itself a sprint task).

As the issues are resolved, the safety manager updates the underlying artifacts, and the next render reflects the changes. The safety case is never out of date with the artifact set.

What follows

Subchapter 16.4 closes the chapter with the EPB walkthrough and the cross-anchor mirrors. The chapter then concludes Part V.

16.4 EPB spec and dashboard walkthrough

This subchapter walks the EPB anchor's EpbSpec.spec and EpbDashboard.dash files, both authored in the companion repository, to close Chapter 16 and Part V. You'll see how the .spec and .dash types together produce the program-management and safety-case views from the underlying engineering artifacts.

EpbSpec.spec

Reports/EpbSpec.spec is the EPB program's principal documentation deliverable. It has seven top-level sections: Overview, Safety Chain, Requirements, Architecture, Failure Analysis, Verification and Variant-Specific Material. Each section holds two to five widgets: def spec sections summarized from source files, def diagram renderings of the engineering diagrams, and def table queries with filtering.

A few widgets stand out. A hazards table filtered to ASIL-C and ASIL-D situations gives the auditor a focused view of the high-consequence content. A high-RPN failure-modes table filtered to RPN ≥ 50 keeps the action-priority focus, and a test-coverage table is grouped by test method (HIL / SIL / manual). Each widget is two to five lines of .spec markup that renders into the corresponding multi-page section of the safety case.

As a rough illustration of the payoff: my working estimate is that the rendered EpbSpec runs to about 80 pages of structured content. Authoring the same content by hand in Word could plausibly take a senior safety engineer around two weeks up front, plus one to three days per sprint to maintain. The .spec file itself is 80 lines, and its maintenance cost is close to zero, because the document re-renders on demand from the always-current artifact state.

EpbDashboard.dash

Reports/EpbDashboard.dash is the program manager's morning view. Its 4x4 grid holds four count metrics (total requirements, approved requirements, ASIL-D requirements, ASIL-D requirements with verifying tests) and four chart widgets (requirements by ASIL, tests by method, hazard situations by ASIL, failure modes by RPN band). It also holds two table widgets: open high-priority sprint tasks, and high-RPN failure modes needing mitigation review.

The dashboard's value compounds the longer you use it. Day one shows the project state, day two shows the delta, and day ten shows the trend. Consult it every morning and you develop a calibrated sense of the program's velocity, its recurring issue patterns and its variant-specific concerns. In conventional MBSE, the underlying data would sit in three or four different tools, and no single dashboard could integrate it without substantial custom integration work.

Cross-anchor mirrors

The other anchors would have analogous .spec and .dash artifacts with domain-specific adjustments. The autopilot's spec would emphasize the DAL-A protection laws and the autoland sequencer, and its dashboard would show flight-envelope-protection metrics. The infusion pump's spec would emphasize the IEC 62304 software safety class evidence and the bolus-overdose hazard analysis, with a dashboard of clinical-deployment metrics. The cobot's spec would emphasize the IEC 61508 SIL-3 safety functions and collision-detection performance, with a dashboard of industrial-deployment metrics.

Across all four anchors, .spec and .dash provide the same affordances. The domain-specific content differs, but the structural patterns stay constant, so if you're fluent in the EPB spec you can author the cobot's spec straight away. That cross-domain consistency is what makes Sylang a language rather than four parallel domain-specific notations.

Closing Chapter 16 and Part V

You now have the reactive-documentation artifact set. We covered the structure of the .spec and .dash types (16.1), the query vocabulary they share (16.2), the safety case construction pattern (16.3), and the EPB walkthrough with cross-anchor mirrors (this subchapter).

Chapter 17, the only chapter of Part VI, closes the book by restating the strategic argument in light of the evidence the chapters in between have developed. It's short (one chapter, five subchapters) but consequential. Leaders return to it after the technical chapters, and auditors consult it for the strategic framing.

Exercises (Chapter 16)

Key takeaways

You’ve got this chapter if you remember:

Reactive documentation queries the artifacts at render time instead of being copied from them, so it doesn't drift.
A .spec builds structured documents from def section, def spec, def diagram and def table; a .dash lays out def metric, def chart and def table widgets on a grid.
Both file types share one small query vocabulary (source, where, groupby, orderby, columns) that an auditor can read and understand.
A safety case becomes a .spec whose sections map onto your .haz, .sgl, .req, .flr, .fta, .sam and .tst files.

Check yourself

Answer in your head first, then reveal.

1Why doesn't a reactive safety case fall out of date?
It queries the artifacts on every render instead of being authored from them. Change an artifact and the next render reflects it.
2Why is the where expression language deliberately limited?
Leaving out joins, subqueries and arbitrary function calls keeps every query inspectable, so an auditor can see exactly what it selects. It also keeps the renderer simple.
3When should source use a glob rather than a specific path?
Use a glob for cross-cutting queries, such as a coverage table over every .req file. Use specific paths when the query is naturally bounded, since a misconfigured glob can pull in irrelevant content.
4Which clause would put the highest-RPN failure modes at the top of a table?
orderby rpn desc, which sorts the rows by RPN in descending order.