psywerx-interactives

PSYWERX Codebook Schema v1.0

Codebook Schema v1.0 defines the canonical public representation of the identical Codebook worksheets embedded in the eight standardized PSYWERX Driver Ontology workbooks. It documents technical ontology fields, controlled vocabularies, and governance rules without changing Driver Schema v1.1 or Family Schema v1.0.

The public artifact uses this envelope:

{
  "schemaVersion": "1.0",
  "metadata": {},
  "entries": []
}

Worksheet structure

The canonical source worksheet distinguishes structural documentation from semantic Codebook terms:

The three populated structural rows are the Codebook title in row 1, the governance instruction in row 2, and the column headers in row 4. Row 3 is blank. Rows 5-60 contain the 56 semantic term records. Structural and blank rows never receive Codebook Term IDs and never become entries. The final eight semantic rows govern Relationship Schema v2 controlled fields.

The title and governance instruction are preserved as public metadata along with the three diagnostic counts.

Canonical entry fields

Canonical field Spreadsheet header JSON type Requirement Technical meaning Normalization
id Codebook Term ID string Required Permanent global identity of one semantic Codebook term. Preserve exactly. Require a URL-safe CB- identifier using the governed domain prefix. Never derive from row number.
sheet Sheet string Required Source worksheet/entity classification governed by the term. Preserve source classification after trimming surrounding whitespace.
field Field string Required Source field or governed concept name. Preserve source wording after trimming surrounding whitespace.
definition Definition string Required Source technical definition. Preserve source wording after trimming surrounding whitespace.
allowedValuesOrFormat Allowed Values / Format string Required Original allowed-value vocabulary or technical format statement. Preserve the complete source text after trimming surrounding whitespace.
allowedValues Derived from Allowed Values / Format array of strings Required output key Structured values when the source row defines a safely separable controlled vocabulary. Split source-supported semicolon-delimited vocabularies. Exclude a temporal format directive from the value array without removing it from allowedValuesOrFormat. Use [] when the row is narrative or format-only.
required Required boolean Required Whether the source field is required. Convert exact source Yes to true and No to false; reject other values.
guidance Rule / Guidance string Required Source governance or implementation guidance. Preserve source wording after trimming surrounding whitespace.
source Generated by importer object Required Public provenance for the canonical Codebook row. Include only worksheet name and one-based row number. Never expose a workbook path.

Every entry contains every canonical JSON key. An entry without a parsed controlled vocabulary uses an empty allowedValues array.

Metadata fields

Field JSON type Meaning
title string Exact Codebook title preserved from structural row 1.
governanceInstruction string Exact cross-workbook governance instruction preserved from structural row 2.
worksheetPopulatedRows integer Count of nonblank worksheet rows, including structural rows.
structuralRows integer Count of populated title, instruction, and header rows.
termRecords integer Count of semantic Codebook entries carrying permanent IDs.

Source Sheet classifications

The sheet field preserves one of the source classifications:

These values are classifications from the source Codebook. Public consumers must not replace them with an unrelated category system.

Permanent Codebook Term IDs

Schema v1.0 has 56 explicit, globally unique IDs. IDs are permanent, identical across all eight workbook copies, and suitable for future URLs such as ?term=CB-DRV-MODIFIABILITY.

The governed prefixes are:

IDs are semantic identities, not row-derived slugs. Moving a term to another row does not authorize changing its ID.

Controlled-vocabulary representation

allowedValues is populated only when the source text defines a controlled list that can be split without interpretation. Schema v1.0 structures the source-supported vocabularies for Driver Layer, Data Type, Modifiability, Volatility, Time Scale of Change, Onset / Causal Lag, Observability, Driver and supporting Evidence Strength, Relationship Expected Direction, Relationship Causal Role, Polarity, Directness, Level, Lag Profile, Exposure Pattern, Confidence, and Governance Class, Operationalization Method Type, and Cautions & Exclusions Disposition.

For Time Scale of Change and Onset / Causal Lag, the phrase semicolon-separated canonical combinations remains in allowedValuesOrFormat as source wording but is not itself an allowed value.

The importer validates current data/drivers.json values against the Driver controlled vocabularies. It also enforces temporal array type, uniqueness, canonical order, and exclusive-value rules from Driver Schema v1.1. Allowed-but-unused values are valid diagnostics, not warnings or errors. Used-but-undefined controlled values are errors.

Validation and output safety

The importer requires eight workbooks and one Codebook worksheet in each. It requires exact headers, 59 populated worksheet rows, three structural rows, 56 semantic records, populated URL-safe IDs, unique IDs, identical content across all eight copies, canonical source classifications, and valid required flags.

The importer selects a canonical copy only after equality validation, builds the complete payload in memory, checks that public provenance contains no local filesystem path, and atomically replaces data/codebook.json only when no errors occur. Output is UTF-8, pretty-printed, and deterministic.