Schema stability

The takuhon.json schema is the contract every Takuhon surface depends on — the profile page, the JSON API, JSON-LD, the MCP endpoint, and the exported CV all read from it. As of 1.0.0 that contract is frozen: a document that validates today keeps validating, and the meaning of every field is fixed.

1. What “frozen” guarantees

Takuhon follows semantic versioning for the schema, and the schemaVersion inside each document records the version it conforms to:

Change	Version bump	Example
Remove a field, change its type, promote an optional field to required, or narrow what a field accepts	major	dropping recommendations; requiring careers
Add an optional field, loosen a constraint, add an enum value, open an extension path	minor	a new optional pronouns field
Wording, docs, non-normative fixes	patch	—

In short: anything that could invalidate a document that is valid today is a major release. You can move across minor and patch releases without touching your takuhon.json.

2. Closed by default

Since 1.0.0 every object in the schema is closed (additionalProperties: false): a key the schema does not define is a validation error, not silently ignored.

{
  "profile": {
    "tittle": "Engineer"   // ❌ misspelled "title" — rejected, not dropped
  }
}

Before 1.0.0 unknown keys were quietly dropped, which could hide a typo and lose data. Closing the schema means a typo fails loudly, and every byte that reaches JSON-LD and the MCP endpoint is schema-defined. The only open maps are the locale-keyed strings ({ "en": "...", "ja": "..." }), which accept any BCP-47 language tag by design.

3. Other 1.0.0 invariants

• Non-empty localized text. A localized value must contain at least one non-whitespace character — a whitespace-only string is rejected instead of resolving to empty.
• Unique ids per array. Each entry’s id must be unique within its array; the reference fields (relatedCareerId, relatedEducationId) rely on it.
• Stable ordering. Items sort by ascending order; missing or equal values keep their original array position.
• Minimal required fields. Only schemaVersion, profile, contact, settings, and meta are required. Every content array — links, careers, projects, skills, and the rest — is optional; an absent array is treated as empty, so a profile with no formal career no longer needs an empty list.

4. Extensions

Custom keys are not allowed in 1.0.0. A reserved x- prefix is planned as a future, non-breaking way to attach your own data without forking the schema; until that ships in a minor release, an x--prefixed key is rejected like any other unknown key.

5. Upgrading from 0.x

A 0.x document that already avoids unknown keys is a valid 1.0.0 document with no structural change — the 1.0.0 freeze tightened the rules but did not move any fields. To stamp the version and confirm conformance:

takuhon migrate ./takuhon.json   # forward-migrates to 1.0.0 (a version stamp)
takuhon validate ./takuhon.json  # confirms it conforms to the frozen schema

If validate reports an unknown key, it is almost always a typo or a field that was removed before 1.0.0 — fix or drop it. See the schema reference for every defined field.