Open interoperability layer

Normalized job and fit-scoring contracts

Keep source jobs, table projections, candidate evaluations, and run outcomes separate. The contracts make identity, unknown facts, enrichment, retries, and delivery gates explicit.

Read the complete contract guide ↗Validate records locally

nomad-agent-job-v1: canonical source job

LinkedIn and EURAXESS dataset items have exactly six top-level fields:

schemaVersion, identity, data, custom, llm, raw
  • identity retains source and external identity; derive jobKey = source:externalId for idempotent destinations.
  • data carries normalized cross-source facts.
  • custom carries a separately versioned source extension rather than forcing specialized evidence into generic fields.
  • llm records optional enrichment/translation state and provenance.
  • raw is optional source material and can correctly be null when raw output is disabled.

Unknown is not empty

null means a field is unknown or unavailable. [] means the source established that the list is empty. A populated array contains supported values. Preserve all three states through parsing, serialization, and destination mapping.

Static extraction, facts derived from descriptions, normalized values, optional LLM metadata, and raw source material are different evidence layers. Do not fill a missing requirement, language, contact, or salary because nearby prose makes it seem likely.

nomad-agent-flat-job-v1: table destination

The shared 32-field flat projection supports Sheets, Airtable, CSV, and low-code tools. It serializes arrays and can include a bounded canonical JSON field, but it deliberately omits deep nested detail. It never replaces nomad-agent-job-v1.

Keep canonical records whenever downstream work needs nested requirements, EURAXESS taxonomy, source evidence, named contacts, raw descriptions, or provenance. The flat schema is maintained in GitHub ↗.

nomad-ai-job-fit-v1: candidate-specific evaluation

The scorer consumes canonical jobs but emits a separate closed contract containing candidate hashes, job identity, scoring v3 evidence, gates, raw fit score, delivery score, recommendation, gaps, status, and the complete nested job.

matchKey is the destination upsert key because it incorporates stable candidate facts and scoring family. evaluationKey is the exact content-addressed receipt. Do not run fit rows through the flat-job mapper.

Run summaries gate consumption

LinkedIn and EURAXESS use nomad-agent-run-summary-v4. Its public status, delivered count, warnings, and closed retry object let a caller distinguish completed, clean empty, usable partial, and failed outcomes. Only a valid usable partial summary can recommend one bounded retry.

The scorer uses nomad-ai-job-fit-run-summary-v4 with result mode, threshold, dropped, held, scored, failed, filtered, output, AI-provider, and billing evidence specific to candidate evaluation. Maintained clients accept legacy scorer v3 during migration. Never validate either scorer summary as scraper v4.

Completion rule

A schema-valid row does not prove the intended build ran, the complete dataset was fetched, a price was reconciled, or a destination received data. Consumers must join terminal run state, exact build, same-run summary, complete default dataset, and named-destination evidence at the appropriate layer.

Versioning policy

  • Select latest in automation and record the build used to produce data.
  • Treat a new schema version as a new contract, not a silent field mutation.
  • Preserve source-specific semantics when creating common projections.
  • Update validators, examples, workflows, and documentation together.
  • Validate each run against the supported schema and test destination changes before enabling them.