Markdown 表格转 CSV 与 JSON Schema 实战指南:四个解析陷阱如何决定你的 Schema

封面图:Markdown 表格会安静地丢数据。管道表格与干净导出之间隔着四个解析陷阱。

Markdown 管道表格不是数据结构。它只是一条渲染指令,供人用眼睛读。你一旦想把它拆成数据行,就会看清这套格式默默纵容了多少东西:单元格宽度和表头对不上;单元格是空的,本意却是零;单元格里带着一个真正的管道符,被朴素的拆分器从中间撕开。Markdown 表格到 CSV、JSON 与类型推断 Schema 这个工具之所以存在,正是因为「表格看起来怎样」和「表格作为数据怎样」之间的这道缝隙,就是数据悄悄丢掉的地方。所以本文讲清三件事:转换器实际推断了什么、它拒绝猜什么,以及结果进入 Schema 之前该怎么核对。

为什么 Markdown 表格比看上去更难解析

它的语法故意留得很松。标记表头与正文分界的定界行,实际使用中可有可无;---: 和 :---: 这类对齐标记不携带任何数据;单元格里的管道符可以写成转义的 |,它是字面字符,不是列分隔符。按 | 拆一行,你会得到与表头数目对不上的单元格、被切成两段的转义管道符,以及闭合分隔符带来的一个尾部空串。

拿 | a | b | c | 这一行做朴素拆分,你得到的是四个字段而不是三个,因为两端的管道符各产生一个空串。就这一个副产物,把所有列索引整体推后一位,正确的转换就此变成悄悄出错的那一种。对齐标记还会叠上一层:| --- | ---: | :---: | --- | 根本不是数据行,可把它当数据处理的拆分器,会从一行没有任何值的文本里推断出四个 string 列。

实际的后果是:一张表在 README 里渲染得完美无缺,作为数据仍然结构含混。对齐方式、可否为空、列类型,全靠约定暗示,没有任何地方声明。任何转换器都只能去推断,而每一处推断都是猜错就导出错的所在。

类型推断究竟决定了什么

类型推断是最容易让人意外的环节,因为答案取决于这一列里每个值是否一致。工具逐列独立判断,只有当所有非空单元格都符合同一种形态时才提升类型。它能分辨 integer、number、boolean、date、date-time 和 string,遇到冲突按固定顺序裁决,不搞多数票。

高亮卡片 1:四种列类型下,类型推断各自决定了什么

走一遍标准的库存示例,规则就落到实处。表头是 | sku | quantity | active | shipped |,数据行是 A-1 | 12 | true | 2026-08-05 和 A-2 | 0 | false | 2026-08-06,推断结果是:sku 为 string,quantity 为 integer,active 为 boolean,shipped 为 date。数量列之所以成立,是因为两个值都是不带小数点的纯数字,而 0 算整数,不算假值空值。日期列则符合严格的 YYYY-MM-DD 形态。

这张表导出后是一行表头加两行数据,表头为 sku,quantity,active,shipped。你可以在 Markdown 表格到 CSV、JSON 与类型推断 Schema 上完整复现一遍,去检查推断出的元数据,而不是只信 CSV 文本。

integer 与 number 之间的陷阱

最常见的一惊发生在 integer 和 number 的边界上,而它偏向的方向很少有人预料到。一列里有 12 和 0,是 integer。一列里有 12 和 9.5,是 number。还是这列 12 和 9.5,它不会因为多数行看起来像整数就被提升回整数:列里只要出现一个小数值,就说明这一列真的装着带小数的量,integer 的 schema 会拒掉合法数据。

反过来的陷阱更糟。一列里有 12 和 abc,它不是「有一个坏行的数值列」,而是一个 string 列,正确的修法在源表格上游,不在导出下游。如果导出器把那个 abc 悄悄强转成零,你就凭空造出了一个从来不存在的数据点。

还有一类值看着像数字,其实不是。标识符的前导零、结尾的百分号、货币符号、千分位分隔符、被引号包起来的值,都会破坏纯数字形态。邮政编码、电话号码、产品 SKU 和账号全都属于 string 列,把它们推断成整数,是永久丢掉前导零最快的一条路。如果某一列不论内容如何都必须保持文本,就直接声明它,别指望样本数据是干净的。

空值标记、空单元格与必填集合

空单元格和写着字面 null 的单元格,在 Markdown 里是两回事,混为一谈会悄悄改变 schema 的形状。工具接受一份显式的空值标记清单,null、NULL 和 ~ 都被当作缺失处理;真正空着的单元格也走同一条缺失规则。清单之外的一切都保持 string,所以写着 none 的单元格是数据,不是空缺。

高亮卡片 2:转换器报出来而不去猜的四个单元格级陷阱

JSON Schema 输出里的必填集合就由这个区别决定,标准示例把它演示得很准。表头 | name | score | active |,数据行 Ada | 9.5 | true 和 Lin | null | false:可空列是 score,非空列是 name 和 active。只有 score 被移出必填清单,生成的 schema 因此要求那两个真正始终存在的列,而允许 score 缺失或为 null。

结果是一份 schema,其中 score 属性类型为 number 且接受 null,写成 number 与 null 的联合。必填模式取非空列时,输出会带上标准的 $schema 声明和一项 additionalProperties 设置,让意料之外的键被有意处理,而不是被忽略。要提防的失败模式,是因为某列在你那两行样本里恰好非空就把它标成必填:小表里没见到反例,不构成存在约束的证据。

对齐、不齐行,以及不静默丢弃的原则

区分一个转换器是可信还是只是顺手,看它遇到与表头宽度不符的行怎么做。原则是任何单元格都不会被静默丢弃。数据行的单元格太少或太多时,转换器把不匹配作为诊断报出来,保留实际存在的内容,而不是为了凑齐形状去补空或截断。

设想表头声明三列,后面一行只有两个单元格,再下一行有四个。宽松的解析器给短行补空串、把长行截断,你最后拿到一张表,其中某个值已被悄悄挪进了错误的列。这比直接报错更糟:导出看着干净,数据已经错了。诊断让问题在还来得及修的地方显形。

对齐标记按同一个原则处理。定界行会被识别出来并排除在数据之外,而不是变成一行四个空串单元格;对齐提示记入源表格的元数据,不当成值。某一列意外地变成了 string 时,值得去查一下这份元数据,漏掉定界行是很常见的原因。

转义管道符,以及那个不是分隔符的单元格

最后一个解析陷阱是字面管道符。值里含管道符的单元格用反斜杠转义书写,所以 a | b 是一个装着 a | b 的单元格,不是三个。见着管道符就拆,会得到 a 和 b 两个独立字段,它后面的一切都被悄悄左移一列。

高亮卡片 3:两个完整示例,连同它们的诊断与推断出的 schema

正确的做法是解析器先把转义认出来,再决定这个字符算不算分隔符。转义管道符以字面管道符的形式进入输出,导出的 CSV 或 JSON 因此保留了原值:装着路径、正则的择一分支,或者「街道加门牌单元」这类复合名称的单元格,都能原样往返。

这也是下游引号变得要紧的地方。值里一旦含有输出格式自己的分隔符,导出器就必须给它加引号,CSV 才能重新解析出同样的字段数。原样进来、带引号出去没有问题;被拆散进来则是任何下游步骤都查不出的缺陷。

信任之前先验证导出

四项检查能盖住出问题的大多数情形,成本都很低。第一,把诊断里的行数与源表格的数据行数对照;标准示例对两行数据报出的行数就是二,出现别的数字,就说明解析过程中有行被加进来或丢掉了。

第二,逐列读一遍推断出来的类型,不要凭想当然。你以为是数值的列变成了 string,原因几乎总是一个不合规的值,修法在源表格。第三,列出可空列并与必填清单对照;你认为始终存在却显示为可空的列,指向数据里的某个空值标记,往往是有人敲进去的占位符,不是真实值。

第四,抽一行从头到尾走一遍:确认各单元格在输出里的顺序与源表格一致,转义管道符以字面管道符的形式活了下来。复合值落在一个字段里,就说明解析器处理转义是对的。结构特殊的表格,可以先拿参照材料比一比:CSV samples 里那个普通的分隔数据集,展示了正确解析后的形状,一对比,坏掉的那份就藏不住了。

导出之后往哪里去

三种输出格式回答三个不同的问题,从中挑一个是最后一个值得认真做的决定。CSV 用来回灌电子表格或数据库装载器,那里的类型已经核对过了。JSON 行用来把数据搬进代码,推断出的类型在那里以真正的 JSON 类型存活,而不是到了对面还得重新解析的文本。

真正改变下游工作方式的是 JSON Schema,因为它把你刚刚发现的那些约束编码进去了。由非空列构成的必填清单、类型为 number 与 null 联合的数值列、显式写出的 additionalProperties,让校验器从第一个请求起就有东西可执行,而不是等你处理完一千条畸形记录才动手。从 schema 出发而不是从原始文本出发,是把一个排版便利变成真正的边界检查的关键。当真正的问题是校验而不是转换时,JSON模式校验器 的 JSON Schema 校验器可以拿这个工具生成的 schema 去检查载荷。

不管导出成什么,诊断要留着。行数、每列的推断类型、可空列清单,记录的是转换器当时的判断,也是三周后有人问「这列标识符怎么就变成整数了」时最快的回答。转换表格,读诊断,然后才让输出离开你的手。想要更多源文档来试,Markdown samples 从单个标题到嵌套文档都覆盖了;等到问题不再关于表格,完整目录在 elysiatools.com。

1 Comment

Leave a Reply

Your email address will not be published. Required fields are marked *