Understanding TWPack Format

What is a TWPack?

A TWPack (Traceability Web Pack) is a self-contained archive that stores all traceability information for a project. It's like a time capsule that captures the complete development history and compliance evidence.

File Structure

The Anatomy of a TWPack

project.twpack (ZIP archive)
│
├── manifest.json        # Package metadata and configuration
├── artifacts.jsonl      # All traceable items (one per line)
├── links.jsonl         # Relationships between artifacts
├── provenance.json     # Creation and authorship information
└── attachments/        # Optional supporting files
    ├── diagrams/
    ├── reports/
    └── evidence/

Core Files Explained

1. manifest.json - The Package Blueprint

The manifest defines what's in the package and how to interpret it:

{
  "format_version": "2.0.0",
  "pack_id": "ACC-2024-001",
  "pack_type": "full",
  "profile": "automotive-safety",
  "metadata": {
    "project": "Adaptive Cruise Control",
    "version": "1.2.0",
    "asil": "C",
    "standard": "ISO 26262:2018"
  },
  "extensions": [
    "automotive/iso26262",
    "security/unr155"
  ],
  "statistics": {
    "artifacts": 1250,
    "links": 3400,
    "coverage": 0.98
  }
}

Key Fields:

• format_version: TRF specification version
• profile: Pre-configured artifact combinations
• extensions: Domain-specific artifact types
• statistics: Quick overview of contents

2. artifacts.jsonl - The Content

Each line is a complete JSON object representing one artifact:

{"id":"req:REQ-001","kind":"requirement","version":"1.0","title":"Maintain safe distance","status":"approved","created_at":"2024-01-15T10:00:00Z"}
{"id":"test:TC-001","kind":"test","version":"1.0","title":"Distance measurement test","status":"passed","created_at":"2024-01-20T14:30:00Z"}
{"id":"haz:HAZ-001","kind":"hazard","version":"1.0","title":"Rear-end collision","asil":"C","severity":3,"created_at":"2024-01-10T09:00:00Z"}

Why JSONL?

• Each line is independent (parallel processing)
• Streamable (no need to load entire file)
• Git-friendly (line-based diffs)
• Human-readable

3. links.jsonl - The Connections

Links show how artifacts relate to each other:

{"id":"link:L-001","from":"req:REQ-001","to":"test:TC-001","relation":"verified_by","confidence":0.95}
{"id":"link:L-002","from":"haz:HAZ-001","to":"req:REQ-001","relation":"mitigated_by","confidence":1.0}
{"id":"link:L-003","from":"req:REQ-001","to":"design:DES-001","relation":"implemented_by","confidence":0.90}

Common Relations:

• verified_by: Requirement verified by test
• implements: Design implements requirement
• mitigated_by: Hazard mitigated by requirement
• derived_from: Child requirement from parent
• produces: Test produces result

4. provenance.json - The History

Documents who created the pack and how:

{
  "pack_id": "ACC-2024-001",
  "created_at": "2024-01-25T16:45:00Z",
  "created_by": {
    "name": "John Smith",
    "email": "john.smith@automaker.com",
    "organization": "AutoCorp",
    "role": "Safety Engineer"
  },
  "tool": {
    "name": "TRF Generator",
    "version": "2.0.0",
    "vendor": "TraceWeave"
  },
  "sources": [
    {
      "system": "JIRA",
      "version": "8.5.1",
      "extracted_at": "2024-01-25T16:00:00Z"
    },
    {
      "system": "Git",
      "repository": "https://github.com/autocorp/acc",
      "commit": "a1b2c3d4"
    }
  ],
  "signature": {
    "algorithm": "SHA256withRSA",
    "value": "3045022100..."
  }
}

Artifact Types

Core Artifacts (Always Available)

Kind	Purpose	Example
requirement	What system must do	"System shall maintain 2-second following distance"
test	Verification method	"Measure distance at 60 km/h"
design	Implementation approach	"Radar + Camera sensor fusion"
component	Physical/software parts	"77GHz radar module"

Extension Artifacts (Domain-Specific)

Extension	Artifact Types	Use Case
Safety	hazard, fmea, safety_goal	ISO 26262 compliance
Security	threat, vulnerability, control	UN-R155 cybersecurity
AI/ML	model, dataset, metrics	AI governance
Business	risk, audit, change_request	Process compliance

Profiles - Pre-configured Templates

Available Profiles

// Minimal - Just the basics
profile: "minimal"  // 4 core types

// Automotive Safety - ISO 26262 compliant
profile: "automotive-safety"  // 16 types

// AI/ML Complete - Full AI governance
profile: "ai-ml-complete"  // 18 types

// Universal - Everything
profile: "universal-complete"  // 68 types

Working with TWPacks

Reading a TWPack

// 1. Unzip the archive
const zip = new JSZip();
await zip.loadAsync(twpackFile);

// 2. Parse manifest
const manifest = JSON.parse(
  await zip.file("manifest.json").async("string")
);

// 3. Stream artifacts
const artifacts = await zip.file("artifacts.jsonl").async("string");
artifacts.split('\n').forEach(line => {
  if (line) {
    const artifact = JSON.parse(line);
    // Process artifact
  }
});

Creating a TWPack

// 1. Prepare artifacts
const artifacts = [
  { id: "req:001", kind: "requirement", title: "..." },
  { id: "test:001", kind: "test", title: "..." }
];

// 2. Create links
const links = [
  { from: "req:001", to: "test:001", relation: "verified_by" }
];

// 3. Generate JSONL
const artifactsJsonl = artifacts.map(a => JSON.stringify(a)).join('\n');
const linksJsonl = links.map(l => JSON.stringify(l)).join('\n');

// 4. Create ZIP
const zip = new JSZip();
zip.file("manifest.json", JSON.stringify(manifest));
zip.file("artifacts.jsonl", artifactsJsonl);
zip.file("links.jsonl", linksJsonl);
zip.file("provenance.json", JSON.stringify(provenance));

// 5. Generate file
const blob = await zip.generateAsync({ type: "blob" });

Best Practices

1. Unique IDs

Use prefixed IDs for clarity:

req:REQ-001    # Requirement
test:TC-001    # Test case
haz:HAZ-001    # Hazard
design:DES-001 # Design element

2. Version Control

Track artifact versions:

{
  "id": "req:REQ-001",
  "version": "2.1.0",
  "previous_version": "2.0.0",
  "change_reason": "Updated acceptance criteria"
}

3. Confidence Scores

Use confidence to indicate link strength:

• 1.0: Direct, verified relationship
• 0.9-0.99: High confidence
• 0.7-0.89: Moderate confidence
• < 0.7: Low confidence (review needed)

4. Status Tracking

Standard status values:

• draft: Under development
• review: Awaiting approval
• approved: Formally approved
• deprecated: No longer valid
• passed/failed: For test results

Validation

TWPacks are validated at multiple levels:

1. Format validation: Valid JSON/ZIP structure
2. Schema validation: Artifacts match schemas
3. Referential integrity: All links point to existing artifacts
4. Business rules: Domain-specific requirements
5. Completeness: Required artifacts present

Next Steps

• Learn about artifacts: Artifacts
• Understand linking: Links and Relations
• Create your first pack: First Pack Tutorial