Core Schema and Extensions

TRF starts with four universal artifact types and layers domain extensions on top. Core artifacts guarantee interoperability, while extensions add specialized fields, relationships, and validation rules without breaking compatibility.

Core Artifact Types

requirement

• Required fields: id, type=requirement, title, content, created, hash.
• Optional fields: priority, status, source, assignee, tags, modified.

{
  "id": "req:FUNC-001",
  "type": "requirement",
  "title": "System response time",
  "content": "The system shall respond to user input within 100ms",
  "priority": "high",
  "status": "approved",
  "source": "stakeholder-interview-2024-01-15",
  "assignee": "requirements-team",
  "tags": ["performance", "user-interface"],
  "created": "2024-01-15T10:30:00Z",
  "modified": "2024-01-18T14:20:00Z",
  "hash": "sha256:a1b2c3d4e5f6..."
}

test

• Required fields: id, type=test, title, status, created, hash.
• Optional fields: description, procedure, environment, results, coverage, executed.

{
  "id": "test:UNIT-TC-042",
  "type": "test",
  "title": "Response time validation",
  "description": "Validates system response time under normal load",
  "status": "passed",
  "procedure": "Execute automated performance test suite",
  "environment": "test-env-v2.1",
  "results": {
    "success": true,
    "average_response_time": 85,
    "max_response_time": 98,
    "iterations": 1000
  },
  "coverage": {
    "requirements": ["req:FUNC-001", "req:PERF-002"],
    "code_coverage": 0.95,
    "branch_coverage": 0.87
  },
  "created": "2024-01-20T14:45:00Z",
  "executed": "2024-01-20T14:45:30Z",
  "hash": "sha256:d4e5f6g7h8i9..."
}

design

• Required fields: id, type=design, title, created, hash.
• Optional fields: description, methodology, components, interfaces, constraints, rationale, attachments.

{
  "id": "design:ARCH-001",
  "type": "design",
  "title": "System architecture",
  "description": "High-level system architecture showing major components",
  "methodology": "layered-architecture",
  "components": ["component:web-server", "component:application-server", "component:database"],
  "interfaces": [
    {
      "from": "component:web-server",
      "to": "component:application-server",
      "protocol": "https",
      "data_format": "json"
    }
  ],
  "constraints": [
    "Must support 1000 concurrent users",
    "Database must be ACID compliant"
  ],
  "rationale": "Layered architecture provides separation of concerns and scalability",
  "attachments": [
    {
      "filename": "architecture-diagram.png",
      "path": "attachments/design/architecture-diagram.png",
      "type": "diagram"
    }
  ],
  "created": "2024-01-12T09:00:00Z",
  "hash": "sha256:j1k2l3m4n5o6..."
}

component

• Required fields: id, type=component, title, created, hash.
• Optional fields: description, version, location, language, framework, dependencies, interface, build_info.

{
  "id": "component:web-server",
  "type": "component",
  "title": "Web Server Module",
  "description": "HTTP/HTTPS web server handling client requests",
  "version": "2.1.3",
  "location": "src/webserver/",
  "language": "python",
  "framework": "flask",
  "dependencies": ["component:auth-module", "component:logging-service"],
  "interface": {
    "endpoints": ["GET /api/v1/status", "POST /api/v1/data"],
    "data_formats": ["json", "xml"]
  },
  "build_info": {
    "build_id": "build-2024-01-20-001",
    "commit_hash": "abc123def456",
    "build_timestamp": "2024-01-20T12:00:00Z"
  },
  "created": "2024-01-08T16:20:00Z",
  "hash": "sha256:p7q8r9s0t1u2..."
}

Domain Extensions

Extensions inherit from core types and apply domain rules.

Automotive

Adds hazard and safety constructs for ISO 26262 and UN regulations:

{
  "hazard": {
    "extends": "requirement",
    "properties": {
      "severity": {"enum": ["minor", "major", "severe", "catastrophic"]},
      "exposure": {"enum": ["rare", "unlikely", "possible", "probable"]},
      "controllability": {"enum": ["controllable", "difficult", "uncontrollable"]},
      "asil_level": {"enum": ["QM", "A", "B", "C", "D"]}
    }
  },
  "safety_goal": {
    "extends": "requirement",
    "properties": {
      "asil_level": {"enum": ["A", "B", "C", "D"]},
      "hazard_ids": {"type": "array", "items": {"type": "string"}}
    }
  },
  "safety_requirement": {
    "extends": "requirement",
    "properties": {
      "asil_level": {"enum": ["QM", "A", "B", "C", "D"]},
      "safety_goal_id": {"type": "string"},
      "allocation": {"enum": ["hardware", "software", "human"]}
    }
  }
}

AI/ML

Captures dataset lineage, model metadata, and experiment parameters:

{
  "dataset": {
    "extends": "component",
    "properties": {
      "size": {"type": "integer"},
      "format": {"enum": ["csv", "json", "parquet", "images"]},
      "split": {"enum": ["train", "validation", "test"]},
      "annotation_quality": {"type": "number", "minimum": 0, "maximum": 1},
      "bias_metrics": {"type": "object"}
    }
  },
  "model": {
    "extends": "component",
    "properties": {
      "framework": {"enum": ["tensorflow", "pytorch", "scikit-learn"]},
      "architecture": {"type": "string"},
      "parameters": {"type": "integer"},
      "training_data": {"type": "string"},
      "performance_metrics": {"type": "object"}
    }
  },
  "experiment": {
    "extends": "test",
    "properties": {
      "hyperparameters": {"type": "object"},
      "training_duration": {"type": "number"},
      "hardware": {"type": "string"},
      "reproducibility_hash": {"type": "string"}
    }
  }
}

Medical Device

Supports IEC 62304 and ISO 14971 artifacts:

{
  "risk_analysis": {
    "extends": "design",
    "properties": {
      "risk_level": {"enum": ["low", "medium", "high"]},
      "severity": {"enum": ["negligible", "minor", "serious", "critical", "catastrophic"]},
      "probability": {"enum": ["remote", "unlikely", "possible", "probable", "frequent"]},
      "mitigation_measures": {"type": "array", "items": {"type": "string"}}
    }
  },
  "clinical_evaluation": {
    "extends": "test",
    "properties": {
      "study_type": {"enum": ["clinical_trial", "literature_review", "post_market"]},
      "patient_count": {"type": "integer"},
      "duration": {"type": "string"},
      "endpoints": {"type": "array", "items": {"type": "string"}}
    }
  }
}

Relationship Catalog

Core relationships apply universally:

{
  "core_relationships": {
    "satisfies": {
      "description": "Implementation satisfies requirement",
      "valid_from": ["component", "design", "test"],
      "valid_to": ["requirement"]
    },
    "tests": {
      "description": "Test validates artifact",
      "valid_from": ["test"],
      "valid_to": ["requirement", "component", "design"]
    },
    "derives_from": {
      "description": "Artifact derived from higher-level artifact",
      "valid_from": ["requirement", "design"],
      "valid_to": ["requirement", "design"]
    },
    "depends_on": {
      "description": "Artifact depends on another artifact",
      "valid_from": ["component"],
      "valid_to": ["component"]
    },
    "implements": {
      "description": "Component implements design or requirement",
      "valid_from": ["component"],
      "valid_to": ["design", "requirement"]
    },
    "refines": {
      "description": "Detailed version of higher-level artifact",
      "valid_from": ["requirement", "design"],
      "valid_to": ["requirement", "design"]
    }
  }
}

Extensions add their own link semantics:

{
  "automotive_relationships": {
    "mitigates": {
      "description": "Safety mechanism mitigates hazard",
      "valid_from": ["safety_requirement", "component"],
      "valid_to": ["hazard"]
    },
    "allocated_to": {
      "description": "Requirement allocated to system element",
      "valid_from": ["safety_requirement"],
      "valid_to": ["component"]
    }
  },
  "ml_relationships": {
    "trained_on": {
      "description": "Model trained on dataset",
      "valid_from": ["model"],
      "valid_to": ["dataset"]
    },
    "validates": {
      "description": "Dataset validates model performance",
      "valid_from": ["dataset"],
      "valid_to": ["model"]
    }
  }
}

Validation Layers

Validation operates in four layers:

1. Structure — JSON schema compliance for core and extension types.
2. Semantic — Domain rules (e.g., ASIL decomposition, dataset quality thresholds).
3. Relationship — Consistency checks on traces and allocations.
4. Integrity — Hash and signature verification.

Example commands:

tw validate package.twpack --level core
tw validate package.twpack --domain automotive --check-asil-decomposition
tw validate package.twpack --check-links
tw validate package.twpack --full

The combination of core schema and modular extensions delivers universal compatibility while preserving domain-specific rigor.