Reference letters. Clear. Fair. Compliant.
Schema · Kompass StandardTechnical specificationPublished April 2026
Schema · Kompass Standard

Kompass schema data structure of the standard

The formal data structure behind the Kompass Standard — JSON schema, field names, value ranges, validation rules. For HR IT, integrations and partners building on Kompass data.

Register now Standard overview
  • JSON schema
  • Machine-readable & validatable
  • Versioned (v1.0)
PDF · Technical specification

Kompass schema — full specification

The complete data structure as PDF: all fields, all value ranges, all validation rules. Includes example JSON, versioning notes and migration paths. Free, no registration.

Download schema PDF
Why structured data matters alongside the prose.

01 — Why a formal schema?

  • Machine readability — third-party systems can parse Kompass references directly instead of interpreting prose
  • Comparability — same fields for every reference, comparable scales across companies and industries
  • Validation — automatic check for completeness and consistency before issuance
  • Tamper protection — schema + SHA-256 fingerprint allow undistorted reconstruction
Top-level fields of a Kompass reference letter.

02 — Root object

  • schemaVersion (string) — e.g. "kompass/1.0"
  • issuedAt (date) — issuance date, ISO 8601
  • subject (object) — personal data of the assessed individual
  • company (object) — master data of the issuing company
  • assessment (object) — the five performance areas, narrative texts, closing
Who is being assessed, who issues the letter.

03 — subject and company

  • subject.firstName, lastName (string, required)
  • subject.birthDate (date, optional)
  • subject.position (string) — role or job title
  • subject.employmentStart, employmentEnd (date) — employment period
  • company.name, address, uid, city (string)
The five performance areas, each with status and evidence sentence.

04 — assessment block

  • fields (array) — five entries: aufgabenbewaeltigung, selbststeuerung, zusammenarbeit, entwicklung, wirkung
  • fields[i].status (enum) — "anforderungen-erfuellt", "anforderungen-oft-uebertroffen", "anforderungen-deutlich-uebertroffen", "nicht-anwendbar"
  • fields[i].evidenz (string, max 240 chars) — observable evidence sentence
  • narrative (object) — tasks, contributions, competence evidence, working style as written prose
  • schluss (object) — reason for departure, thanks, future wishes
What the schema engine checks before issuance.

05 — Validation rules

  • Required fields present (subject.firstName/lastName/position, company.name, assessment.fields)
  • Exactly five fields entries with the defined keys
  • Status from the fixed enum, no free-text values
  • Date fields in ISO 8601 format, employmentEnd ≥ employmentStart
How new schema versions are introduced.

06 — Versioning & compatibility

  • Semantic versioning (Major.Minor) — schemaVersion always in the root object
  • Minor updates are backwards-compatible (additional optional fields)
  • Major updates come with a migration path and a 12-month transition period
  • Validators detect the version themselves and apply the matching rule set
Continue reading

In-depth pages

FAQ

Frequent questions

Is the schema open?
Yes. The schema is openly documented and can be used by any vendor, HR system or integrator. The PDF specification above contains all fields, value ranges and validation rules. A machine-readable JSON Schema file is available on request.
How does the schema relate to the PDF output?
The schema is the source of data, the PDF is the rendering. From a schema-conformant JSON, ZeugnisPilot (or a third-party system) can deterministically render the print-ready PDF. The content fingerprint (SHA-256) is computed over the normalised JSON — so tampering remains detectable even after PDF print.
Can I use the schema in my own HR system?
Yes. If your system needs to create or import Kompass references, it only needs to comply with the schema. Validators and example JSONs ease the entry. We recommend starting with schema version 1.0 and using the transition period for major updates.
What happens on validation error?
The validator returns a structured error list (field path, rule, found value, expected values). The reference cannot be issued until all errors are resolved — protecting against incomplete or inconsistent data.
Where can I find the full schema as PDF?
Right here: the schema specification is available at the top of this page as a PDF download (free, no registration). It contains the root object, all sub-objects, value ranges, example JSON and validation rules.

Apply Kompass directly in the generator

The generator writes Kompass references schema-conformant by default — you can focus on the content instead of JSON fields.

Register nowOpen generator