Schema reference

This page documents every field of the takuhon.json schema: each section, its type, whether it is required, its constraints, and what it is for. For a gentler introduction to the document as a whole, see The takuhon.json file.

The tables below are generated from the canonical schema (version 0.6.0). Field descriptions are reproduced verbatim from the schema, which is maintained in English as the canonical contract.

Top-level document

Field	Type	Required	Constraints	Description
schemaVersion	string	Yes	pattern ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?$	Semantic version of the takuhon schema this document conforms to.
profile	Profile	Yes	—	—
links	array of Link	Yes	≤ 100 items	—
careers	array of Career	Yes	≤ 50 items	—
projects	array of Project	Yes	≤ 100 items	—
skills	array of Skill	Yes	≤ 200 items	—
certifications	array of Certification	No	≤ 50 items	—
memberships	array of Membership	No	≤ 50 items	—
volunteering	array of Volunteering	No	≤ 50 items	—
honors	array of Honor	No	≤ 50 items	—
education	array of Education	No	≤ 30 items	—
publications	array of Publication	No	≤ 100 items	—
languages	array of Language	No	≤ 30 items	—
courses	array of Course	No	≤ 100 items	—
patents	array of Patent	No	≤ 50 items	—
testScores	array of TestScore	No	≤ 30 items	—
recommendations	array of Recommendation	No	≤ 50 items	—
contact	Contact	Yes	—	—
settings	Settings	Yes	—	—
meta	Meta	Yes	—	—

No additional properties beyond those listed.

Definitions

LocaleTag

BCP-47 language tag (e.g., ‘en’, ‘ja’, ‘zh-Hant’, ‘pt-BR’).

• Type: string
• Constraints: pattern ^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$; 2–35 chars

Iso3166Alpha2

ISO 3166-1 alpha-2 country code (uppercase, two letters).

• Type: string
• Constraints: pattern ^[A-Z]{2}$

YearMonth

Year-month in ‘YYYY-MM’ format (Gregorian calendar).

• Type: string
• Constraints: pattern ^[0-9]{4}-(0[1-9]|1[0-2])$

IsoDateTime

ISO 8601 date-time (e.g., 2026-05-11T12:34:56Z).

• Type: string
• Constraints: format date-time

Url

• Type: string
• Constraints: format uri; ≤ 2048 chars

Email

• Type: string
• Constraints: format email; ≤ 254 chars

Slug

URL-safe identifier (lowercase alphanumerics and hyphens, must start with alphanumeric).

• Type: string
• Constraints: pattern ^[a-z0-9][a-z0-9-]*$; 1–64 chars

LocalizedTitle

Map of BCP-47 locale tag to short title-like string (max 200 chars per value).

• Type: object (map)
• Keys: pattern ^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$
• Values: string (1–200 chars)
• Constraints: at least 1 entry

LocalizedBody

Map of BCP-47 locale tag to body-length string (max 5000 chars per value).

• Type: object (map)
• Keys: pattern ^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$
• Values: string (1–5000 chars)
• Constraints: at least 1 entry

LinkType

Identifies the kind of link. ‘custom’ requires iconUrl.

• Type: string
• Constraints: one of: website, blog, github, gitlab, linkedin, x, mastodon, bluesky, instagram, youtube, threads, facebook, email, rss, custom

Profile

Field	Type	Required	Constraints	Description
displayName	LocalizedTitle	Yes	—	—
tagline	LocalizedTitle	No	—	—
bio	LocalizedBody	No	—	—
avatar	Avatar	No	—	—
location	Address	No	—	—

Avatar

Field	Type	Required	Constraints	Description
url	string	Yes	format uri-reference; ≤ 2048 chars	URL or path to the avatar image.
alt	LocalizedTitle	No	—	—

Address

Field	Type	Required	Constraints	Description
country	Iso3166Alpha2	No	—	—
region	string	No	≤ 100 chars	—
locality	LocalizedTitle	No	—	—
display	LocalizedTitle	No	—	—

Link

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
type	LinkType	Yes	—	—
label	LocalizedTitle	No	—	—
url	Url	Yes	—	—
featured	boolean	No	—	—
order	integer	No	≥ 0	—
iconUrl	Url	No	—	—

If type is custom, then iconUrl must be set. No additional properties beyond those listed.

Career

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
organization	LocalizedTitle	Yes	—	—
role	LocalizedTitle	Yes	—	—
description	LocalizedBody	No	—	—
startDate	YearMonth	Yes	—	—
endDate	YearMonth or null	No	—	—
isCurrent	boolean	No	—	—
url	Url	No	—	—
location	Address	No	—	—
order	integer	No	≥ 0	—

Project

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
title	LocalizedTitle	Yes	—	—
description	LocalizedBody	No	—	—
url	Url	No	—	—
tags	array of string	No	≤ 30 items; items: 1–50 chars	—
relatedCareerId	Slug	No	—	—
startDate	YearMonth	No	—	—
endDate	YearMonth or null	No	—	—
highlighted	boolean	No	—	—
order	integer	No	≥ 0	—

Skill

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
label	string	Yes	1–100 chars	—
category	string	No	1–64 chars	Recommended values (extensible): programming, design, business, communication, language, music, art, sports, other.
order	integer	No	≥ 0	—

Contact

Field	Type	Required	Constraints	Description
email	Email	No	—	—
showEmail	boolean	No	default false	—
formUrl	Url	No	—	—

Settings

Field	Type	Required	Constraints	Description
defaultLocale	LocaleTag	Yes	—	—
fallbackLocale	LocaleTag	No	—	—
availableLocales	array of LocaleTag	Yes	1–50 items; unique items	—
theme	string	No	1–64 chars	UI theme identifier. ‘default’ is the built-in theme; adapters may add more.
showPoweredBy	boolean	No	default true	Display the ‘Powered by takuhon’ attribution in the rendered profile.
enableJsonLd	boolean	No	default true	Emit Schema.org JSON-LD on the rendered profile page.
enableApi	boolean	No	default true	Expose the public read API endpoints (GET /api/profile, /api/jsonld, /api/schema, /takuhon.json).
enableAnalytics	boolean	No	default false	Opt-in flag for first-party analytics. Default is false to keep takuhon privacy-respecting by default.
activity	ActivitySettings	No	—	—
publicVisibility	PublicVisibility	No	—	—

PublicVisibility

Per-section public visibility (added in 0.6.0). Each key is a content section; setting it to false hides that whole section from every public surface (GET /, /api/profile, /api/jsonld, /takuhon.json, MCP, and the derived CV) via the shared applyPublicPrivacyFilter. An absent key — or an absent object — means the section is public, so the default is all-visible and omitting this block is fully backwards-compatible. The profile identity (profile.displayName, …) is always public and is intentionally not a key here. Field-level controls (contact.showEmail, meta.privacy.*) still apply within a visible section: visibility is the AND of the feature toggle, this section flag, and the field flag.

Field	Type	Required	Constraints	Description
links	boolean	No	—	Default true. When false, links[] is emitted empty on public surfaces.
careers	boolean	No	—	Default true. When false, careers[] is emitted empty on public surfaces.
projects	boolean	No	—	Default true. When false, projects[] is emitted empty on public surfaces.
skills	boolean	No	—	Default true. When false, skills[] is emitted empty on public surfaces.
certifications	boolean	No	—	Default true. When false, certifications[] is emitted empty on public surfaces.
memberships	boolean	No	—	Default true. When false, memberships[] is emitted empty on public surfaces.
volunteering	boolean	No	—	Default true. When false, volunteering[] is emitted empty on public surfaces.
honors	boolean	No	—	Default true. When false, honors[] is emitted empty on public surfaces.
education	boolean	No	—	Default true. When false, education[] is emitted empty on public surfaces.
publications	boolean	No	—	Default true. When false, publications[] is emitted empty on public surfaces.
languages	boolean	No	—	Default true. When false, languages[] is emitted empty on public surfaces.
courses	boolean	No	—	Default true. When false, courses[] is emitted empty on public surfaces.
patents	boolean	No	—	Default true. When false, patents[] is emitted empty on public surfaces.
testScores	boolean	No	—	Default true. When false, testScores[] is emitted empty on public surfaces.
recommendations	boolean	No	—	Default true. When false, recommendations[] is emitted empty on public surfaces.
contact	boolean	No	—	Default true. When false, the contact section (email, formUrl) is emitted empty on public surfaces.

No additional properties beyond those listed.

ActivitySettings

Opt-in developer-activity dashboard configuration (GitHub / WakaTime). Only the owner-curated settings live here; secrets are provisioned out of band and the synced metrics are stored in a separate document, never in takuhon.json.

Field	Type	Required	Constraints	Description
enabled	boolean	No	default false	Master switch. When false (the default), the activity section is not rendered even if a snapshot exists.
github	object	No	—	—
wakatime	object	No	—	—
showRank	boolean	No	default true	Display the derived activity rank / badge.
refreshHintHours	integer	No	1–168	Advisory refresh cadence in hours. The real cadence is how often the sync step (CLI command or scheduled job) runs.

No additional properties beyond those listed.

ActivitySettings.github

Field	Type	Required	Constraints	Description
username	string	Yes	1–39 chars	GitHub login whose public activity is summarized.
showLanguages	boolean	No	default true	—
showContributions	boolean	No	default true	—

No additional properties beyond those listed.

ActivitySettings.wakatime

Field	Type	Required	Constraints	Description
username	string	Yes	1–255 chars	WakaTime username whose coding-time stats are summarized.
showCodingTime	boolean	No	default true	—

No additional properties beyond those listed.

Meta

Field	Type	Required	Constraints	Description
createdAt	IsoDateTime	No	—	—
updatedAt	IsoDateTime	No	—	—
generator	string	No	1–100 chars	Tool that produced this document (e.g. ‘Takuhon’, ‘create-takuhon@0.1.0’).
contentLicense	ContentLicense	Yes	—	—
privacy	MetaPrivacy	No	—	—

ContentLicense

Field	Type	Required	Constraints	Description
spdxId	string	Yes	1–64 chars	SPDX identifier (e.g., ‘CC-BY-4.0’, ‘CC0-1.0’) or ‘Proprietary’. No default; the profile owner must choose explicitly.
url	Url	No	—	—
attribution	object	No	—	—
rights	string	No	1–1000 chars	Free-form rights statement (used when spdxId=‘Proprietary’ or for additional notices).

No additional properties beyond those listed.

ContentLicense.attribution

Field	Type	Required	Constraints	Description
name	string	No	1–200 chars	—
url	Url	No	—	—

No additional properties beyond those listed.

MetaPrivacy

Opt-out flags that strip personally identifying fields from public API output (GET /api/profile, /api/jsonld, /takuhon.json). Admin endpoints (PUT /api/admin/*, GET /api/admin/export) ignore these flags. Privacy-by-default: omitting the object or individual flags is equivalent to true.

Field	Type	Required	Constraints	Description
hideCredentialIds	boolean	No	default true	When true (default), strip certifications[*].credentialId from public responses.
hideEducationGrades	boolean	No	default true	When true (default), strip education[*].grade from public responses.

Certification

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
title	LocalizedTitle	Yes	—	—
issuingOrganization	LocalizedTitle	Yes	—	—
issueDate	YearMonth	Yes	—	—
expirationDate	YearMonth or null	No	—	null = explicitly ‘no expiration’. Omit if unknown/unstated.
credentialId	string	No	1–100 chars	License or certificate number. Public exposure controlled by meta.privacy.hideCredentialIds.
url	Url	No	—	—
order	integer	No	≥ 0	—

Membership

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
organization	LocalizedTitle	Yes	—	—
role	LocalizedTitle	No	—	—
description	LocalizedBody	No	—	—
startDate	YearMonth	Yes	—	—
endDate	YearMonth or null	No	—	null = ongoing. Omit if unknown.
isCurrent	boolean	No	—	—
url	Url	No	—	—
order	integer	No	≥ 0	—

Volunteering

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
organization	LocalizedTitle	Yes	—	—
role	LocalizedTitle	Yes	—	—
cause	LocalizedTitle	No	—	—
description	LocalizedBody	No	—	—
startDate	YearMonth	Yes	—	—
endDate	YearMonth or null	No	—	—
isCurrent	boolean	No	—	—
url	Url	No	—	—
order	integer	No	≥ 0	—

Honor

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
title	LocalizedTitle	Yes	—	—
issuer	LocalizedTitle	Yes	—	—
description	LocalizedBody	No	—	—
date	YearMonth	Yes	—	—
url	Url	No	—	—
order	integer	No	≥ 0	—

Education

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
institution	LocalizedTitle	Yes	—	—
degree	LocalizedTitle	No	—	—
fieldOfStudy	LocalizedTitle	No	—	—
description	LocalizedBody	No	—	—
grade	string	No	1–50 chars	Free-form grade / class / GPA. Public exposure controlled by meta.privacy.hideEducationGrades.
startDate	YearMonth	Yes	—	—
endDate	YearMonth or null	No	—	null = currently enrolled.
isCurrent	boolean	No	—	—
url	Url	No	—	—
order	integer	No	≥ 0	—

Publication

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
title	LocalizedTitle	Yes	—	—
publisher	LocalizedTitle	No	—	—
description	LocalizedBody	No	—	—
date	YearMonth	Yes	—	—
url	Url	No	—	—
doi	string	No	1–200 chars	DOI identifier (e.g. ‘10.1145/3548643.3548644’). The full URL goes in ‘url’.
coAuthors	array of string	No	≤ 50 items; items: 1–100 chars	Co-author names in original script. Excludes the profile owner.
order	integer	No	≥ 0	—

Language

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
language	LocaleTag	Yes	—	—
displayName	LocalizedTitle	No	—	—
proficiency	string	Yes	one of: native, fluent, professional, intermediate, basic	LinkedIn-compatible 5-level proficiency.
order	integer	No	≥ 0	—

Course

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
title	LocalizedTitle	Yes	—	—
provider	LocalizedTitle	No	—	—
courseNumber	string	No	1–50 chars	—
description	LocalizedBody	No	—	—
completionDate	YearMonth	No	—	—
certificateUrl	Url	No	—	—
relatedEducationId	Slug	No	—	Optional reference to an education[].id (e.g. for university coursework).
order	integer	No	≥ 0	—

Patent

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
title	LocalizedTitle	Yes	—	—
patentNumber	string	Yes	1–100 chars	—
office	string	No	≤ 100 chars	Patent office name (e.g. ‘USPTO’, ‘JPO’, ‘EPO’).
status	string	Yes	one of: pending, issued, expired, abandoned	—
description	LocalizedBody	No	—	—
filingDate	YearMonth	No	—	—
grantDate	YearMonth	No	—	—
url	Url	No	—	—
coInventors	array of string	No	≤ 20 items; items: 1–100 chars	—
order	integer	No	≥ 0	—

TestScore

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
title	LocalizedTitle	Yes	—	—
score	string	Yes	1–50 chars	Free-form score string (e.g. ‘112 / 120’, ‘330’, ‘N1 Pass’, or a percentile). The validator does not interpret its contents.
date	YearMonth	Yes	—	—
relatedEducationId	Slug	No	—	Optional reference to an education[].id (e.g. for a university course exam).
description	LocalizedBody	No	—	—
url	Url	No	—	—
order	integer	No	≥ 0	—

Recommendation

Field	Type	Required	Constraints	Description
id	Slug	Yes	—	—
body	LocalizedBody	Yes	—	—
author	RecommendationAuthor	Yes	—	—
relationship	LocalizedTitle	No	—	How the recommender relates to the profile owner (e.g. ‘managed directly’, ‘worked together’).
date	YearMonth	No	—	—
relatedCareerId	Slug	No	—	Optional reference to a careers[].id (the position the recommendation pertains to).
relatedEducationId	Slug	No	—	Optional reference to an education[].id (e.g. a recommendation from a professor).
order	integer	No	≥ 0	—

RecommendationAuthor

Field	Type	Required	Constraints	Description
name	string	Yes	1–100 chars	Recommender’s name, in its original script. Owner-curated; takuhon does not verify it.
headline	LocalizedTitle	No	—	Recommender’s title / role / organization at the time of the recommendation.
url	Url	No	—	Link to the recommender’s profile, for external verification by the reader.