docs: Document import key matching and per-field override semantics

[cristidrg]

Description

Refreshes all six schema files from the monorepo generator (yarn workspace @theydo/external-format refresh).

Substantive change — only one:

• InsightsFile.schema.json: adds the personas field (array of persona share URLs …/p/<shareKey>, nullable). Personas that do not exist in the target workspace are ignored — imports never create personas.

Everything else is generator churn, verified semantically equivalent:

• SurveyResponsesFile / FeedbackResponsesFile: $ref/$defs indirection inlined; resolved schemas are byte-identical to the old ones.
• MetricsFile, OpportunitiesFile, SolutionsFile: key ordering/formatting only — zero semantic changes.

---

Documents the per-field update semantics for the JSON entity imports (THEYDO_INSIGHTS_V1, THEYDO_OPPORTUNITIES_V1, THEYDO_SOLUTIONS_V1), shipped in theydo/theydo#26312:

• Import Key and Overrides — records are matched by importKey (unknown creates, known updates), plus the omit / null / value table: an omitted key preserves existing data, null clears, a value sets (lists replace membership exactly).
• Fields with special matching behavior — ownerEmail and personas are matched against existing users/personas and never created; status/type and tags/tag groups are created when missing; tags+groupTags form one merged set; out-of-range empathyScore is ignored.
• Notes that these semantics are specific to JSON (a CSV import cannot express an omitted field) and cross-references the survey/feedback persona matching, which is a different mechanism but likewise never creates personas.
• Replaces the old "Treatment of ownerEmail property" subsection, now covered by the generic rule plus the ownerEmail row.

🤖 Generated with Claude Code

[drye]

Thanks for writing this up, Cristian. I checked it against the import behavior we just merged, and the omit / null / value table is right. Same for the special cases: unknown ownerEmail does not wipe the current owner, a persona list that matches nothing is left alone, tags and groupTags are one merged set, out of range empathyScore is ignored, and CSV cannot omit a field.

I hope I'm not getting this wrong, but this README now tells people they can send personas on insights, but schemas/InsightsFile.schema.json still does not declare that field, and extra keys are rejected. s3tcli test-format will fail a file that follows this doc. Ingest already accepts personas (array of share URLs, or null). Could you add that field to the insights schema here so the docs and the validator agree?

Smaller thing: the schema files still say to read "Treatment of ownerEmail", which this PR removes. Updating those descriptions to the new section name would keep the pointer working.

[drye]

This matches ingest. schemas/InsightsFile.schema.json does not declare personas though, and extra keys are rejected, so s3tcli test-format will fail a file that follows this row. Can we add the field here (array of share URL strings, or null) so the schema matches the docs?

[cristidrg]

Yes you are right, I noticed this repo is out of sync as well with master in regards to personas (and probably other things?). Was chatting with Andres about it