psywerx-interactives

PSYWERX Family Schema v1.0

Family Schema v1.0 defines the canonical public representation of the Families worksheets embedded in the eight standardized PSYWERX Driver Ontology workbooks. It is a supporting ontology schema and does not modify Driver Schema v1.1.

The public artifact uses this envelope:

{
  "schemaVersion": "1.0",
  "families": []
}

Canonical fields

Canonical field	Spreadsheet header	JSON type	Requirement	Technical meaning	Normalization or derivation
id	Family ID	string	Required	Permanent Family identifier, globally unique across the PSYWERX Driver Ontology and suitable as a stable foreign key.	Preserve the explicit source value exactly. Never regenerate, rename, reuse, or reassign it.
name	Family Name	string	Required	Canonical Family display name.	Trim and collapse whitespace. Family names must be globally unique.
layer	Layer	canonical layer string	Required	Layer containing the Family.	Require an exact canonical layer value and validate it against the canonical workbook filename.
definition	Definition	string	Required	Technical description of the variable class grouped by the Family.	Trim and collapse whitespace.
includes	Inclusion Rule	string	Required	Rule describing what belongs in the Family.	Trim and collapse whitespace.
exclusions	Exclusion / Boundary Rule	string	Required	Rule describing what does not belong in the Family or how neighboring domains are separated.	Trim and collapse whitespace.
representativeDrivers	Representative Drivers	array of strings	Optional	Source-provided illustrative canonical Driver names.	Split on semicolons and preserve source order and names. Every name must resolve uniquely to a Driver in this Family.
representativeDriverIds	Derived linkage	array of strings	Derived	Stable Driver IDs corresponding positionally to representativeDrivers.	Resolve each source name to exactly one canonical Driver and preserve source order. This augments rather than replaces the source names.
driverCount	Driver Count	integer	Required validation field	Declared number of canonical Drivers assigned to the Family.	Parse as a non-negative integer and require equality with the authoritative count derived from data/drivers.json. Never silently correct a mismatch.
source	Generated by importer	object	Required	Public provenance for the source Family row.	Include only workbook filename, worksheet name, and one-based row number. Never expose a local filesystem path.

Canonical layers

• Biological
• Psychological
• Social
• Cultural
• Physical / Environmental
• Institutional / Structural
• Informational
• Technological

Identity and relationship rules

• Family IDs are explicit, permanent, and globally unique across all layers.
• Family names are globally unique in Schema v1.0.
• Each (layer, Family name) pair must identify exactly one Family.
• Every Driver’s exact layer and family values must resolve to exactly one Family.
• Every Family must contain at least one canonical Driver.
• The Driver family field remains the canonical display-name relationship. Family Schema v1.0 does not add familyId to Driver Schema v1.1.

Driver Count governance

The authoritative Driver Count is derived from the canonical Driver records in data/drivers.json. The workbook’s Driver Count is a required assertion that must equal that derived value. A mismatch is an import error; the importer does not repair or overwrite the source value.

Representative Driver linkage

representativeDrivers preserves the canonical Driver names written in the workbook. representativeDriverIds is a derived stable linkage for public consumers. For each representative name, the importer requires:

1. exactly one matching canonical Driver name;
2. the same canonical layer as the Family; and
3. the same canonical Family name.

Unresolved, ambiguous, duplicate, or wrong-Family references are errors.

Validation and output safety

The importer validates exact worksheet headers, canonical layers, required values, globally unique IDs and names, unique layer/name pairs, complete Driver-to-Family coverage, representative links, declared counts, and public provenance. It builds and validates the entire dataset in memory and atomically replaces data/families.json only when no errors occur.

Families are sorted deterministically by canonical layer order, normalized Family name, and permanent Family ID. JSON is UTF-8 and pretty-printed.