JSON Output & Diagnostics Rendering

The JSON Output and Diagnostics system in cheMD provides a machine-readable representation of the chemical experiment document and a structured feedback mechanism for validation. While the HTML renderer focuses on human-readable previews, the JSON renderer serializes the normalized Abstract Syntax Tree (AST), resolved object graphs, and all warnings or errors encountered during the multi-stage pipeline.

This module ensures that chemd documents can be integrated into broader laboratory informatics systems, such as Electronic Lab Notebooks (ELN) or automated data pipelines, by providing a stable, structured data contract.

JSON Rendering Architecture

The JSON renderer is a terminal stage in the system pipeline. It consumes the resolved document and the final render options to produce a serialized payload. Unlike semantic blocks which maintain strict separation from styling, the JSON output explicitly includes the resolved render profile and options as separate metadata fields.

JSON Payload Structure

A conforming JSON export includes several top-level components to represent the full state of the document.

Sources: chemd-v0.1-architecture.md:144-150, chemd-v0.1-spec.md:522-530

Data Flow for JSON Export

The following diagram illustrates how data flows from the initial source through the pipeline into the final JSON representation.

The diagram shows the parallel collection of diagnostics and the merging of resolved AST with render metadata.
Sources: chemd-v0.1-architecture.md:88-106, packages/compiler/tests/compiler.test.ts:16-55

Diagnostics System

The diagnostics system is designed to be local and non-catastrophic. Errors in specific blocks or profile selections do not crash the entire rendering process but are instead reported as structured objects with location metadata.

Diagnostic Data Model

Every diagnostic entry follows a standard interface to allow UI components (like the playground diagnostics panel) to highlight relevant source lines.

interface Diagnostic {
  code: string;
  severity: 'info' | 'warning' | 'error';
  message: string;
  position?: {
    start: { line: number; column: number };
    end: { line: number; column: number };
  };
  nodeId?: string;
}

Sources: chemd-v0.1-architecture.md:274-282, packages/parser/src/frontmatter/parse-frontmatter.ts:40-57

Severity Levels and Mandatory Codes

The system categorizes issues to help users distinguish between critical syntax failures and helpful suggestions.

• Error (error): Prevents correct interpretation of a block (e.g., E_DUPLICATE_ID, E_MISSING_REQUIRED_FIELD, E_TEMPLATE_CYCLE).
• Warning (warning): Semantic or non-critical issues (e.g., W_UNRESOLVED_REFERENCE, W_UNKNOWN_FIELD, W_UNKNOWN_RENDER_PROFILE).
• Info (info): General information regarding the parsing process.

Sources: chemd-v0.1-architecture.md:284-298, chemd-v0.1-spec.md:465-485

Implementation Details

Parsing and Diagnostic Collection

Diagnostics are generated primarily during the parsing and resolution phases. For example, the frontmatter parser validates keys like id, title, and date, emitting E_MISSING_REQUIRED_FRONTMATTER_KEY if they are absent.

// Example diagnostic generation for missing keys
for (const requiredKey of REQUIRED_FRONTMATTER_KEYS) {
  if (!seenKeys.has(requiredKey)) {
    diagnostics.push(
      createFrontmatterDiagnostic(
        "E_MISSING_REQUIRED_FRONTMATTER_KEY",
        "error",
        `Missing required frontmatter key: ${requiredKey}`,
        anchorLineIndex
      )
    );
  }
}

Sources: packages/parser/src/frontmatter/parse-frontmatter.ts:474-488

Serialization and Adapter Payloads

The JSON output often includes a RenderAdapterPayload, which maps generic render options (like bondLength) to specific engine settings (like RDKit's fixedBondLength). This ensures that the machine-readable output contains all data necessary to reproduce visual results in external tools.

{
  "render": {
    "profileId": "publication-acs",
    "adapter": {
      "rdkit": {
        "fixedBondLength": 32,
        "bondLineWidth": 1.4
      }
    }
  }
}

Sources: packages/renderer-json/tests/renderer-json.test.ts:25-39, packages/renderer-docx/src/index.ts:10-23

Conclusion

The JSON Output & Diagnostics Rendering system serves as the technical backbone for interoperability in the cheMD project. By serializing the full document state alongside a comprehensive list of diagnostics, it allows developers to build robust tools for experiment validation and data export, ensuring that every transformation in the pipeline is transparent and traceable.