Skip to main content

Artifacts

Artifacts capture every traceable unit of evidence in TRF. Requirements, tests, designs, components, hazards, threats, datasets, and more all share the same envelope so tools can reason about them consistently.

Artifact Envelope​

{
  "id": "req:REQ-ACC-001",
  "kind": "requirement",
  "version": "2.0.0",
  "status": "approved",
  "created_at": "2024-01-15T10:00:00Z",
  "created_by": {
    "name": "Jane Smith",
    "email": "jane.smith@example.com"
  },
  "source": {
    "system": "JIRA",
    "id": "AUTO-1234"
  },
  "fields": {
    "title": "Maintain safe following distance",
    "description": "The ACC system shall maintain...",
    "priority": "high",
    "asil": "C"
  }
}
  • id: globally unique with namespace prefix.
  • kind: artifact type that drives validation and relationships.
  • version/status: track lifecycle.
  • created_by and source: provenance metadata.
  • fields: kind-specific payload (schema enforced by profiles/extensions).

Core Artifact Types​

Requirement​

{
  "id": "req:REQ-001",
  "kind": "requirement",
  "fields": {
    "title": "Emergency braking activation",
    "description": "System shall apply maximum braking force when collision is imminent",
    "rationale": "Prevent or minimize collision impact",
    "acceptance_criteria": [
      "Activation within 200ms",
      "Deceleration > 0.8g"
    ],
    "priority": "critical",
    "type": "functional"
  }
}

Key fields: title, description, rationale, acceptance_criteria, type (functional, performance, interface, etc.).

Test​

{
  "id": "test:TC-001",
  "kind": "test",
  "fields": {
    "title": "Emergency braking response time",
    "objective": "Verify system activates within 200ms",
    "preconditions": ["Vehicle speed > 30 km/h", "System enabled"],
    "procedure": [
      "1. Set vehicle speed to 50 km/h",
      "2. Trigger collision scenario",
      "3. Measure activation time"
    ],
    "expected_result": "Braking activated < 200ms",
    "test_type": "system",
    "test_level": "integration"
  }
}

Test kinds span unit, integration, system, and acceptance levels.

Design​

{
  "id": "design:DES-001",
  "kind": "design",
  "fields": {
    "title": "Sensor Fusion Architecture",
    "description": "Combines radar, camera, and lidar data",
    "specification": {
      "inputs": ["radar_data", "camera_feed", "lidar_points"],
      "processing": "Kalman filter fusion",
      "output": "unified_object_list",
      "update_rate": "50Hz"
    },
    "rationale": "Redundancy and accuracy",
    "interfaces": ["CAN", "Ethernet"],
    "design_type": "architectural"
  }
}

Component​

{
  "id": "comp:COMP-001",
  "kind": "component",
  "fields": {
    "name": "Continental ARS540 Radar",
    "type": "hardware",
    "version": "4.2.1",
    "manufacturer": "Continental AG",
    "part_number": "ARS540-21",
    "specifications": {
      "range": "300m",
      "fov": "±60°",
      "frequency": "77GHz"
    },
    "certifications": ["ISO 26262 ASIL B"],
    "datasheet": "attachments/ARS540_datasheet.pdf"
  }
}

Extended Artifact Types​

Safety (ISO 26262)​

{
  "kind": "hazard",
  "fields": {
    "description": "Unintended acceleration",
    "operational_situation": "Highway driving",
    "harm": "Rear-end collision",
    "severity": 3,
    "exposure": 4,
    "controllability": 2,
    "asil": "C"
  }
}
{
  "kind": "safety_goal",
  "fields": {
    "goal": "Prevent unintended acceleration",
    "asil": "C",
    "fault_tolerant_time_interval": "150ms",
    "safe_state": "Disable ACC and alert driver"
  }
}

Security (UN-R155)​

{
  "kind": "threat",
  "fields": {
    "description": "Remote code execution via OTA",
    "stride_category": "tampering",
    "attack_vector": "network",
    "impact": "critical",
    "likelihood": "medium",
    "risk_level": "high"
  }
}
{
  "kind": "vulnerability",
  "fields": {
    "cve": "CVE-2024-1234",
    "component": "OTA update handler",
    "severity": "HIGH",
    "cvss_score": 7.5,
    "status": "mitigated",
    "patch": "v2.3.4"
  }
}

AI/ML​

{
  "kind": "model",
  "fields": {
    "name": "PedestrianDetector",
    "version": "3.2.0",
    "type": "CNN",
    "framework": "TensorFlow 2.10",
    "metrics": {
      "accuracy": 0.9987,
      "precision": 0.9991,
      "recall": 0.9985,
      "inference_time_ms": 12
    },
    "training": {
      "dataset": "dataset:COCO-PED-001",
      "epochs": 100,
      "batch_size": 32
    }
  }
}
{
  "kind": "dataset",
  "fields": {
    "name": "Urban Pedestrian Dataset",
    "version": "2.1",
    "size_gb": 450,
    "samples": 1000000,
    "split": {"train": 0.7, "validation": 0.15, "test": 0.15},
    "augmentations": ["rotation", "flip", "brightness"],
    "annotation_type": "bounding_box"
  }
}

Lifecycle and Versioning​

  • Status values: draft, review, approved, rejected, deprecated, superseded.
  • Immutability: create a new version rather than editing approved content.
{
  "id": "req:REQ-001",
  "version": "2.1.0",
  "previous_version": "2.0.0",
  "change_log": [
    {
      "version": "2.1.0",
      "date": "2024-01-20",
      "changes": ["Updated acceptance criteria"],
      "changed_by": "john.doe@example.com"
    }
  ]
}

Relationships​

[
  { "from": "req:REQ-001", "to": "test:TC-001", "relation": "verified_by" },
  { "from": "design:DES-001", "to": "req:REQ-001", "relation": "implements" },
  { "from": "haz:HAZ-001", "to": "sg:SG-001", "relation": "mitigated_by" },
  { "from": "comp:COMP-001", "to": "design:DES-001", "relation": "realizes" }
]

Practices and Conventions​

  • ID prefixes: req:, test:, design:, comp:, haz: keep artifacts searchable.
  • Granularity: avoid oversized catch-all records or trivial fragments.
{ "title": "ACC System Requirements", "description": "All requirements for ACC..." }
{ "title": "Button color", "description": "Button shall be blue" }
{ "title": "ACC activation control", "description": "Driver shall activate ACC via steering wheel button" }
  • Completeness checklist: what, why, verification, owner, timestamps, source system.
  • Immutability:
// Wrong
artifact.description = "New description";

// Right
const newVersion = {
  ...artifact,
  version: "2.0.0",
  previous_version: "1.0.0",
  change_reason: "Clarified acceptance criteria"
};

Validation Rules​

KindRequired fields
requirementtitle, description, acceptance_criteria
testtitle, procedure, expected_result
designtitle, specification
componentname, type, version
const requirementSchema = {
  title: { type: "string", minLength: 10, maxLength: 200 },
  priority: { enum: ["low", "medium", "high", "critical"] },
  asil: { enum: ["QM", "A", "B", "C", "D"] }
};

Metrics​

const requirements = artifacts.filter(a => a.kind === "requirement");
const tested = requirements.filter(r =>
  links.some(l => l.from === r.id && l.relation === "verified_by")
);
const coverage = tested.length / requirements.length;

Quality indicators: completeness (required fields), consistency (no conflicts), clarity (plain language), testability (measurable acceptance criteria).

Next Steps​