compare_structures
Compare two SDMX structures to identify differences in codes, references, and versions. Get a summary and visual diff diagram for codelists, dataflows, or data structures.
Instructions
Compare two SDMX structures to identify differences.
Supports comparing different structure types with specialized logic:
**Codelists** (`structure_type="codelist"`):
- Compares actual codes (code IDs and names)
- Shows added/removed/renamed codes
- Perfect for: "What codes changed between CL_GEO v1.0 and v2.0?"
**Data Structure Definitions** (`structure_type="datastructure"`):
- Compares codelist/concept scheme references
- Shows version changes in referenced codelists
- Perfect for: "What codelists were updated in DSD v3.0?"
**Dataflows** (`structure_type="dataflow"`):
- Compares structural references (DSD, constraints)
- Perfect for: "What structures do these dataflows share?"
Args:
structure_type: Type of structure to compare:
- "codelist": Compare codes within codelists
- "datastructure" or "dsd": Compare DSD references
- "dataflow": Compare dataflow references
- "conceptscheme": Compare concept schemes
structure_id_a: First structure identifier
structure_id_b: Second structure identifier (defaults to same as A for version comparison)
version_a: Version of first structure (default "latest")
version_b: Version of second structure (default "latest")
agency_id: Agency ID (uses current endpoint's default if not specified)
show_diagram: Generate a Mermaid diff diagram (default True)
endpoint: Optional endpoint key (e.g. "FBOS", "ECB") to target a
specific provider for this call only. Defaults to the session's
current endpoint.
Returns:
StructureComparisonResult with type-specific changes:
- code_changes: For codelist comparisons
- reference_changes: For DSD/dataflow comparisons
- summary: Counts of added/removed/modified/unchanged
- mermaid_diff_diagram: Visual diff diagram
- interpretation: Human-readable explanation
Examples:
# Compare two versions of a codelist - see what codes changed
>>> compare_structures("codelist", "CL_GEO", version_a="1.0", version_b="2.0")
# Compare two different codelists - find intersection/differences
>>> compare_structures("codelist", "CL_FREQ", "CL_TIME_FREQ")
# Compare DSD versions - see what codelist references changed
>>> compare_structures("datastructure", "DSD_SDG", version_a="2.0", version_b="3.0")
# Compare two different DSDs
>>> compare_structures("datastructure", "DSD_SDG", "DSD_EDUCATION")
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endpoint | No | ||
| agency_id | No | ||
| version_a | No | latest | |
| version_b | No | latest | |
| show_diagram | No | ||
| structure_id_a | Yes | ||
| structure_id_b | No | ||
| structure_type | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Additional notes or warnings | |
| summary | Yes | Summary counts of changes | |
| structure_a | Yes | First structure being compared | |
| structure_b | Yes | Second structure being compared | |
| code_changes | No | Changes in codes (for codelist comparisons) | |
| api_calls_made | Yes | Number of SDMX API calls made | |
| interpretation | Yes | Human-readable explanation of the differences | |
| structure_type | No | Type of structures being compared: 'codelist', 'conceptscheme', 'datastructure', 'dataflow' | generic |
| comparison_type | Yes | Type of comparison: 'version_comparison' or 'cross_structure' | |
| concept_changes | No | Changes in concepts (for concept scheme comparisons) | |
| discovery_level | No | Discovery workflow level | structure_comparison |
| dimension_changes | No | Changes in dimensions (for DSD comparisons) | |
| reference_changes | No | Changes in structural references (codelists, concept schemes referenced) | |
| mermaid_diff_diagram | No | Mermaid diagram highlighting differences (green=added, red=removed, yellow=changed) |