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.
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-classiccv:
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] | NoneA 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.
| Conceito | ExperienceEntry | EducationEntry | NormalEntry |
|---|---|---|---|
| Organização | company | institution | name |
| Função / assunto | position | area | — |
| 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 | Doctorlevel(competências) ∈Novice | Beginner | Intermediate | Advanced | Expert | Masterfluency∈ cinco níveis derivados do ILR, deElementary ProficiencyaNative or Bilingual Proficiencycountry,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:
s.title ~* '(education|academic|study)'é um palpite. FalhaBildungsweg,Things I Dideedu. Também produz falsos positivos se alguém chamar a uma secção "Education Policy Publications".- 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 escolheuEducationEntry. Escrita comoNormalEntry, a mesma formação torna-se{name: "...", ...}einstitutionnão existe. - 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 | 27Os 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_datedo RenderCV estão limitados aYYYY-MM-DD,YYYY-MM,YYYYou ao literalpresent, analisados em objetosdatereais para cálculo de duração e validaçãostart > end. As datas do YAMLResume são tudo o queDate.parseaceita — ótimo para escreverSep 1, 2016e para localização idiomática, fraco para consultas por intervalo. Se estás a construir um sistema de RH sobre o YAMLResume, guarda uma colunastart_date datenormalizada 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 exigeid/name) e deriva o URL do perfil. O YAMLResume aceita uma enumeraçãonetworke umusernamelivre, 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 comocertifcatesé silenciosamente descartado em vez de reportado. Se operas um pipeline de ingestão, valida contra o JSON Schema comadditionalProperties: falsedo 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:
- Mantém um registro canónico e validado pelo schema por currículo (
contentno YAMLResume). Valida na escrita, na fronteira. - Nunca guardes strings de apresentação como fonte de verdade. Guarda datas normalizadas e valores de enumeração; localiza na leitura.
- 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.
- 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:
| Propriedade | YAMLResume | RenderCV |
|---|---|---|
| Chaves de secção | Fixas, 14 chaves conhecidas | Strings arbitrárias |
| Forma da entrada | Fixa por secção | 9 tipos inferidos + strings |
| Degree / level / fluency | Enumeração, traduzida | Strings livres |
| Datas | Livres, localização primeiro | Tipadas YYYY-MM[p-D] + present |
| Ordem e títulos das secções | Em layouts[] | Ordem e nomes das chaves do dict |
| Chaves desconhecidas | Removidas (silenciosamente) | Proibidas no topo |
| Consultável sem código de aplicação | Sim | Parcialmente, via campos de tipo de entrada |
| Secções arbitrárias | Não (12 renomeáveis) | Sim |
| Origem do schema | Forma do JSON Resume | Forma 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 HanyuAt