Skip to main content

Core Concepts

TRF organizes traceability evidence into three layers: artifacts, links, and packages. Understanding how they connect keeps every stakeholder aligned on what evidence exists and how it was produced.

Artifacts​

Artifacts are the fundamental units stored in a TWPack. They cover requirements, tests, designs, components, hazards, datasets, models, and more. Every artifact shares the same envelope:

{
  "id": "req:ACC-001",
  "kind": "requirement",
  "version": "2.0.0",
  "status": "approved",
  "created_at": "2024-01-15T10:00:00Z",
  "fields": {
    "title": "Maintain safe distance",
    "acceptance_criteria": ["Activation within 200ms"],
    "priority": "high",
    "asil": "D"
  },
  "attachments": [
    {
      "path": "attachments/requirements/acc.pdf",
      "hash": "sha256:..."
    }
  ]
}
  • id pairs a namespace with a readable identifier (req:, test:, design:).
  • kind drives validation rules supplied by cores or extensions.
  • fields hold kind-specific data; schemas guarantee structure.

See the full catalog in Artifacts.

Links connect artifacts into a graph so you can trace coverage, dependencies, and change impact.

{
  "id": "link:L-001",
  "from": "req:ACC-001",
  "to": "test:TC-ACC-001",
  "relation": "verified_by",
  "confidence": 1.0,
  "rationale": "Regression suite TC-ACC-001 covers all acceptance criteria"
}
  • relation expresses intent (verified_by, implements, mitigated_by, etc.).
  • confidence records how strong the connection is (direct, inferred, manual).
  • rationale explains why the link exists for reviewers and auditors.

Explore relationship patterns in Links and Relations.

TWPack packages​

All artifacts and links live inside deterministic TWPack archives. Each pack includes:

  • manifest.json – package identity, generator, extension list, and statistics.
  • artifacts.jsonl – one artifact per line for easy streaming.
  • links.jsonl – all relationships.
  • signatures.json – digital signatures and certificates.
  • attachments/ – binary evidence referenced by artifacts.

Packaging rules, hashes, and validation commands are covered in TWPack Format.

Profiles and extensions​

Profiles bundle the core schema with domain extensions, default validation packs, and coverage targets. Choose a profile to bootstrap a project, then toggle extensions as needed.

{
  "profile": "automotive_safety",
  "core_types": ["requirement", "test", "design", "component"],
  "extensions": ["automotive"],
  "validation_rules": ["automotive_validation_rules"],
  "required_coverage": {
    "requirement_to_test": 0.95,
    "safety_requirement_to_mechanism": 1.0
  }
}

Profiles and extension mechanics are described in Core Schema and Extensions and Profiles.

Validation and integrity​

The CLI and validator enforce consistency:

  • Schema validation for every artifact and link.
  • Relationship checks to prevent missing or circular traces.
  • Hash and signature verification for tamper detection.
  • Timestamp and provenance checks to confirm creation context.

Automation examples live in Validator and Cryptographic Integrity.

Putting it together​

  1. Model your artifacts using the core schema plus any relevant extensions.
  2. Link them to express verification, implementation, allocation, and risk coverage.
  3. Package everything into a TWPack and sign it.
  4. Validate the pack before sharing it with suppliers, auditors, or customers.

Continue with the Quick Start to build your first package or dive into Creating Links for practical automation patterns.