Table Schema 表架构

简介

Table Schema 是由 Frictionless Data（一个致力于数据互操作性的开源项目）制定的一种规范，用于通过 JSON 对象标准化描述表格数据集的元数据（结构、类型、约束等）。它的核心目标是让机器和人都能清晰理解表格数据的 “结构规则”，从而实现数据的跨系统交换、验证、集成和解析。

核心作用

Table Schema 的本质是用 JSON 格式定义表格数据的 “说明书”，包含：

• 表格的基本信息（名称、描述等）；
• 字段的结构（名称、类型、格式）；
• 数据的约束规则（是否必填、是否唯一、范围限制等）；
• 表间关系（主键、外键）。

通过这份 “说明书”，不同工具、系统或团队可以统一理解数据结构，避免因 “字段含义模糊”“类型不匹配” 等问题导致的数据混乱。

基本结构JSON格式

$schema
引用 Table Schema 规范的版本（如最新版 https://frictionlessdata.io/schemas/table-schema.json）

name

表格的机器可读名称

title
表格的人类可读标题
description
表格的详细描述

fields
字段定义数组（核心！描述每个列的结构）
primaryKey
主键（单个字段名或多个字段名的数组，如 id 或 [“name”, “age”]）
foreignKeys
外键数组（定义与其他表格的关联）

misssingValues
全局缺失值标识（如 [“”, “NA”, “null”]），字段级可覆盖

fields

fields 是一个数组，每个元素是描述一列的 JSON 对象，包含以下常用属性：

• name
• title
• description
• type
• format
• constraints
• missingValues
• example

type

Table Schema 定义了一套跨系统通用的类型（非特定数据库类型），常见类型如下：

• string
• integer
• number
• boolean
• date
• time
• datetime
• geopoint
• object
• array

constraints

constraints 是字段的验证规则，确保数据符合业务逻辑，常见约束如下：

• `required
• unique
• minimum
• maximum
• pattern
• enum

primaryKey 与 foreignKeys：表间关系

• primaryKey：定义表格的唯一标识，例如：
  “primaryKey”: “user_id”（单个字段）或 “primaryKey”: [“name”, “email”]（联合主键）。

• foreignKeys：定义与其他表格的关联，每个外键是一个对象，包含：

  • fields：当前表格的字段（如 [“role_id”]）；
  • reference：引用的表格和字段（如 {“resource”: “roles”, “fields”: “id”}，表示关联 roles 表的 id 字段）。

"foreignKeys": [
  {
    "fields": ["role_id"],
    "reference": {
      "resource": "roles",
      "fields": "id"
    }
  }
]

应用场景

1. 数据验证：工具（如 frictionless-py）可根据 Schema 检查数据是否符合类型、约束（例如：birth_date 是否为合法日期，user_id 是否重复）。
2. 数据交换：跨系统传输表格数据时，附带 Schema 可确保接收方正确解析（如 API 接口返回数据时，用 Schema 说明字段含义）。
3. 数据目录：在数据平台中展示数据集结构，帮助用户快速理解数据（如数据中台的元数据管理）。
4. 数据转换：ETL 过程中，依据 Schema 自动转换数据格式（如将字符串 20231001 转为 date 类型的 2023-10-01）。

工具支持

• Frictionless Data：提供官方库（如 Python 的 frictionless、JavaScript 的 @frictionlessdata/tableschema），支持解析、验证、生成 Schema。
• 数据工具集成：Excel、Google Sheets、Pandas 等可通过插件支持 Table Schema（如 pandas 可根据 Schema 校验 DataFrame）。

示例

{
  "$schema": "https://frictionlessdata.io/schemas/table-schema.json",
  "name": "user_table",
  "title": "用户信息表",
  "description": "存储平台用户的基本信息",
  "missingValues": ["", "NA"],
  "fields": [
    {
      "name": "user_id",
      "title": "用户ID",
      "type": "integer",
      "description": "用户唯一标识",
      "constraints": { "required": true, "unique": true }
    },
    {
      "name": "name",
      "title": "姓名",
      "type": "string",
      "constraints": { "required": true, "pattern": "^[a-zA-Z\\u4e00-\\u9fa5]+$" }
    },
    {
      "name": "birth_date",
      "title": "出生日期",
      "type": "date",
      "format": "%Y-%m-%d",
      "constraints": { "maximum": "2010-01-01" }
    },
    {
      "name": "role_id",
      "title": "角色ID",
      "type": "integer",
      "description": "关联角色表的ID"
    }
  ],
  "primaryKey": "user_id",
  "foreignKeys": [
    {
      "fields": ["role_id"],
      "reference": {
        "resource": "roles",
        "fields": "id"
      }
    }
  ]
}