Draft: JSON-based exchange format for OFT items and reports

[redcatbear]

JSON-based exchange format for OFT Specification items and reports

Description

We propose a JSON-based exchange format for OpenFastTrace (OFT) specification items and reports. This format is intended to support both exports (unlinked items) and reports (linked/traced items) while ensuring bit-identical reproducibility when desired.

Key Features

• Header Section: Contains metadata including schema version, OFT version, parameters, and a mode marker (export or report).
• Specification Items: A flat list of items using exact OFT terminology. The covering list is simplified to only include target IDs.
• Tracing Details: An optional section per item (for report mode) containing linkage status, coverage results, and defect markers.
• Report Summary: An optional global summary for traced results.
• Reproducibility: The timestamp is optional. For bit-identical output, it should be omitted, and all lists/keys should be sorted.

Draft Format Example (Report Mode)

{
  "header": {
    "schema_version": "1.0",
    "oft_version": "4.5.0",
    "mode": "report",
    "timestamp": "2026-05-24T20:09:00Z",
    "parameters": {
      "input_paths": ["src/main/resources/specs"],
      "output_format": "json",
      "wanted_artifact_types": ["req", "dsn", "impl"],
      "show_origin": true
    }
  },
  "specification_items": [
    {
      "id": "req-data-storage-1",
      "version": 1,
      "doctype": "req",
      "shortdesc": "Data Storage Requirement",
      "status": "approved",
      "sourcefile": "specs/requirements.md",
      "sourceline": 42,
      "description": "The system shall store data in a JSON format.",
      "coverage": {
        "needed_coverage_types": ["dsn"]
      },
      "covering": [
        { "id": "feat-json-export-1" }
      ],
      "tracing_details": {
        "is_defect": false,
        "shallow_coverage_status": "COVERED",
        "deep_coverage_status": "COVERED",
        "covered_artifact_types": ["dsn"],
        "uncovered_artifact_types": [],
        "links": [
          {
            "target_id": "dsn-json-storage-1",
            "target_version": 1,
            "target_doctype": "dsn",
            "status": "covered shallow",
            "direction": "incoming"
          }
        ]
      }
    }
  ],
  "report_summary": {
    "result_status": "OK",
    "total_item_count": 1,
    "defect_item_count": 0,
    "coverage_statistics": {
      "fully_covered": 1,
      "partially_covered": 0,
      "uncovered": 0
    }
  }
}

Reproducibility Guidelines

1. Omit header.timestamp.
2. Sort specification_items by id then version.
3. Sort all nested lists (e.g., links, covering, covered_artifact_types).
4. Sort keys alphabetically within all objects.