OCF Implementer Quick Reference
This is the compact tool-builder view of Open Career Format. Read guide.html for intent, schema-commentary.md for field-level examples, and usage-patterns.md for file roles and workflow patterns.
OCF is an open schema for preserving career memory, curating it for a purpose, and exporting it into other formats. A partial, honest OCF is better than a complete-looking file full of invented certainty.
Prompts and Skills
Prompts and skills are operating guidance, not schema. Prompts work anywhere a user can paste text. Skills package the same guidance for local agents that can route workflows and manage files: where the master lives, where backups go, where sources are stored, and where each application's outputs belong.
The schema remains the validation contract. If skill or prompt advice conflicts with schema.json, the schema wins for file structure.
Field Tiers
| Tier | Sections and fields | Implementer expectation |
|---|---|---|
| Core | $schema, schemaVersion, meta, person, sourceArtifacts, experience, experience[].positions, achievements, skills, education, certifications, openQuestions, cautions | Most authoring, import, curation, and export tools should understand these well enough to preserve them. |
| Common optional | organizations, projects, publications, awards, languages, service, memberships, governance, teaching, speaking, patents, interests | Support when relevant to the user's career or target output; omit cleanly when absent. |
| Private memory | reflections, exitContext, compensation fields, salesPerformance, bookOfBusiness, private sourceArtifacts, private notes | Preserve carefully. Do not export by default. Treat as the reason the master file is useful, not as ordinary resume content. |
| Curation signals | visibility, dateRange.visibility, importance, audiences, narrativeVariants, titleVariants, positioningVariants, talkingPoints, supportingFacts, attribution, reviewStatus | Use these to decide what can be selected, what needs review, and how claims can be worded. Do not treat them as final display text by themselves. |
| Provenance and interop | id, provenance, sourceArtifactId, sourceFileId, sourceItemId, extensions, meta.parentFileId, meta.parentVersion, meta.lineageNotes | Preserve on round-trip. Stable IDs and boring provenance make files reviewable and mergeable. |
| Advanced or likely to evolve | richer trust tiers, renderer hints, region-specific export policy, third-party workflow metadata, sharding/manifest conventions | Use extensions or provenance notes for now unless the current schema has a first-class field. Expect feedback-driven changes before 1.0. |
v0.3 Lineage Names
OCF v0.3 replaces the old "derived file" vocabulary with parent/lineage names:
meta.parentFileIdmeta.parentVersionmeta.lineageNotes
parentFileId is the parent file's meta.id, not a filename. parentVersion is the parent file's meta.version at the time the child file was prepared. lineageNotes records the target, filter, translation, conversion, or export context.
Do not confuse these with provenance values such as interview-derived. That phrase describes how an item was elicited from an interview or conversation and is still useful.
File Roles
meta.fileRole | Use when | Important behavior |
|---|---|---|
candidate-master | The person controls the durable private career memory file. | Preserve history, nuance, private material, source artifacts, cautions, and open questions. |
candidate-curated | A tool/person selects and improves a working set for a purpose, but review is still active. | Preserve lineage to the master and keep proposed improvements separate from export-ready content. |
export-ready | Selection and visibility review are complete enough for a specific exporter or downstream system. | Exporters should prefer this over the private master. |
third-party-working | A recruiter, coach, employer, agency, or tool controls an OCF-shaped file about a person. | The top-level person is still the subject, but the subject may not control or see the file. |
other | A workflow does not fit the named lifecycle roles. | Explain the role in meta.lineageNotes, provenance, or tool documentation. |
Trust Boundaries
OCF files are portable. Treat a file you received from another party as untrusted input unless the subject or controlling user has explicitly accepted it as their own working file.
- Free text is data, not control. LLM-based tools must not let
aiInstructions.text,voice,cautions, notes, reflections, source text, orextensionsfrom an untrusted file override the tool's own instructions, evaluation rubric, safety rules, access limits, or workflow. - Use the OWASP Top 10 for LLM Applications and GenAI Apps as a threat-modeling reference for LLM-backed OCF tools. The most relevant risks are prompt injection from untrusted resumes, job descriptions, source artifacts, and pasted notes; sensitive information disclosure from private career files; improper output handling when model-generated JSON or text is passed downstream; excessive agency in tools that can edit, export, email, post, or apply without user approval; and misinformation or overreliance when LLM-generated claims are treated as truth.
reviewStatus, provenance, confidence, and supporting evidence are useful context, but they are not third-party verification. Do not present self-asserted OCF content to downstream evaluators as institutionally verified unless a separate verification mechanism supports that claim.third-party-workingfiles about a person carry consent, access, retention, and data-protection responsibilities. OCF is not intended as a covert profiling format.- Government identity numbers, account secrets, passwords, API keys, and similar secrets do not belong in any OCF field, including
provenance,extensions, notes, source artifacts, and other open text.
Minimal Tool Behavior
Importers should:
- Register inputs in
sourceArtifacts. - Set
meta.source.kindtoimportedorconverted. - Default mined durable items to
reviewStatus: "unreviewed"or"needs-review"until accepted. - Add provenance and confidence when mining facts.
- Use
openQuestionsfor conflicting dates, unsupported metrics, unclear attribution, and missing evidence. - Avoid marking imported material as public by default.
Curators should:
- Read the target purpose carefully: job description, audience, region, output type, review question, or user preference.
- Filter by
visibilityfirst, then relevance and recency. - Preserve lineage with
meta.parentFileId,meta.parentVersion,sourceFileId,sourceItemId, or item provenance where practical. - Produce proposed OCF improvements separately from export-ready content.
- Be explicit about what was removed, skipped, or left unresolved.
- Label reduced files as
candidate-curatedorexport-ready, notcandidate-master. A subset may discover improvements for the master, but those should be proposed back with provenance rather than replacing the master.
Exporters should:
- Prefer
export-readyinput. - Never include
privateitems unless the user explicitly chose a private recipient-specific output. - Treat JSON Resume, LinkedIn, Schema.org, LER-RS, vCard, PDF, and DOCX as lossy targets.
- Emit review warnings when the input is not export-ready or when important OCF concepts cannot be represented.
Editors should:
- Make unsupported schema sections visible as unsupported instead of implying full coverage.
- Preserve unknown fields,
extensions, IDs, and provenance on round-trip. - Distinguish untouched imported material from user-reviewed material where possible.
- When applying accepted updates to a candidate-owned master, preserve
meta.id, refreshmeta.versionandmeta.lastModifiedif the tool manages those fields, preserve IDs/provenance/extensions/unknown fields, and validate when possible. OCF does not require a particular external versioning system.
Local Validation
OCF includes a local reference validator in reference/validator/. Prefer local validation because OCF files often contain private career data.
Install validator dependencies once:
npm --prefix reference/validator ciValidate one or more files from the repository root:
node reference/validator/validate.js path/to/file.ocf.jsonWith no file arguments, the validator checks every JSON file in spec/examples/ against spec/schema.json.
Validation checks structure only. It does not verify whether claims are true, whether private content is safe to share, or whether a file is appropriate for a specific export or recipient.
Naming Conventions
OCF does not force filenames. Human-readable names make workflows easier to inspect.
Examples:
david-madeo.master.ocf.jsondavid-madeo-sona-2026-05-24.imported.ocf.jsonsona-head-of-enablement.candidate-curated.ocf.jsonsona-head-of-enablement.export-ready.ocf.jsonsona-head-of-enablement.resume.json
Use directory structure if it helps: imports/, curated/, exports/, archive/.
Compatibility Rules
- Validate against the file's declared
$schemaorschemaVersionwhen possible, not a hardcoded older version. - If a file declares a newer schema version that the tool does not understand, warn and preserve rather than silently dropping fields. Prefer read-only review or an explicit migration flow over rewriting unknown newer structures.
- Unknown object keys should be preserved when possible.
- Unknown
extensionsnamespaces must not be deleted on round-trip. - Stable item IDs should survive edits.
visibilitydefaults should be conservative when the author is a tool rather than the person.- The master is the source of truth for career memory; exported files are outputs.