---
title: SuccApp Super JSON
description: 说明 SuccApp Super JSON 的定义、适用文件、共同规范、修改原则和校验方式
navTitle: Super JSON
---
# SuccApp Super JSON

SuccApp Super JSON 是 SuccApp 多种元数据 JSON 文件共同遵守的文件格式规范。它不是某一个文件后缀，而是一套基于JSON的文件格式规范。

本文只说明 Super JSON 总体概念、适用范围和修改原则，真实文件格式细节见DTS定义 [`types/meta/superjson/base.d.ts`](../../../../dev-types/types/meta/superjson/base.d.ts) 中的 `SuperJSON`。

## 适用文件{#file-types}

SuccApp Super JSON 主要适用于这些元数据文件：

| 类型 | 文件 | 用途和细节入口 |
| --- | ------- | ----------------------- |
| 数据类 | `.tbl`、`.query` | 数据模型和查询 DSL。查看 [.tbl](../file-types/data/tbl.md)、[.query](../file-types/data/query.md)、[`types/meta/file-types/tbl.d.ts`](../../../../dev-types/types/meta/file-types/tbl.d.ts)、[`types/meta/file-types/query.d.ts`](../../../../dev-types/types/meta/file-types/query.d.ts)。 |
| 页面类 | `.spg`、`.dash`、`.rpt`、`.fapp`、`.tpg` | SuperPage、仪表板、报表、报表填报应用、超级模板页面。查看 [.spg](../file-types/views/spg.md)、[.dash](../file-types/ana/dash.md)、[.rpt](../file-types/ana/rpt.md)、[.fapp](../file-types/views/fapp.md)、[.tpg](../file-types/views/tpg.md)、[`types/meta/visual-page/visualpage.d.ts`](../../../../dev-types/types/meta/visual-page/visualpage.d.ts)、[`types/meta/file-types/tpg.d.ts`](../../../../dev-types/types/meta/file-types/tpg.d.ts)。 |
| 流程类 | `.afl`、`.wfl` | 程序流和工作流。查看 [.afl](../file-types/backend/afl.md)、[.wfl](../file-types/backend/wfl.md)、[`types/meta/file-types/afl.d.ts`](../../../../dev-types/types/meta/file-types/afl.d.ts)、[`types/meta/file-types/wfl.d.ts`](../../../../dev-types/types/meta/file-types/wfl.d.ts)。 |

其他 JSON 元数据文件例如项目配置、主题和模板配置不属于 SuccApp Super JSON。遇到这些文件时，应回到对应[文件类型页](../file-types/README.md)和 DTS 判断，不要强行套用本页示意结构。

## 共同规范{#structure}

下面是 SuccApp Super JSON 的顶层段落地图。它不是可直接复制的新文件模板；真实文件只保留自己文件类型支持的段落。同名字段在不同文件类型中的位置可能不同，编辑时保持原文件和同类最新版文件的顺序，字段细节以 DTS 为准。

```jsonc
{
  "version": "5.8.2",                  // 大多数 Super JSON 文件的结构版本；修改旧文件前先确认是否已升级到当前版本。
  "settings": {                        // 文件级设置；不同类型的 settings 由各自 DTS 定义。
    "..."
  },
  "params": [                          // 对外输入参数或内部中转参数。
    {
      "id": "deptId",                  // 参数内部 ID，通常自动生成并保持稳定。
      "name": "deptId",                // 参数业务名称，可通过 $params.deptId 引用。
      "dt": "C",                       // 参数数据类型，字段取值见 Param DTS。
      "disablePassIn": false           // 是否禁止外部传入。
    }
  ],
  "sources": [                         // 页面类、.tpg、.tbl 取数模型、.query 和 .wfl 都可能有数据来源。
    {
      "id": "sales",                   // 数据集或来源的稳定 ID。
      "name": "销售明细",               // 数据集显示名或别名。
      "modelType": "dwtable",          // 数据集类型，按 dataset DTS 继续定位分支结构。
      "refType": "query",              // 使用该模型的引用类型。
      "path": "salesModel",            // 外部模型资源代号，真实路径在 referenceResources.salesModel。
      "content": "dataflow1"           // 内嵌数据集资源代号，完整内容在 innerResources.dataflow1；和 path 按类型二选一。
    }
  ],
  "..."                                // 仅 .wfl：流程连线，连接 nodes 中的节点并记录分支条件。
  "referenceResources": {              // 外部资源引用索引；业务字段里通常只写 salesModel、logo 等代号。
    "salesModel": {
      "targetPath": "$DATA:/销售明细.tbl", // 真实目标路径，路径格式见 referenceResources DTS。
      "targetType": "METAFILE",        // 目标资源类型。
      "refType": "query",              // 引用类型。
      "srcProperty": "sources"         // 可选：记录引用来自哪个属性，便于分析和重构。
    }
  },
  "innerResources": {                  // 内嵌资源；使用方记录代号，完整资源内容集中放在这里。
  }
}
```

需要修改具体段落时，进入对应文件类型页和 DTS，例如 [`types/meta/file-types/tbl.d.ts`](../../../../dev-types/types/meta/file-types/tbl.d.ts)、[`types/meta/file-types/query.d.ts`](../../../../dev-types/types/meta/file-types/query.d.ts)、[`types/meta/visual-page/visualpage.d.ts`](../../../../dev-types/types/meta/visual-page/visualpage.d.ts)、[`types/meta/superjson/referenceResources.d.ts`](../../../../dev-types/types/meta/superjson/referenceResources.d.ts)、[`types/meta/file-types/afl.d.ts`](../../../../dev-types/types/meta/file-types/afl.d.ts) 和 [`types/meta/file-types/wfl.d.ts`](../../../../dev-types/types/meta/file-types/wfl.d.ts)。外部资源引用方式、路径前缀、`targetType` 和 `refType` 见[资源引用与路径](./reference-paths.md)；内嵌完整资源内容的写法见[内嵌资源](./inner-resources.md)。

## 修改原则{#edit-notes}

直接修改 SuccApp Super JSON 文件前，先确认文件类型、`version`、文件类型页、相关 DTS、当前文件内容和同项目同类文件。

修改时遵守这些原则：

1. 先判断文件后缀和业务类型，再进入对应文件类型页和 DTS。
2. 修改前先确认 `version`。除非非常确定要改什么，并且只是很小范围的兼容修复，否则应先确保文件已经升级到当前最新版；如果不是最新版，应先通过SuccApp CLI工具或浏览器端的可视化设计升级，再按当前 DTS 修改。
3. 不要基于最新 DTS 直接大改老版本 JSON，这容易把历史结构改坏。
4. 字段细节以 DTS 为准，不靠本页示意结构猜字段。
5. 不随意改稳定标识，例如组件 `id`、数据集 `id/name`、字段 `fld`、动作节点 `id/name`、资源代号和 `.meta` 中的资源 ID。
6. 改资源目标、移动文件、重命名文件或删除文件时，同步检查 `referenceResources`、业务字段中的引用代号和 `.meta`。
7. Git diff 只保留任务相关修改，不混入全文件格式化、字段排序或无关默认值。

### 老版本文件{#legacy-files}

老版本文件应先通过SuccApp CLI工具或浏览器端的可视化设计升级再修改。只有在改动范围非常小、目标字段含义非常确定、且不需要按最新结构重写文件时，才按兼容维护方式直接改旧结构。

不确定历史字段含义时，先查同版本同类文件、DTS 和产品实现，再决定是否修改。

### 检查清单{#checklist}

修改完成后至少检查：

1. 文件仍是可解析的 JSON 或当前文件类型允许的结构化文本。
2. 文件类型、根结构和 DTS 入口匹配。
3. 受影响的 `id`、`fld`、数据集名、资源代号和路径能被搜索和追踪。
4. `referenceResources` 没有明显悬挂条目，业务字段里的引用代号也能找到目标。
5. 对应设计器、预览页、报表、流程或系统功能可以打开验证。

## 文件格式校验{#validation}

::: warning TODO
这里后续补充 SuccApp Super JSON 的正式校验方法，包括可执行命令、校验范围、错误解释和修复建议。
:::

正式校验方法补齐前，优先使用编辑器的 DTS 类型提示、JSON 解析检查、引用搜索和产品设计器打开验证。