SpData

Specification and file management for SPDM mapping files.

Purpose

SpMapping defines the canonical format, constraints, and semantics of mapping files — YAML documents that record the correspondence between target data paths (e.g., IMAS IDS paths) and source data paths (e.g., device-specific MDSplus or HDF5 paths).

This repository contains:

• Specification — authoritative format definition for mapping files
• Schema — JSON Schema for validating mapping files
• Mappings — the actual mapping file library, organized by target namespace
• Scripts — tooling for validation, linting, and management of mapping files
• Docs — design notes and reference material

Repository Structure

spmapping/
├── specification/
│   └── spmapping.md           # Authoritative format specification
│
├── schema/
│   └── mapping.schema.json    # JSON Schema for mapping file validation
│
├── mappings/                  # Mapping file library
│   └── examples/              # Example / reference mappings
│
├── scripts/                   # Management and validation scripts
│   └── validate.py            # Validate a mapping file against the schema
│
└── docs/
    ├── design/                # Design notes (Chinese)
    └── guides/                # User guides (English)

Mapping File Format (quick reference)

A mapping file is a YAML document with the following top-level fields:

Field	Required	Description
$version	yes	Format version (integer)
$target_namespace	yes	Alias for the target namespace; must be a $prefixes key
$source_namespace	yes	Alias(es) for source namespace(s)
$prefixes	yes	Namespace URI prefix table
$rules	no	Explicit rules block; top-level non-$ keys are implicit rules
$metadata	no	Descriptive metadata; not used in rule matching

See specification/spmapping.md for the complete specification.

Example:

$version: 1
$target_namespace: imas/v3
$source_namespace: east/mdsplus

$prefixes:
  imas/v3     : http://imas.iter.org/3.42/
  east/mdsplus: http://mdsplus.ipp.ac.cn/#\TOP::

$metadata:
  description: Mapping from IMAS equilibrium paths to EAST MDSplus raw data
  tree_name: efit_east
  owner: spdm

equilibrium:
    time: TIME
    time_slice/*:
      boundary/type: "1"
      boundary/outline/r: "BDRY[0, 0:NBDRY[{0}]-1, {0}]"
      boundary/outline/z: "BDRY[1, 0:NBDRY[{0}]-1, {0}]"
      global_quantities/ip: "EFIT_MFILE:PLASMA[{0}]"
    time_slice/*/global_quantities/beta_pol: BETAP[{0}]
    time_slice/*/profiles_1d/f: FPOL[*,{0}]
    time_slice/*/profiles_2d/psi: "PSIRZ[*,*,{0}]"

Implementation

The reference runtime implementation of the SpMapping format is SpDM:

• Repository: https://github.com/fusion-yun/spdm
• Status: work in progress — the mapper engine is not yet complete.

SpDM is responsible for:

• Loading and parsing mapping files according to this specification.
• Resolving target path patterns against concrete request paths (wildcard matching, capture extraction).
• Routing source queries to the appropriate backend (MDSplus, HDF5, static, etc.) based on the effective source namespace alias.
• Applying $read / $write / $dtype transforms during data access.
• Merging multiple mapping files for the same $target_namespace and handling same-pattern conflicts by load order.

This repository serves as the authoritative reference for the mapping file format. Implementors building their own engines should follow specification/spmapping.md.

Validation

python scripts/validate.py mappings/examples/equilibrium.complete.yaml

Documentation

• specification/spmapping.md — full format spec
• docs/design/ — design discussions (Chinese)
• docs/guides/ — how-to guides

License

See LICENSE.