# Semantic Exchange — Structural Mapping & Analysis

This directory holds the **sssom-py-compatible structural mapping** and the human-readable analysis docs that accompany the D4D ↔ RO-Crate / FAIRSCAPE semantic exchange layer.

The **canonical** SKOS TTL and the label-level / URI-level SSSOM TSVs live under [`src/data_sheets_schema/semantic_exchange/`](../../src/data_sheets_schema/semantic_exchange/). This directory is intentionally lean — only files that aren't already in the canonical source tree.

## Files

### Structural mapping (canonical here)

| File | Description |
|---|---|
| `d4d_rocrate_structural_mapping.sssom.tsv` | 17-column structural SSSOM (sssom-py compatible). Captures D4D slot range / multivalued / RO-Crate value-type metadata for every mapped slot. Generated by `make gen-sssom-structural`. |

### Analysis & documentation

| File | Description |
|---|---|
| `d4d_rocrate_structural_mapping_summary.md` | Human-readable summary of structural mapping coverage |
| `STRUCTURAL_MAPPING_ANALYSIS.md` | Type-compatibility analysis between LinkML ranges and RO-Crate value types |
| `uri_mapping_recommendations.md` | URI-level mapping rationale and recommendations for unmapped slots |

## Where the other artifacts live

| Artifact | Canonical path |
|---|---|
| SKOS TTL (authoritative source of all alignments) | `src/data_sheets_schema/semantic_exchange/d4d_rocrate_skos_alignment.ttl` |
| Semantic SSSOM (label-level, 19-col) | `src/data_sheets_schema/semantic_exchange/d4d_rocrate_sssom_mapping.tsv` |
| Interface-only subset SSSOM (curated Google-Sheet seed) | `src/data_sheets_schema/semantic_exchange/d4d_rocrate_sssom_mapping_subset.tsv` |
| URI-level SSSOM (slots with `slot_uri`) | `src/data_sheets_schema/semantic_exchange/d4d_rocrate_sssom_uri_mapping.tsv` |
| URI-level SSSOM (all D4D attributes) | `src/data_sheets_schema/semantic_exchange/d4d_rocrate_sssom_uri_comprehensive.tsv` |
| Comprehensive label-level SSSOM (all D4D attributes) | `src/data_sheets_schema/semantic_exchange/d4d_rocrate_sssom_comprehensive.tsv` |

Regenerate everything with:

```bash
make gen-sssom-all
```

See [`docs/semantic_exchange.md`](../../docs/semantic_exchange.md) for the user-facing overview and the `/d4d-add-mapping` workflow.
