YAMLResume vs RenderCV:記錄還是文件?

在找 RenderCV 的替代方案?兩個工具都接受 YAML,但一個把履歷建模成可查詢的 記錄,另一個建模成自由形態的文件。本文說明這個差異在 Postgres 和 MongoDB 裡 讓你付出什麼、又省下什麼。

如果你對比 YAMLResume 和 RenderCV,最顯眼的差異是渲染引擎和視覺可調項的數量。這些 我們已經在逐項對比裡講過了。這篇文章聊的是一個更狹窄、 但對「要建系統而不只是產生一份 PDF」的人來說重要得多的問題:資料的形狀。

兩個工具都接受 YAML,都會驗證,都能產出 PDF。但它們建模的是兩種不同的東西:

  • YAMLResume 把履歷建模成一筆記錄(record)——一列資料,且所有列共享同一套 schema。
  • RenderCV 把履歷建模成一份文件(document)——一棵樹,形狀由作者決定。

這不是無關緊要的措辭差別。它決定了「找出所有碩士學歷的人」究竟是一條 SQL,還是一個 應用層的解析工程。所以下面我們先具體看這兩種模型,再推演它們在履歷建置器、HR 系統或 ERP 裡到底讓你付出什麼代價。

同一份履歷,兩種模型

下面是同一個人的資料,各寫一遍。沒有刻意構造——大致就是 yamlresume new 和 rendercv new 給你的東西。

yamlresume.yml
content:
  basics:
    name: Andy Dufresne
    headline: Backend Engineer
    email: [email protected]
  location:
    city: San Francisco
    region: California
    country: United States
  profiles:
    - network: GitHub
      username: andy
  education:
    - institution: University of Southern California
      degree: Bachelor
      area: Computer Engineering
      startDate: Sep 1, 2016
      endDate: Jul 1, 2020
  work:
    - name: PPResume
      position: Senior Software Engineer
      startDate: Dec 1, 2022
      endDate:
      summary: |
        - Built the LaTeX rendering pipeline
layouts:
  - engine: latex
    template: moderncv-classic
rendercv.yml
cv:
  name: Andy Dufresne
  headline: Backend Engineer
  email: [email protected]
  location: San Francisco, CA
  social_networks:
    - network: GitHub
      username: andy
  sections:
    education:
      - institution: University of Southern California
        degree: BS
        area: Computer Engineering
        start_date: 2016-09
        end_date: 2020-07
    experience:
      - company: PPResume
        position: Senior Software Engineer
        start_date: 2022-12
        end_date: present
        highlights:
          - Built the LaTeX rendering pipeline
design:
  theme: classic

乍看之下兩者像表親。其實不是。有四個結構性決策把它們分開,而每一個都會在儲存層 產生直接後果。

1. section 的 key 是固定的嗎?

YAMLResume 的 section key 是一個封閉集合。 content schema 恰好合併了十四個:basics、location、profiles、education、work、 volunteer、awards、certificates、publications、skills、languages、 interests、references、projects。一份把 certificates 打成 certifcates 的履歷,並沒有「證書」這個 section——你無法表達一個不在清單裡的 section。

RenderCV 的對應物只有一行 Pydantic:

sections: dict[str, Section] | None

key 是 str。沒有任何保留字。使用者可以寫 education、Education、 education_and_training、Academic Background、教育,或者 Things I Did。在產生的 JSON Schema 裡,這個欄位 字面上就是 additionalProperties: { "$ref": "#/$defs/Section" }——也就是說,schema 對 驗證器表達的唯一訊息是「任何 key 都可以」,僅此而已。

2. 欄位名稱在各處意義一致嗎?

這一點容易被忽略,而它在資料庫場景裡傷害最大。RenderCV 並沒有統一的 entry schema; 它有九種 entry 型別(ExperienceEntry、EducationEntry、PublicationEntry、 NormalEntry、OneLineEntry、BulletEntry、NumberedEntry、 ReversedNumberedEntry),外加一個名為 TextEntry 的裸字串。一個 section 的型別是 靠「第一個能匹配上的 entry」推斷出來的,依據是一張「特徵欄位」表——即每種型別獨有的 欄位:

# rendercv/src/rendercv/schema/models/cv/section.py
characteristic_entry_fields = get_characteristic_entry_fields(available_entry_models)

一個含 institution 的 entry 就是 EducationEntry,因為其他型別都不宣告 institution。只有一個 name 的 entry 則是 NormalEntry。接著 validate_section() 要求同一 section 內的所有 entry 必須是同一型別。

結果就是:「組織名」這個欄位叫什麼,取決於使用者隱式選了什麼型別。

概念ExperienceEntryEducationEntryNormalEntry
組織companyinstitutionname
角色 / 主題positionarea—
學位—degree—

注意表裡沒有什麼。日期、location、summary、highlights 在這三種型別裡完全 相同,所以它們也無法幫你區分型別——唯一的訊號就是上面這三列。

所以「這個人在哪工作過」是 cv.sections.*[*].company——如果他用了 ExperienceEntry;而如果他為了表達同樣的資訊用了 NormalEntry,那就是 ...name。 更極端的是,一個 section 可以全是純字串,因為 TextEntry 就是 str——這意味著 entries 在結構上是 list[str] | list[dict],完全沒有形狀保證。

YAMLResume 沒有這種漂移:公司永遠在 work[].name,機構永遠在 education[].institution,skills section 永遠是 {name, level, keywords}。

3. 值是否來自受控詞彙?

YAMLResume 把系統通常需要比較的那些值釘死了:

  • degree ∈ Middle School | High School | Diploma | Associate | Bachelor | Master | Doctor
  • level(技能)∈ Novice | Beginner | Intermediate | Advanced | Expert | Master
  • fluency ∈ 由 ILR 量表(Interagency Language Roundtable,美國跨部門語言圓桌會議)派生的五級,從 Elementary Proficiency 到 Native or Bilingual Proficiency
  • country、language、network——篇幅很長的固定清單,同時也用於翻譯

RenderCV 的 degree 是 str | None。它自己的範例履歷裡用的是 PhD 和 BS。這對排版 來說完全合理——但這也意味著一堆 RenderCV 檔案裡會同時出現 PhD、Ph.D.、 Doctorate、BS、BSc、Bachelor of Science、MS、MSc、M.S.、 Master of Science,而它們只表示兩件事。

有一個細節值得為 YAMLResume 記上一筆:規範值(canonical value)只以英文存一份,渲染 時才本地化。同一個人的中文履歷和英文履歷攜帶的是完全相同的規範值。而在自由字串的 世界裡,值就是作者用自己語言敲進去的那串字元,這讓跨語言的聚合幾乎不可能。

4. 呈現資訊住在哪裡?

在 RenderCV 裡,section 的顯示標題就是 dict 的 key,而顯示順序就是 dict 的插入 順序(get_rendercv_sections() 走訪 sections.items(),並把 snake_case 的 key 轉成 Title Case)。你改了履歷的外觀,也就改了資料。

在 YAMLResume 裡,這兩者都住在 layouts[] 的 sections.aliases 和 sections.order 下面。內容保留規範 key 和規範順序,而每一種輸出格式都可以對它們做不同的呈現。

一個決策,四個症狀

這四個答案不是彼此獨立的。它們是同一種設計立場的四個後果,把這個立場點明,取捨就更好 推理了:

  • YAMLResume 在設計上是 opinionated(有主見的)。 由 schema 來做決定——哪些 section 存在、每個欄位叫什麼、哪些值被允許、呈現和內容的分界線在哪。作者去填一個 自己沒選的形狀。
  • RenderCV 在設計上是 free-form(自由形態的)。 由作者來做決定。schema 只驗證每個 entry 自身是否格式良好,然後就退到一邊。

兩者都合法,而且代價是對稱的:

opinionated 的代價是表達力上限。 如果你的履歷需要 "Patents" 或 "Invited Talks" section,而它不在 YAMLResume 那十四個 key 裡,你就無法原生地表達它。你有十二個可改名 的 section 標題,這對大多數履歷夠用,但對每一份 CV 都不夠。

free-form 的代價是語意下限。 schema 無法承諾文件裡的任何東西可以和別的東西 相比較。兩個作者表達完全相同的事實,產出的文件共享零個 key、零個詞彙、零個結構—— 這在人類讀者之外還有人要消費這些資料之前,都沒問題。

對這篇文章而言,真正重要的是什麼時候付費。opinionated 模型在寫作時收一次費,用 一種很小的貨幣:你說不了某個你想說的東西。free-form 模型在讀取時收費,永遠收,而且 是複利:每一個使用者發明的 section 標題、每一個 Master 的新拼法,都是下游某個解析器裡 多出來的一個分支。一種代價由一個作者付一次;另一種代價由之後每一個接觸這批資料的系統 反覆支付。

這正是為什麼本文接下來關心的是讀取方——資料庫、ATS 流程、HRIS 匯入——而不是 作者。

這在 Postgres 裡要花多少代價

假設一個最直白的 schema——每一個履歷建置器最後都會落到這個:

CREATE TABLE resumes (
  id         uuid PRIMARY KEY,
  content    jsonb NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);

用 YAMLResume 的模型,路徑在資料到來之前就是已知的,所以你可以直接建索引、直接查詢。

-- 所有碩士學位持有者
SELECT id, content -> 'basics' ->> 'name' AS name
FROM resumes
WHERE content -> 'education' @> '[{"degree": "Master"}]';

-- 履歷裡有 Kubernetes 的候選人
SELECT id, content -> 'basics' ->> 'name' AS name
FROM resumes
WHERE content @? '$.skills[*].keywords[*] ? (@ == "Kubernetes")';

-- 按學歷統計人數,無需任何正規化步驟
SELECT e ->> 'degree' AS degree, count(*) AS n
FROM resumes, jsonb_array_elements(content -> 'education') AS e
WHERE e ->> 'degree' IS NOT NULL
GROUP BY e ->> 'degree'
ORDER BY n DESC;

最後那條就是整個論點,幾行寫完。它是一個作用在封閉詞彙上的普通 GROUP BY,輸出 立即正確。

再看 RenderCV 的等價寫法。section 名未知,所以你必須走訪它們;entry 形狀未知,所以 你必須探測一個能識別出「這是教育條目」的欄位:

SELECT r.id, e ->> 'institution' AS institution, e ->> 'degree' AS degree
FROM resumes r
CROSS JOIN LATERAL jsonb_each(
  CASE WHEN jsonb_typeof(r.content -> 'cv' -> 'sections') = 'object'
       THEN r.content -> 'cv' -> 'sections'
       ELSE '{}'::jsonb END
) AS s(title, entries)
CROSS JOIN LATERAL jsonb_array_elements(s.entries) AS e
WHERE s.title ~* '(education|academic|study)'
  AND jsonb_typeof(e) = 'object'
  AND e ? 'institution';

這個 CASE WHEN 不是多餘的防禦:sections 在 RenderCV 的模型裡是可空的,而 COALESCE 救不了你,因為 JSON 的 null 不是 SQL 的 NULL——jsonb_each 會直接拋 cannot call jsonb_each on a non-object。那個 jsonb_typeof(e) = 'object' 守衛同理: 一個 TextEntry section 就是一串純字串,jsonb_array_elements 會把那些字串 當作元素交給你。

三個問題,一個比一個煩人:

  1. s.title ~* '(education|academic|study)' 是個猜測。 它會漏掉 Bildungsweg、 Things I Did 和 edu;同時也會誤傷——如果有人把某個 section 命名為 "Education Policy Publications",它就會被當成教育經歷。
  2. 你可以部分修復它:去掉標題過濾,只靠 e ? 'institution' 判斷。公平地說, RenderCV 的 entry 型別在這裡是真正的緩解手段——entry 型別是一個語意錨點,能扛住 重新命名。但它只在該作者選了 EducationEntry 時有效。若用 NormalEntry 寫同一段 教育經歷,它就成了 {name: "...", ...},institution 根本不存在。
  3. 值仍然是髒的。 即使你找齊了每個 degree 欄位,拿到的還是這樣:
SELECT lower(trim(e ->> 'degree')) AS degree_raw, count(*)
FROM resumes r
CROSS JOIN LATERAL jsonb_each(
  CASE WHEN jsonb_typeof(r.content -> 'cv' -> 'sections') = 'object'
       THEN r.content -> 'cv' -> 'sections'
       ELSE '{}'::jsonb END
) AS s(title, entries)
CROSS JOIN LATERAL jsonb_array_elements(s.entries) AS e
WHERE jsonb_typeof(e) = 'object' AND e ? 'degree'
GROUP BY lower(trim(e ->> 'degree'));
 degree_raw        | count
-------------------+-------
 bs                |   412
 b.sc.             |    37
 bachelor          |    21
 bachelor of science|     9
 phd               |   188
 ph.d.             |    44
 doctorate         |     6
 ms                |   301
 msc               |    58
 master of science |    27

上面的數字是示意值。它們展示的是你應該預期看到的分布形狀,而不是某一份具體語料的執行結果。

現在你需要一張同義詞表,而且得永遠維護它,因為 schema 裡沒有任何東西能阻止下一個 使用者發明新的拼法。這就是「應用層程式碼稅」,它隨語料規模成長,而不是保持恆定。

投影(projection)問題

固定模型的真正回報是:你可以宣告式地把 JSONB 投影進關聯表——沒有解析、沒有啟發式、 沒有未知 key:

CREATE VIEW resume_work AS
SELECT r.id AS resume_id,
       w ->> 'name'      AS company,
       w ->> 'position'  AS position,
       w ->> 'startDate' AS start_date,
       w ->> 'endDate'   AS end_date
FROM resumes r,
     jsonb_array_elements(r.content -> 'work') AS w;

這個檢視表在你的整個語料上都是穩定的。你可以在它上面搭 ATS 儀表板、BI 工具,或者跟你的 employees 表做 JOIN。同樣的語句放在 RenderCV 上不只是更難——它是沒有明確定義 的,因為「公司」可能是 company 也可能是 name,而承載它的 section 又叫什麼都行。

如果你攝取的是 YAMLResume 檔案,你還可以用 CLI 驗證所用的同一份 schema 來推導資料庫 約束,而不必手工維護一份平行副本:

ALTER TABLE resumes
  ADD CONSTRAINT degree_valid CHECK (
    content -> 'education' IS NULL
    OR NOT jsonb_path_exists(
      content,
      '$.education[*].degree ? (@ != "Middle School" && @ != "High School"
        && @ != "Diploma" && @ != "Associate" && @ != "Bachelor"
        && @ != "Master" && @ != "Doctor")'
    )
  );

囉唆,但它是產生的——而且對每一列、永遠成立。

索引

對 YAMLResume 的資料,一個 GIN 索引就能涵蓋上面的所有查詢:

CREATE INDEX resumes_content_gin ON resumes USING gin (content jsonb_path_ops);

jsonb_path_ops 支援 @>、@? 和 @@,這恰好就是你需要的算子集合:包含操作用於 列舉匹配,JSON path 用於關鍵字檢索。如果你經常按某個陣列過濾,就索引整個陣列, 而不是其中一個元素:

CREATE INDEX resumes_education_gin
  ON resumes USING gin ((content -> 'education') jsonb_path_ops);

索引 content -> 'education' -> 0 ->> 'degree' 會是個錯誤,而且很隱蔽:它只索引一個人 第一筆教育經歷,於是任何把碩士學歷寫在第二筆的人,在這個索引裡都是不可見的。 直接索引陣列本身就沒有這個失效模式。

對 RenderCV 的資料,沒有穩定的路徑可供索引。你只能為每個語意概念建一個生成欄位,而每個 生成欄位都要先在 SQL 裡解決「哪個 section 才是教育經歷」的問題。團隊實際會採用的答案是 一個每晚跑的的正規化任務——換句話說,他們最終還是把固定 schema 建起來了,只是更晚、 在第二個系統裡、並且沿途丟資料。

MongoDB 裡的同一個故事

MongoDB 對巢狀的履歷文件更友善,而差異仍然出現在同一個地方:查詢到底是一個 filter, 還是一段腳本。

用 YAMLResume,查詢和索引都是直接的:

db.resumes.createIndex({ 'content.education.degree': 1 })
db.resumes.createIndex({ 'content.skills.keywords': 1 })

db.resumes.find(
  { 'content.education.degree': 'Master' },
  { 'content.basics.name': 1 }
)

db.resumes.aggregate([
  { $unwind: '$content.education' },
  { $group: { _id: '$content.education.degree', n: { $sum: 1 } } },
  { $sort: { n: -1 } },
])

這些是已知路徑上的 multikey 索引,伺服器會替你做事。

用 RenderCV,cv.sections 是一個 key 未知的 map,所以你無法為一條你不知道的路徑建 索引。能做到的最好情況是在讀取時正規化:

db.resumes.aggregate([
  { $project: { sections: { $objectToArray: '$cv.sections' } } },
  { $unwind: '$sections' },
  { $unwind: '$sections.v' },
  {
    $match: {
      $or: [
        { 'sections.v.institution': { $exists: true } },
        { 'sections.k': /education/i },
      ],
    },
  },
  { $group: { _id: '$sections.v.degree', n: { $sum: 1 } } },
])

它能跑,但這是一次帶正規表達式和 $exists 探測的集合掃描。它用不上索引,而且語意會 隨著使用者發明新的拼法和 section 名而變化。幾百份文件時沒問題;幾十萬份時它就是個 批次任務。

RenderCV 的模型可能更好的地方

公平地讀,必須承認有幾處靈活文件模型佔優、而固定 schema 會讓你付出代價:

  • 日期。 RenderCV 的 start_date / end_date 被限定為 YYYY-MM-DD、YYYY-MM、 YYYY,或字面量 present,並被解析成真正的 date 物件,用於時長計算和 start > end 驗證。YAMLResume 的日期是 Date.parse 能接受的任何字串——這很適合 敲 Sep 1, 2016,也很適合做地道的本地化,但不利於範圍查詢。如果你要在 YAMLResume 上建 HR 系統,就在 content 之外另存一個正規化的 start_date date 欄位,不要試圖對 顯示字串做範圍查詢。
  • 任意 section。 一個博士生想放 "Invited Talks"、"Patents"、"Teaching"。RenderCV 原生支援。YAMLResume 有十二個可改名的 section,能涵蓋大多數履歷,但涵蓋不了所有 CV。
  • entry 級別的可擴充性。 RenderCV 的 entry 模型是 extra="allow",所以模板可以 掛上衍生欄位(渲染後的日期字串、計算出的時長)而不破壞驗證。這是一個乾淨的分層 手法。
  • 社群網路。 RenderCV 驗證 17 個平台,並帶各平台的使用者名稱規則(Mastodon 需要 @user@domain,ORCID 需要形如檢驗碼的 ID,StackOverflow 需要 id/name),還會 推導出主頁 URL。YAMLResume 接受一個 network 列舉加一個自由 username,URL 由你 自己給。
  • 拒絕拼寫錯誤。 RenderCV 的頂層模型是 extra="forbid",所以拼錯的 key 會報錯。 YAMLResume 依賴 Zod 物件的預設行為,也就是**剝離(strip)**未知 key——這意味著 certifcates 這類拼寫錯誤會被靜默丟棄,而不是被報告出來。如果你在跑攝取流程, 請在信任一份文件之前,先在你這一側用 additionalProperties: false 的 JSON Schema 驗證它。

這些都不推翻結論,只是給它劃定了範圍:RenderCV 的模型更適合精雕一份 CV,更不適合 對很多份做推理。

場景裁決

履歷建置器(多租戶 SaaS)。 你需要按使用者存文件、版本歷史、diff 和模板切換。固定 key 讓 diff 有意義——一次改動是 content.work[2].position,而不是「dict 裡的某一列」。 它們也讓模板切換安全,因為 layouts 是獨立的陣列,content 從不搬家。YAMLResume 的 模型是更好的底座。如果你從不需要跨使用者查詢、而你的使用者又非要奇怪的 section,那麼 RenderCV 的模型更省事。

HR / ATS 流程。 這是最清晰的案例。你存的不是履歷,而是候選人,履歷只是其中 一個屬性。你需要跟職位、階段、員工做 join,還要出報表(「有多少進入面試的候選人擁有 碩士學位?」)。帶列舉詞彙的固定 schema 讓你用 SQL 就能完成這一切。自由形態的文件 模型則把你推進一個永遠寫不完的 etl/normalize.py。

ERP / HRIS。 履歷是龐大的正規化世界裡的一小塊。比儲存更重要的是整合的方向: 固定 key 讓你機械地產生從履歷 JSON 到你的 Person、Education、Employment 規範 實體的對應。任意 key 則意味著要有人逐個客戶地寫和維護這份對應。

資料交換。 YAMLResume 的 schema 沿用了 JSON Resume 的形狀,並由 json2yamlresume 在兩種格式之間轉換。 它的價值在於讓你無需先發明一套格式就能把履歷資料對應進自己的模型,而不是對某個第三方 生態的健康度做背書。一份 RenderCV 檔案是一份定義良好的文件,但它的形狀是為排版最佳化 的,而不是為交換最佳化的。

一個人,一份漂亮的 PDF。 RenderCV 完勝。任意 section、強型別日期、逐元素樣式、 Typst 數學,當讀者是人類而不是資料庫時,這些都恰到好處。

實操配方

如果你在建系統、並且由你來選,那麼存記錄模型,把文件模型當作渲染層的事。具體來說:

  1. 為每份履歷保留一筆規範的、經過 schema 驗證的記錄(YAMLResume 裡的 content)。 在寫入時、在邊界上做驗證。
  2. 永遠不要把顯示字串當作事實來源。存正規化後的日期和列舉值;讀的時候再本地化。
  3. 把呈現——模板、別名、section 順序、顏色——放在單獨的欄位或表裡。它是檢視狀態, 不是履歷資料。
  4. 如果你必須攝取 RenderCV 風格的文件,就把原始 YAML 存下來以保證保真度,同時 在攝取時投影進正規化形狀。把「猜」這件事做一次、並在審核之下完成,而不是在每一次 報表裡都做。

小結

兩個工具都是 "resume as code",而且都做得不錯。但它們的資料模型回答的是不同的 問題:

屬性YAMLResumeRenderCV
section key固定,14 個已知 key任意字串
entry 形狀每個 section 固定9 種推斷型別 + 字串
degree / level / fluency列舉,可翻譯自由字串
日期自由形態,本地化優先強型別 YYYY-MM[p-D] + present
section 順序與標題在 layouts[] 裡dict key 順序與 key 名
未知 key剝離(靜默)頂層禁止
無需應用層程式碼即可查詢是部分可以,靠 entry 型別欄位
任意 section否(12 個可改名)是
schema 來源沿用 JSON Resume 形狀自有文件形狀

YAMLResume 把履歷建模成一筆記錄:在你整個語料裡,同樣的 key、同樣的詞彙、同樣 的意義。RenderCV 把它建模成一份文件:創作時你想要的一切自由,以及批次讀取時隨之 而來的一切歧義。

兩者都不錯。它們是針對不同讀者的最佳化——一個資料庫,或者一個拿著 PDF 的人。

如果你想要更宏觀的逐項對比(包含引擎、本地化和工具鏈),請看 YAMLResume vs RenderCV。至於 schema 本身, 型別參考和 JSON Schema 是 權威來源。

Written by

Xiao Hanyu

At