2025-11-23T02:07:17.015845

Generating CodeMeta using declarative mapping rules: An open-ended approach using ShExML

GarcÃa-GonzÃ¡lez

Nowadays, software is one of the cornerstones when conducting research in several scientific fields which employ computer-based methodologies to answer new research questions. However, for these experiments to be completely reproducible, research software should comply with the FAIR principles, yet its metadata can be represented following different data models and spread across different locations. In order to bring some cohesion to the field, CodeMeta was proposed as a vocabulary to represent research software metadata in a unified and standardised manner. While existing tools can help users to generate CodeMeta files for some specific use cases, they fall short on flexibility and adaptability. Hence, in this work, I propose the use of declarative mapping rules to generate CodeMeta files, illustrated through the implementation of three crosswalks in ShExML which are then expanded and merged to cover the generation of CodeMeta files for two existing research software artefacts. Moreover, the outputs are validated using SHACL and ShEx and the whole generation workflow is automated requiring minimal user intervention upon a new version release. This work can, therefore, be used as an example upon which other developers can include a CodeMeta generation workflow in their repositories, facilitating the adoption of CodeMeta and, ultimately, increasing research software FAIRness.

academic

Generating CodeMeta using declarative mapping rules: An open-ended approach using ShExML

基本信息

论文ID: 2510.09172
标题: Generating CodeMeta using declarative mapping rules: An open-ended approach using ShExML
作者: Herminio García-González (Kazerne Dossin, Mechelen, Belgium)
分类: cs.DL (Digital Libraries), cs.SE (Software Engineering)
发表时间: 2025年10月10日 (arXiv预印本)
论文链接: https://arxiv.org/abs/2510.09172v1

摘要

当今，软件是多个科学领域进行研究的基石之一，这些领域采用基于计算机的方法来回答新的研究问题。然而，为了使这些实验完全可重现，研究软件应当符合FAIR原则，但其元数据可能遵循不同的数据模型并分散在不同位置。为了为该领域带来一些凝聚力，CodeMeta被提出作为一个词汇表，以统一和标准化的方式表示研究软件元数据。虽然现有工具可以帮助用户为某些特定用例生成CodeMeta文件，但它们在灵活性和适应性方面存在不足。因此，本文提出使用声明式映射规则来生成CodeMeta文件，通过在ShExML中实现三个交叉映射来说明，然后扩展和合并这些映射以涵盖两个现有研究软件工件的CodeMeta文件生成。此外，使用SHACL和ShEx验证输出，整个生成工作流程自动化，在新版本发布时只需最少的用户干预。

研究背景与动机

问题定义

研究软件FAIR合规性问题：研究软件虽然是科学研究的重要支撑，但其元数据分散在不同平台（GitHub、Zenodo、Maven等），使用不同的数据模型，缺乏统一性。
现有工具的局限性：
- 大多数工具只支持一对一转换（单一元数据源到CodeMeta）
- 缺乏灵活性和适应性
- 需要用户手动干预进行数据协调
- 自动化能力不足
CodeMeta采用障碍：虽然CodeMeta提供了统一的研究软件元数据表示标准，但现有工具的限制阻碍了其广泛采用。

研究重要性

开放科学推进：符合FAIR原则的研究软件对于实现开放科学至关重要
可重现性保障：统一的元数据标准有助于研究结果的可重现性
跨平台互操作性：解决不同平台间元数据格式不兼容的问题

核心贡献

提出声明式映射规则方法：使用ShExML语言创建灵活、可维护的CodeMeta生成规则
实现三个关键交叉映射：为GitHub、Maven和Zenodo平台开发了完整的ShExML映射实现
构建统一映射框架：展示了如何合并多个异构元数据源生成单一CodeMeta文件
开发完整自动化工作流：包括JSON-LD框架化、SHACL/ShEx验证和GitHub Actions集成
提供实际应用案例：在ShExML引擎和DMAOG两个开源项目中成功部署

方法详解

任务定义

输入：来自多个异构元数据提供者的数据（GitHub API、Maven POM文件、Zenodo记录等）输出：符合CodeMeta 3.0规范的标准化JSON-LD文件 约束条件：保持数据语义完整性，支持自动化更新，确保输出验证通过

核心方法架构

1. ShExML声明式映射语言

ShExML包含两个主要组件：

声明部分：
- 前缀定义（IRI快捷方式）
- 数据源定义（输入文件位置）
- 函数定义（扩展基础功能）
- 迭代器定义（数据提取方式）
- 表达式定义（合并不同来源的数据）
生成部分：
- 形状定义（RDF图生成规则）
- 主体-谓词-客体三元组构建

2. 三个核心交叉映射实现

GitHub映射（示例代码）：

PREFIX codemeta: <https://w3id.org/codemeta/3.0/>
PREFIX schema: <http://schema.org/>
SOURCE repo_info <https://api.github.com/repos/herminiogg/ShExML>
ITERATOR gh <jsonpath: $> {
    FIELD id <id>
    FIELD name <name>
    FIELD description <description>
    // ... 更多字段
}
schema:SoftwareSourceCode ex:[md.name] {
    a schema:SoftwareSourceCode ;
    schema:identifier [md.id] ;
    schema:name [md.name] ;
    // ... 更多属性映射
}

Maven映射：使用XPath查询XML格式的POM文件，处理命名空间和依赖关系映射。

Zenodo映射：处理嵌套的JSON结构，包括作者、机构等多层次实体关系。

3. 统一映射策略

智能源选择：当多个源包含相同属性时，基于语义相关性和维护便利性选择最佳源
硬编码值补充：对于无法从外部源获取的数据，允许在映射文件中直接定义
数据转换函数：处理日期格式转换、URL标准化等数据清理任务

技术创新点

多源数据融合：不同于现有工具的一对一转换，支持任意数量异构源的灵活合并
声明式规则：相比程序化方法，提供更好的可读性、可维护性和可共享性
细粒度控制：允许属性级别的精确映射控制，而非简单的优先级覆盖
自动化集成：完整的CI/CD工作流集成，支持版本发布时的自动更新

实验设置

测试项目

ShExML引擎：Scala编写的异构数据映射工具
DMAOG库：数据映射相关的Scala库

数据源

GitHub API：仓库基本信息、发布记录、议题跟踪等
Maven Central：POM文件中的项目元数据和依赖信息
Zenodo：DOI、资助信息、作者详细信息等

验证方法

SHACL验证：使用W3C推荐标准进行结构验证
ShEx验证：使用Shape Expressions进行模式验证
CodeMeta Generator：使用官方验证工具进行最终确认

自动化工具链

GitHub Actions：CI/CD流水线
Groovy脚本：JSON-LD框架化处理
Bash脚本：工作流程编排

实验结果

主要成果

1. 映射覆盖度

平台	支持属性数	CodeMeta类覆盖
GitHub	12个核心属性	SoftwareSourceCode, Person
Maven	8个核心属性	SoftwareSourceCode, 依赖关系
Zenodo	15个核心属性	SoftwareSourceCode, Person, Organization