Convert CSV to OSCAL Mapping Collection
trestle_task_csv_to_oscal_mcGenerate an OSCAL mapping-collection JSON from a formatted CSV of control-to-control correspondences, with relationship types, mapped IDs, and optional confidence and coverage scores.
Instructions
Convert a CSV file to an OSCAL mapping-collection JSON file.
This tool runs the trestle task csv-to-oscal-mc command, which reads a specially formatted CSV of control-to-control correspondences and produces mapping-collection.json — the OSCAL model for "control X over here means the same thing as controls Y and Z over there".
The CSV must have:
Row 1: column headings
Row 2: column descriptions
Row 3+: data rows
Required CSV columns:
$$Source_Resource, $$Target_Resource: for each side, a path to a catalog JSON file or an href to a profile. Both sides are loaded and every id in the ref lists is looked up in them. An id that is not found is dropped without a warning, and the row is still written with whatever ids did resolve:
ac-1 ac-99-typoon one side produces a map namingac-1only, and the run reports success. It fails only when nothing in a row's list resolves at all. So a successful run does not mean every id in the CSV made it into the output -- check the id-refs in mapping-collection.json against the CSV if the mapping has to be complete.$$Map_Source_Id_Ref_List, $$Map_Target_Id_Ref_List: whitespace-separated control ids, or statement ids such as
ac-1_smt.a. Several ids on one side are what makes a mapping many-to-many.$$Map_Relationship: the relationship type, as an NCName token. The conventional values are the NIST IR 8477 section 4.3 set-theory relationships —
equivalent,subset-of,superset-of,intersects-with,no-relationship— but trestle does not restrict the vocabulary. Leave the cell empty to declare a control unmapped: it is then recorded in the gap summary instead of producing a map entry.
Optional CSV columns:
$$Map_Confidence_Score, $$Map_Coverage: percentages expressed in the range 0 to 1, not 0 to 100. A value of 80 is silently dropped with a "Percentage value out of range" warning and the map entry is written without it; write 0.8.
Resource paths in the CSV are resolved relative to the trestle process's
working directory, which is trestle_root when you pass one and wherever
the server was started when you do not. Pass trestle_root, or use absolute
paths, so the CSV does not depend on how the server was launched.
Args: params (TrestleTaskCsvToOscalMcInput): Input parameters with: - title (str): Mapping collection title (required) - version (str): Mapping collection version (required) - csv_file (str): Path to the input CSV file (required) - output_dir (str): Output directory for mapping-collection.json (required) - output_overwrite (bool): Overwrite existing output (default: true) - trestle_root (Optional[str]): Trestle workspace root path (optional) - verbose (bool): Display verbose output (optional)
Returns: str: Success or error message with the output file location
Examples:
- Use when: "Map our internal control set onto NIST SP 800-53"
- Use when: "Produce an OSCAL mapping collection from this crosswalk
spreadsheet"
- Don't use when: You want a component definition out of a CSV; use
trestle_task_csv_to_oscal_cd.
- Don't use when: The CSV is missing a required column, or names control
ids that are not in the source or target resource.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"params": "<params>"
},
"name": "trestle_task_csv_to_oscal_mc"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |