informatievlaanderen/oslo-ea-to-rdf

Enterprise Architect RDF转换工具

镜像概述和主要用途

本工具是弗拉芒***Open Standaarden voor Linkende Organisaties (OSLO²) 倡议的一部分（OSLO产品页面）。OSLO²项目旨在为（地方）***间的数据交换建立坚实标准，这些数据交换格式以RDF词汇表（或本体）的形式创建，遵循关联数据（Linked Data）运动的原则。

该工具提供了一种自动方式，从符合特定格式的Enterprise Architect（常用UML建模工具）项目中创建本体。它主要用于生成发布在[***]

核心功能和特性

• UML到RDF自动转换：将Enterprise Architect中的UML图（包、类、数据类型、枚举、属性、连接器等）转换为RDF本体（Turtle格式）
• 配置定制：通过JSON配置文件自定义标签映射、前缀、本体元数据等
• 多场景支持：处理内部定义术语、外部引用术语及非活动术语的不同转换逻辑
• 错误检查：转换过程中输出ERROR/WARNING日志，确保生成本体的质量
• TSV导出：支持将UML图转换为包含层级、数据类型等信息的制表符分隔值（TSV）文件
• 源码格式化：集成Google Java Format工具统一源码风格

使用场景和适用范围

• 数据交换标准生成：为部门间的数据交换创建RDF本体规范
• UML模型测试：本地验证UML图转换为RDF的正确性
• 关联数据项目：复用工具将现有UML模型转换为符合关联数据原则的本体
• 多本体协作：处理跨包/跨本体的元素引用和属性定义

使用方法和配置说明

环境要求

• 构建需安装Maven和Java (JDK)
• Docker环境（用于Docker化构建）

构建与运行

常规构建

bash
mvn clean package
cd target
java -jar <jar文件> --help

Docker化构建

项目构建过程分为两个阶段实现Docker化，支持离线构建：

1. 构建基础镜像：下载所有依赖
2. 使用exec目标：创建离线构建，加速开发过程
3. 使用format目标：格式化源码

命令示例

转换UML图为RDF本体（Turtle格式）

bash
# 转换EA项目中的指定图为RDF本体，生成Turtle格式文件
# 注意：使用生成的本体前应处理所有ERROR和WARNING日志
java -jar <jar文件> convert --diagram <图名称> --config <配置文件> --input <EA项目文件> --output <Turtle输出文件>

转换UML图为TSV文件

bash
# 转换EA项目中的指定图为包含层级、数据类型等信息的TSV文件
java -jar <jar文件> tsv --diagram <图名称> --config <配置文件> --input <EA项目文件> --output <TSV输出文件>

转换约定

由于UML与RDF之间存在差异，需遵循特定约束并指定元数据（以EA项目中元素的标签形式）。配置文件决定这些标签如何转换为RDF。标签值限制为256字符，超过时可使用值NOTE指示使用标签备注作为值。

包（Package）

映射为owl:Ontology，包中定义的每个元素均属于该本体。标签：

• baseURI：包中每个元素的基础URI（例：http://example.org/ns#）
• （可选）baseURIabbrev：baseURI的首选缩写形式，用于生成命名空间前缀（例：ex）
• （可选）ignore：布尔值，设为true时忽略该包及其中所有内容
• （可选）ontologyURI：对应owl:Ontology的URI，默认是baseURI去掉最后一个字符（例：http://example.org/ns）

类、数据类型与枚举（Class, DataType & Enumeration）

映射为owl:Class，枚举通过owl:oneOf限制为指定值。标签：

• （可选）ignore：布尔值，设为true时忽略该元素及其属性和连接器
• （可选）literal：布尔值，指示元素是否表示文字类型，影响引用该元素的属性类型（默认false）
• （可选）name：用于补全元素URI的字符串，未指定时使用类/数据类型名称（例：类名为Dog，name设为Canine，URI为http://example.org/ns#Canine）
• （可选）package：定义外部类翻译的包名，默认使用元素所在包
• （可选）uri：外部定义类的URI，优先于baseURI/name组合（例：http://example.org/ns/special#Canine）

属性（Attribute）

映射为rdf:Property、owl:DatatypeProperty或owl:ObjectProperty。标签：

• （可选）domain：属性域的URI，覆盖自动推导结果
• （可选）ignore：布尔值，设为true时忽略该属性
• （可选）literal：与range标签配合使用，指示范围是否为文字（默认false）
• （可选）name：用于补全元素URI的字符串，未指定时使用属性名称（例：canine-name）
• （可选）package：定义该属性的包名，默认使用属性所在类/数据类型/枚举的包
• （可选）parentURI：该属性作为子属性的父属性完整URI（例：https://www.w3.org/2000/01/rdf-schema#label）
• （可选）range：属性范围的URI，覆盖自动推导结果，使用此标签将生成owl:ObjectProperty
• （可选）uri：属性的完整URI，优先于baseURI/name组合（例：http://example.org/ns/special#canine-name）

属性数据类型映射规则（优先匹配）：

• 若数据类型为Boolean、Date、DateTime等支持的XSD/RDF/RDFS基本类型，直接映射
• 否则映射为名称匹配的数据类型或类

连接器（Connector）

• 泛化连接器：转换为rdfs:subClassOf三元组
• 关联或聚合连接器：转换为owl:ObjectProperty，属性方向遵循连接器标签方向或连接器本身方向

标签：

• package：定义该属性的包名（未指定uri时必需），默认基于连接元素推测
• （可选）domain：属性域的URI，覆盖自动推导结果
• （可选）ignore：布尔值，设为true时忽略该属性
• （可选）name：用于补全元素URI的字符串，未指定时使用属性名称（例：petPicture）
• （可选）parentURI：该属性作为子属性的父属性完整URI（例：http://xmlns.com/foaf/spec/#term_depiction）
• （可选）range：属性范围的URI，覆盖自动推导结果
• （可选）uri：属性的完整URI，优先于baseURI/name组合（例：http://example.org/ns/special#petPicture）

指定包（Specifying Packages）

转换多词汇表交互模型时，需区分三种术语类型：

• 内部活动术语：由当前导出图定义，输出所有信息（使用配置中的internalMapping）
• 外部术语：外部定义并复用，可添加翻译等附加信息（使用配置中的externalMapping）
• 非活动术语：在其他图中定义，不输出任何信息

类、数据类型与枚举的术语类型判定

• 内部活动术语：无uri标签，且元素定义于或package标签设为导出包
• 外部术语：有uri标签，且元素定义于或package标签设为导出包
• 非活动术语：元素未定义于导出包

属性与连接器的术语类型判定

• 内部活动术语：无uri标签，且package标签（或默认值）指向导出包
• 外部术语：有uri标签，且package标签（或默认值）指向导出包

关联类（Association Classes）

注意：关联类是UML特有概念，难以准确反映RDF结构，不建议使用。

UML中，连接器可通过关联类跟踪两个类之间关联的信息。在RDF中，这通过将关联类置于连接属性中间实现，考虑反向属性后会形成4个独立属性。

带关联类的连接器需为所有标签添加前缀：source-、source-rev-、target-和target-rev-（例：source-label-en对应源元素到关联类的属性）。若不需要转换所有属性，可使用忽略标签（例：source-rev-ignore设为true）。

配置

配置文件为JSON格式，影响UML图的转换方式，主要包括前缀、标签到属性的映射（本体级、内部术语、外部术语）及内置标签覆盖。

前缀（Prefixes）

json
{
  "prefixes": {
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "owl": "http://www.w3.org/2002/07/owl#"
  }
  ...
}

映射（Mappings）

包含三个映射块：

• ontologyMappings：处理包级标签，映射为owl:Ontology实例的属性
• internalMappings：处理导出包中定义并显示在图中的类、属性等
• externalMappings：处理未在导出包中定义但显示在图中的类

每个映射包含：

• tag：EA中使用的标签名
• property：映射目标RDF属性（URI）
• mandatory：布尔值，指示无值时是否警告
• type：RDF值的数据类型URI，默认http://www.w3.org/1999/02/22-rdf-syntax-ns#langString，使用http://www.w3.org/2000/01/rdf-schema#Resource可转为链接
• lang：rdf:langString值的语言
• fallbackTags：tag无值时依次尝试的标签列表

示例：

json
{
  "ontologyMappings": [
    {
      "tag": "issued",
      "property": "http://purl.org/dc/terms/issued",
      "mandatory": true,
      "type": "http://www.w3.org/2001/XMLSchema#date"
    }
  ],
  "internalMappings": [
    {
      "tag": "label-nl",
      "property": "http://www.w3.org/2000/01/rdf-schema#label",
      "mandatory": true,
      "lang": "nl"
    },
    {
      "tag": "pref-label-nl",
      "property": "http://www.w3.org/2004/02/skos/core#prefLabel",
      "fallbackTags": ["label-nl"],
      "mandatory": true,
      "lang": "nl"
    }
  ],
  "externalMappings": []
  ...
}

内置标签（Builtin Tags）

可通过配置自定义所有内置标签，默认值如下：

json
{
  "builtinTags": {
    "LOCALNAME": "name",
    "EXTERNAL_URI": "uri",
    "IGNORE": "ignore",
    "DEFINING_PACKAGE": "package",
    "SUBPROPERTY_OF": "parentURI",
    "DOMAIN": "domain",
    "RANGE": "range",
    "IS_LITERAL": "literal",
    "PACKAGE_BASE_URI": "baseURI",
    "PACKAGE_BASE_URI_ABBREVIATION": "baseURIabbrev",
    "PACKAGE_ONTOLOGY_URI": "ontologyURI"
  }
}

示例配置

json
{
  "prefixes": {
    "rdf": "[***]",
    "rdfs": "[***]",
    "owl": "[***]"
  },
  "ontologyMappings": [
    {
      "tag": "title-nl",
      "property": "[***]",
      "mandatory": true,
      "lang": "nl"
    },
    {
      "tag": "issued",
      "property": "[***]",
      "mandatory": true,
      "type": "[***]"
    }
  ],
  "internalMappings": [
    {
      "tag": "label-nl",
      "property": "[***]",
      "mandatory": true,
      "lang": "nl"
    },
    {
      "tag": "pref-label-nl",
      "property": "[***]",
      "fallbackTags": ["label-nl"],
      "mandatory": true,
      "lang": "nl"
    },
    {
      "tag": "definition-nl",
      "property": "[***]",
      "mandatory": true,
      "lang": "nl"
    }
  ],
  "externalMappings": [
    {
      "tag": "label-nl",
      "property": "[***]",
      "lang": "nl"
    }
  ]
}