informatievlaanderen/oslo-specification-generator

规范生成器（Specification Generator）中文技术文档

1. 镜像概述和主要用途

规范生成器（Specification Generator）是一套基于OSLO工具EA-to-RDF输出结果的工具集，用于生成多种技术产物。其核心功能是将EA-to-RDF生成的RDF词汇转换为可直接使用的结构化文档、验证规则及语义描述文件，支持语义网应用开发、静态规范文档生成及数据模型验证等场景。

2. 核心功能和特性

2.1 主要工具集

该工具集包含以下核心工具及相关工具：

核心工具

• json-ld-generator.js：生成完整的JSON-LD上下文文件。
• exampletemplate-generator.js：为规范中的每个类生成JSON-LD上下文及默认负载结构。
• html-generator.js：生成可由静态网页服务器渲染的HTML页面（主要目标为Data.vlaanderen.be），默认模板位于/views目录。
• shacl-generator.js：生成SHACL验证模板。

相关工具

• csv-renderer.js：根据exampletemplate-generator生成的模板渲染CSV文件内容。
• pretty-print.js：对EA-to-RDF输出结果进行排序和格式化，提高生成产物的稳定性。
• translation-json-generator.js：创建语言感知值的翻译文件，包含供译者使用的关键信息及EA-Guid。
• generate-translation-report.js：生成翻译JSON文件的报告，检查空字符串或占位符以验证翻译完整性。
• jsonld-merger.js：将翻译JSON合并回原始JSON-LD，覆盖配置中针对特定语言优化的值（如标题、模板）。
• linkeddataparser4.js：扩展HTML生成器以支持外部链接引用，需配合特定模板（如ap2ext_en.j2）使用。
• mu-config-generator.js：基于规范的JSON-LD自动生成mu-semtech项目配置。

2.2 技术特性

• 跨语言模板兼容：使用nunchucks.js模板引擎，保持与Python版本（Jinja2）的外部模板接口一致。
• Docker化部署：支持通过Docker容器构建和运行，简化环境依赖管理。
• 命令行交互：所有工具通过命令行调用，提供--help参数获取使用说明。
• 代码风格检查：集成eslint进行JavaScript代码风格验证。

3. 使用场景和适用范围

• 语义网词汇开发：生成JSON-LD上下文文件，支持RDF词汇的语义描述。
• 静态规范文档：通过html-generator.js生成可部署的静态HTML规范页面（如Data.vlaanderen.be）。
• 数据验证规则：使用shacl-generator.js生成SHACL模板，用于RDF数据的结构验证。
• 多语言支持：通过translation-json-generator.js和jsonld-merger.js实现规范文档的多语言翻译与整合。
• mu-semtech项目集成：使用mu-config-generator.js快速生成符合mu-semtech架构的资源配置。

4. 构建与安装

4.1 环境要求

• Node.js ≥ 10.x
• npm ≥ 6.x（用于本地构建）
• Docker（用于容器化构建）

4.2 本地构建（npm）

bash
# 设置npm安全权限
npm set unsafe-perm true
# 安装依赖
npm install

4.3 Docker构建

推荐使用项目中的Dockerfile.circleci构建Docker镜像：

bash
docker build -f Dockerfile.circleci -t specification-generator:latest .

5. 使用方法

5.1 工具运行通用命令

所有工具通过Node.js命令行调用，基本格式：

bash
node <tool>.js --help

执行上述命令可获取工具的详细参数说明。

5.2 核心工具使用示例

5.2.1 HTML生成器（html-generator.js）

生成静态HTML规范页面：

bash
# 查看帮助
node html-generator.js --help
# 示例：从RDF输入生成HTML（具体参数需根据--help提示补充）
node html-generator.js --input ./ea-to-rdf-output.ttl --output ./html-docs --template ./views/default.j2

5.2.2 SHACL生成器（shacl-generator.js）

生成SHACL验证模板：

bash
node shacl-generator.js --input ./vocabulary.jsonld --output ./shacl-templates

5.3 模板引擎差异（Python vs JavaScript）

本工具集使用nunchucks.js作为模板引擎，与Python版本（Jinja2）存在以下差异，需在模板中调整：

5.3.1 变量过滤前需检查存在性

对可能不存在的变量使用过滤器（如selectattr、lower）时，需先检查变量是否存在，否则模板会崩溃：

nunjucks
{% if object.property %}
  {{ object.property | lower }}
{% endif %}

5.3.2 字符串小写转换语法

Python版本中{{ "TEST".lower() }}在JS版本中需改为过滤器形式：

nunjucks
{{ "TEST" | lower }}

5.3.3 selectattr过滤器复杂用法不支持

Jinja2的复杂selectattr（如selectattr('property', 'equalto', 1)）不支持，需通过groupby替代：

nunjucks
{% for property, objects in objects | groupby('property') %}
  {% if property == 1 %}
    # 处理过滤后的objects
  {% endif %}
{% endfor %}

5.3.4 自动转义机制

默认启用HTML自动转义，特殊字符（如<、>）会被转义。若需禁用，可使用safe过滤器（确保内容安全）：

nunjucks
{{ entity.usage[language] | safe }}

5.4 mu-config-generator.js使用指南

5.4.1 前置准备

1. 克隆mu-project基础仓库：

bash
git clone https://github.com/mu-semtech/mu-project/

2. 在docker-compose.yml中添加资源服务配置：

yaml
resource:
  image: semtech/mu-cl-resources:1.18.0
  links:
    - db:database
  volumes:
    - ./config/resources:/config
  ports:
    - "8888:80"  # 暴露8888端口供访问

5.4.2 生成配置

运行工具生成mu-semtech配置文件，指定JSON-LD输入、语言及输出目录（需对应mu-project的./config/resources）：

bash
node mu-config-generator.js --input ./specification.jsonld --language en --output ./mu-project/config/resources

5.4.3 应用配置

重启Docker Compose使配置生效：

bash
cd mu-project
docker-compose down && docker-compose up -d

5.4.4 示例：创建资源

通过HTTP POST请求创建Address资源（Content-Type: application/vnd.api+json）：

json
{
  "data": {
    "type": "Addresses",
    "attributes": {
      "name": "An Address",
      "definition": "A Description",
      "usage": "A Usage"
    },
    "relationships": {
      "Location": {
        "data": {
          "type": "Locations",
          "id": "5FCFCE2A873EE90008000001"
        }
      }
    }
  }
}

请求地址：http://localhost:8888/Addresses

6. 代码风格与质量

项目通过eslint实施JavaScript代码风格检查，配置集成在测试脚本中：

bash
# 运行代码风格检查
npm test

7. Docker部署方案

7.1 构建镜像

bash
docker build -f Dockerfile.circleci -t specification-generator:latest .

7.2 运行工具容器

以html-generator.js为例，挂载本地目录并执行：

bash
docker run -v $(pwd):/app specification-generator:latest node html-generator.js --input /app/input.ttl --output /app/output

7.3 集成mu-semtech项目

在mu-project的docker-compose.yml中添加规范生成器服务：

yaml
spec-generator:
  image: specification-generator:latest
  volumes:
    - ./spec-input:/input
    - ./spec-output:/output
  command: node mu-config-generator.js --input /input/vocab.jsonld --output /output/config

8. 注意事项

• 模板兼容性：迁移Python版本模板时，需按照5.3节调整过滤器使用方式。
• 外部链接支持：使用linkeddataparser4.js时，需确保JSON-LD中类和属性包含"externallink"语言标签属性。
• 翻译整合：jsonld-merger.js会覆盖原始JSON-LD中已翻译的值，建议备份原始文件。
• 依赖管理：Docker构建可避免本地Node.js环境差异，推荐生产环境使用容器化部署。