YAMLResume vs RenderCV: Registro ou Documento?

Procuras uma alternativa ao RenderCV? As duas ferramentas aceitam YAML, mas uma modela o currículo como um registro consultável e a outra como um documento livre. Eis o que essa diferença custa — e poupa — no Postgres e no MongoDB.

Se comparares o YAMLResume com o RenderCV, as diferenças óbvias são os motores de renderização e o número de ajustes visuais. Já abordámos isso na comparação lado a lado. Este artigo trata de algo mais estreito e, para quem constrói um sistema em vez de um único PDF, muito mais determinante: a forma dos dados.

As duas ferramentas aceitam YAML, validam-no e transformam-no num PDF. Mas estão a modelar duas coisas diferentes:

  • O YAMLResume modela o currículo como um registro (record) — uma linha cujas linhas partilham todos o mesmo schema.
  • O RenderCV modela o currículo como um documento (document) — uma árvore cuja forma é controlada pelo autor.

Não é uma distinção cosmética. Determina se "encontrar todas as pessoas com um mestrado" é uma consulta SQL ou um projeto de análise na camada de aplicação. Vejamos então os dois modelos em concreto, e depois o que eles te custam num construtor de currículos, num sistema de RH ou num ERP.

Dois modelos, um currículo

Eis os dados da mesma pessoa em cada formato. Nada de artificial — é aproximadamente o que yamlresume new e rendercv new produzem.

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

À primeira vista parecem primos. Não são. Quatro decisões estruturais separam-nos, e cada uma tem uma consequência direta ao nível do armazenamento.

1. As chaves de secção são fixas?

O YAMLResume tem um conjunto fechado de chaves de secção. O schema de conteúdo combina exatamente catorze: basics, location, profiles, education, work, volunteer, awards, certificates, publications, skills, languages, interests, references, projects. Um currículo que escreva certifcates por engano não tem uma secção de certificados — não há forma de expressar uma secção que não esteja na lista.

O equivalente no RenderCV é uma linha de Pydantic:

sections: dict[str, Section] | None

A chave é um str. Não há palavras reservadas. Um utilizador pode escrever education, Education, education_and_training, Academic Background, 教育 ou Things I Did. No JSON Schema gerado, esse campo é literalmente additionalProperties: { "$ref": "#/$defs/Section" } — o schema diz ao validador "qualquer chave serve", e nada mais.

2. Os nomes dos campos significam o mesmo em todo o lado?

Esta é a parte fácil de escapar, e a que mais dói numa base de dados. O RenderCV não tem um único schema de entrada; tem nove tipos de entrada (ExperienceEntry, EducationEntry, PublicationEntry, NormalEntry, OneLineEntry, BulletEntry, NumberedEntry, ReversedNumberedEntry), mais uma simples string chamada TextEntry. O tipo de uma secção é inferido a partir da primeira entrada que corresponde, usando uma tabela de "campos característicos" — os campos únicos de cada tipo:

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

Uma entrada que contenha institution é uma EducationEntry, porque nenhum outro tipo declara institution. Uma entrada apenas com name é uma NormalEntry. Depois, validate_section() exige que todas as entradas dessa secção sejam do mesmo tipo.

Consequência: o nome do campo para "a organização" depende do tipo que o utilizador escolheu implicitamente.

ConceitoExperienceEntryEducationEntryNormalEntry
Organizaçãocompanyinstitutionname
Função / assuntopositionarea—
Grau—degree—

Repara no que não está nessa tabela. Datas, location, summary e highlights são idênticos nos três tipos, por isso também não te ajudam a distingui-los — os únicos sinais são as três linhas acima.

Assim, "onde é que esta pessoa trabalhou" é cv.sections.*[*].company se usou ExperienceEntry, e ...name se usou NormalEntry para a mesma informação. E uma secção pode ser apenas strings simples, já que TextEntry é um str — o que significa que entries é estruturalmente list[str] | list[dict], sem qualquer garantia de forma.

O YAMLResume não tem essa deriva: a empresa é sempre work[].name, a instituição é sempre education[].institution, e uma secção de competências é sempre {name, level, keywords}.

3. Os valores vêm de um vocabulário controlado?

O YAMLResume fixa os valores que os sistemas normalmente precisam de comparar:

  • degree ∈ Middle School | High School | Diploma | Associate | Bachelor | Master | Doctor
  • level (competências) ∈ Novice | Beginner | Intermediate | Advanced | Expert | Master
  • fluency ∈ cinco níveis derivados do ILR, de Elementary Proficiency a Native or Bilingual Proficiency
  • country, language, network — longas listas fixas, também usadas para tradução

O degree do RenderCV é str | None. O próprio CV de exemplo usa PhD e BS. É perfeitamente razoável para composição tipográfica — e significa que um corpus de ficheiros RenderCV contém PhD, Ph.D., Doctorate, BS, BSc, Bachelor of Science, MS, MSc, M.S., Master of Science, todos a significar apenas duas coisas.

Um detalhe que vale a pena registar a favor do YAMLResume: o valor canónico é guardado uma vez, em inglês, e localizado no momento da renderização. O currículo chinês e o currículo inglês da mesma pessoa transportam valores canónicos idênticos. Com strings livres, o valor é o que o autor escreveu na sua língua, o que torna a agregação entre locales praticamente impossível.

4. Onde vive a apresentação?

No RenderCV, o título apresentado da secção é a chave do dict, e a ordem de apresentação é a ordem de inserção do dict (get_rendercv_sections() percorre sections.items() e converte as chaves snake_case para Title Case). Muda a aparência do currículo e mudaste os dados.

No YAMLResume, ambos vivem em layouts[], sob sections.aliases e sections.order. O conteúdo mantém chaves e ordem canónicas, e cada formato de saída pode apresentá-las de forma diferente.

Uma decisão, quatro sintomas

Estas quatro respostas não são independentes. São todas consequências de uma única postura de design, e dar-lhe nome torna o compromisso mais fácil de raciocinar:

  • O YAMLResume é opinionated por design. É o schema que decide — que secções existem, como se chama cada campo, que valores são permitidos, onde a apresentação acaba e o conteúdo começa. O autor preenche uma forma que não escolheu.
  • O RenderCV é free-form por design. É o autor que decide. O schema valida que cada entrada está internamente bem formada e depois sai do caminho.

Ambos são legítimos, e os custos são simétricos:

O custo de ser opinionated é um teto de expressividade. Se o teu currículo precisa de uma secção "Patents" ou "Invited Talks" que não está entre as catorze chaves do YAMLResume, não a podes expressar nativamente. Tens doze títulos de secção renomeáveis, o que cobre a maioria dos currículos mas não todos os CV.

O custo de ser free-form é um piso semântico. O schema não pode prometer que algo no documento seja comparável a outra coisa. Dois autores a expressar factos idênticos produzem documentos que não partilham chaves, vocabulário nem estrutura — o que é aceitável até algo além de um leitor humano precisar de os consumir.

A assimetria que importa para este artigo é quando pagas. O modelo opinionated cobra-te no momento da autoria, uma vez, em moeda pequena: não podes dizer uma coisa que querias dizer. O modelo free-form cobra-te no momento da leitura, para sempre, numa moeda que se compõe: cada novo título de secção que um utilizador inventa, e cada nova grafia de Master, é mais um ramo em algum parser a jusante. Um custo é pago uma vez por um autor; o outro é pago repetidamente por cada sistema que toca nos dados depois.

É por isso que o resto deste artigo é sobre leitores — bases de dados, pipelines de ATS, importações de HRIS — e não sobre autores.

O que isso custa no Postgres

Assumamos o schema óbvio — aquele a que todos os construtores de currículos acabam por chegar:

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

Com o modelo do YAMLResume, os caminhos são conhecidos antes de qualquer dado chegar, por isso podes indexá-los e consultá-los diretamente.

-- Todas as pessoas com mestrado
SELECT id, content -> 'basics' ->> 'name' AS name
FROM resumes
WHERE content -> 'education' @> '[{"degree": "Master"}]';

-- Candidatos com Kubernetes no currículo
SELECT id, content -> 'basics' ->> 'name' AS name
FROM resumes
WHERE content @? '$.skills[*].keywords[*] ? (@ == "Kubernetes")';

-- Contagem por grau, sem qualquer passo de normalização
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;

A última é todo o argumento em poucas linhas. É um simples GROUP BY sobre um vocabulário fechado, e o resultado é imediatamente correto.

Agora o equivalente no RenderCV. Os nomes das secções são desconhecidos, por isso tens de os percorrer; as formas das entradas são desconhecidas, por isso tens de sondar um campo que identifique uma entrada de educação:

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';

O CASE WHEN não é ruído defensivo: sections é nullable no modelo do RenderCV, e COALESCE não ajuda, porque o null JSON não é NULL SQL — jsonb_each lança cannot call jsonb_each on a non-object. A guarda jsonb_typeof(e) = 'object' importa pelo mesmo motivo: uma secção TextEntry é uma lista de strings simples, e jsonb_array_elements devolver-te-á essas strings como elementos.

Três problemas, por ordem crescente de incómodo:

  1. s.title ~* '(education|academic|study)' é um palpite. Falha Bildungsweg, Things I Did e edu. Também produz falsos positivos se alguém chamar a uma secção "Education Policy Publications".
  2. Podes corrigir isso em parte removendo o filtro de título e confiando apenas em e ? 'institution'. É justo dizê-lo: os tipos de entrada do RenderCV são aqui uma mitigação real — o tipo de entrada é uma âncora semântica que sobrevive à mudança de nome. Mas só funciona se o autor escolheu EducationEntry. Escrita como NormalEntry, a mesma formação torna-se {name: "...", ...} e institution não existe.
  3. Os valores continuam sujos. Mesmo depois de encontrares todos os campos de grau, obténs isto:
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

Os números acima são ilustrativos. Mostram a forma da distribuição que deves esperar, não o resultado de um corpus específico.

Agora precisas de uma tabela de sinónimos, e precisas de a manter para sempre, porque nada no schema impede o próximo utilizador de inventar uma nova grafia. É o "imposto de código na camada de aplicação", e cresce com o teu corpus em vez de se manter fixo.

O problema da projeção

O verdadeiro retorno de um modelo fixo é que podes projetar JSONB em tabelas relacionais de forma declarativa — sem parsing, sem heurísticas, sem chaves desconhecidas:

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;

Essa vista é estável em todo o teu corpus. Podes colocar-lhe em cima um painel de ATS, uma ferramenta de BI, ou um JOIN com a tua tabela employees. A mesma instrução para o RenderCV não é apenas mais difícil — é mal definida, porque "empresa" pode ser company ou name, e a secção que a contém pode ter qualquer título.

Se estiveres a ingerir ficheiros YAMLResume, podes também derivar as tuas restrições de base de dados a partir do mesmo schema com que o CLI valida, em vez de manteres à mão uma cópia paralela:

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")'
    )
  );

Verborrágico, mas gerado — e vale para cada linha, para sempre.

Indexação

Para dados do YAMLResume, um único índice GIN cobre as consultas acima:

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

jsonb_path_ops suporta @>, @? e @@, que é exatamente o conjunto de operadores de que precisas: contenção para correspondências de enumeração, caminho JSON para pesquisas por palavra-chave. Se filtrares frequentemente por um array, indexa o array inteiro em vez de um único elemento:

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

Indexar content -> 'education' -> 0 ->> 'degree' seria um erro, e subtil: indexa apenas a primeira formação de um candidato, por isso quem tem o mestrado em segundo lugar fica invisível para esse índice. Indexar o próprio array não tem esse modo de falha.

Para dados do RenderCV não há um caminho estável para indexar. Terias de criar uma coluna gerada por conceito semântico, e cada uma exige resolver primeiro em SQL a questão "que secção é a educação". A resposta prática a que as equipas recorrem é uma tarefa de normalização noturna — ou seja, acabam por construir o schema fixo de qualquer maneira, só que mais tarde, num segundo sistema, com perda de dados pelo caminho.

A mesma história no MongoDB

O MongoDB é mais amigável com documentos de currículo aninhados, e a diferença aparece no mesmo sítio: se a consulta é um filtro ou um script.

Com o YAMLResume, tanto a consulta como o índice são diretos:

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 } },
])

São índices multikey sobre um caminho conhecido, por isso o servidor faz o trabalho.

Com o RenderCV, cv.sections é um mapa com chaves desconhecidas, por isso não podes indexar um caminho que não conheces. O melhor que podes fazer é normalizar no momento da leitura:

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 } } },
])

Funciona, mas é uma varredura de coleção com uma expressão regular e uma sonda $exists. Não pode usar um índice, e o seu significado muda à medida que os utilizadores inventam novas grafias e nomes de secção. Com algumas centenas de documentos não há problema. Com algumas centenas de milhares é uma tarefa em lote.

Onde o modelo do RenderCV pode ser melhor

Uma leitura justa tem de admitir vários pontos em que o modelo de documento livre ganha, e em que um schema fixo te custa:

  • Datas. Os start_date / end_date do RenderCV estão limitados a YYYY-MM-DD, YYYY-MM, YYYY ou ao literal present, analisados em objetos date reais para cálculo de duração e validação start > end. As datas do YAMLResume são tudo o que Date.parse aceita — ótimo para escrever Sep 1, 2016 e para localização idiomática, fraco para consultas por intervalo. Se estás a construir um sistema de RH sobre o YAMLResume, guarda uma coluna start_date date normalizada ao lado do conteúdo; não tentes consultar por intervalo a string de apresentação.
  • Secções arbitrárias. Um doutorando quer "Invited Talks", "Patents", "Teaching". O RenderCV suporta-as nativamente. O YAMLResume tem doze secções renomeáveis, o que pode cobrir a maioria dos currículos mas não todos os CV.
  • Extensibilidade ao nível da entrada. Os modelos de entrada do RenderCV são extra="allow", por isso os templates podem anexar campos derivados (strings de data renderizadas, durações calculadas) sem quebrar a validação. É um truque de camadas limpo.
  • Redes sociais. O RenderCV valida 17 plataformas com regras de nome de utilizador por plataforma (o Mastodon exige @user@domain, o ORCID exige um ID em forma de soma de verificação, o StackOverflow exige id/name) e deriva o URL do perfil. O YAMLResume aceita uma enumeração network e um username livre, e usa o URL tal como é fornecido.
  • Rejeitar erros ortográficos. Os modelos de topo do RenderCV são extra="forbid", por isso uma chave mal escrita é um erro. O YAMLResume assenta no comportamento predefinido dos objetos Zod, que remove chaves desconhecidas — o que significa que um erro como certifcates é silenciosamente descartado em vez de reportado. Se operas um pipeline de ingestão, valida contra o JSON Schema com additionalProperties: false do teu lado antes de confiar num documento.

Nada disto inverte a conclusão. Apenas a delimita: o modelo do RenderCV é melhor para escrever um CV com precisão, e pior para raciocinar sobre muitos.

Veredictos por cenário

Construtor de currículos (SaaS multi-tenant). Precisas de documentos por utilizador, histórico de versões, diffs e mudança de template. Chaves fixas tornam os diffs significativos — uma alteração é content.work[2].position, não "uma linha em algum lugar de um dict". Também tornam a mudança de template segura, porque layouts é um array separado e o conteúdo nunca se move. O modelo do YAMLResume é o melhor substrato. O do RenderCV é mais fácil se nunca precisares de consultar entre utilizadores e os teus utilizadores exigirem secções invulgares.

Pipeline de RH / ATS. É o caso mais claro. Não estás a guardar currículos; estás a guardar candidatos, e o currículo é apenas um atributo. Precisas de join com vagas, fases e colaboradores, mais relatórios ("quantos candidatos pré-selecionados têm mestrado?"). Um schema fixo com vocabulários de enumeração dá-te tudo isso em SQL. Um modelo de documento livre empurra-te para um etl/normalize.py que nunca fica terminado.

ERP / HRIS. Os currículos são uma pequena parte de um vasto mundo normalizado. A direção da integração importa mais que o armazenamento: chaves fixas permitem-te gerar mecanicamente um mapeamento do JSON do currículo para as tuas entidades canónicas Person, Education e Employment. Chaves arbitrárias significam que um humano escreve e mantém esse mapeamento cliente a cliente.

Troca de dados. O schema do YAMLResume segue a forma do JSON Resume, e o json2yamlresume converte entre os dois formatos. Isso importa para mapear dados de currículo para o teu próprio modelo sem inventar um formato antes, e não como uma afirmação sobre a saúde de um ecossistema de terceiros. Um ficheiro RenderCV é um documento bem definido, mas a sua forma é ajustada para composição tipográfica e não para intercâmbio.

Uma pessoa, um belo PDF. O RenderCV ganha claramente. Secções arbitrárias, datas tipadas, estilo por elemento e matemática Typst são exatamente o que é preciso quando o público é um leitor humano em vez de uma base de dados.

A receita prática

Se estás a construir um sistema e podes escolher, guarda o modelo de registro e trata o modelo de documento como uma questão de renderização. Concretamente:

  1. Mantém um registro canónico e validado pelo schema por currículo (content no YAMLResume). Valida na escrita, na fronteira.
  2. Nunca guardes strings de apresentação como fonte de verdade. Guarda datas normalizadas e valores de enumeração; localiza na leitura.
  3. Mantém a apresentação — template, aliases, ordem das secções, cores — numa coluna ou tabela separada. É estado de vista, não dados de currículo.
  4. Se tiveres mesmo de ingerir documentos ao estilo do RenderCV, guarda o YAML bruto para fidelidade e projeta-o para a forma normalizada na ingestão. Faz o palpite uma vez, sob revisão, em vez de em cada relatório.

Resumo

As duas ferramentas são "resume as code", e ambas o fazem bem. Mas os seus modelos de dados respondem a perguntas diferentes:

PropriedadeYAMLResumeRenderCV
Chaves de secçãoFixas, 14 chaves conhecidasStrings arbitrárias
Forma da entradaFixa por secção9 tipos inferidos + strings
Degree / level / fluencyEnumeração, traduzidaStrings livres
DatasLivres, localização primeiroTipadas YYYY-MM[p-D] + present
Ordem e títulos das secçõesEm layouts[]Ordem e nomes das chaves do dict
Chaves desconhecidasRemovidas (silenciosamente)Proibidas no topo
Consultável sem código de aplicaçãoSimParcialmente, via campos de tipo de entrada
Secções arbitráriasNão (12 renomeáveis)Sim
Origem do schemaForma do JSON ResumeForma de documento própria

O YAMLResume modela o currículo como um registro: as mesmas chaves, o mesmo vocabulário, o mesmo significado, para cada documento do teu corpus. O RenderCV modela-o como um documento: toda a liberdade que possas querer ao escrever, e toda a ambiguidade que vem com ela quando lês em escala.

Nenhum está errado. São otimizações para leitores diferentes — uma base de dados, ou uma pessoa com um PDF na mão.

Para a visão mais ampla, funcionalidade a funcionalidade, incluindo motores, locales e ferramentas, vê YAMLResume vs RenderCV. Quanto ao schema em si, a referência de tipos e o JSON Schema são as fontes autoritativas.

Written by

Xiao Hanyu

At