docs: ADR 0001 (Proposed) — field naming & source-standard normalization#1015
Open
bjagg wants to merge 4 commits into
Open
docs: ADR 0001 (Proposed) — field naming & source-standard normalization#1015bjagg wants to merge 4 commits into
bjagg wants to merge 4 commits into
Conversation
…ization Records the conflict between source-standard field names (CEDS et al.), the LIF naming convention, and consumer technology constraints (GraphQL/Python/JSON) — the class of problem behind the iSO639-2LangCode GraphQL crash (LIF-Initiative#1011). Status Proposed: captures context, options, and a recommended decision (normalize on MDR intake + preserve source name as metadata + write-time enforcement, with the LIF-Initiative#1012 codegen sanitization as defense-in-depth) for the team to ratify or revise. Adds the ADR to docs/INDEX.md and drops data_model/ from the template-only note. Refs LIF-Initiative#1014 (ADR + non-tech guide + enforcement), LIF-Initiative#1011/LIF-Initiative#1012, LIF-Initiative#1013. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ing + audit evidence Frame the problem around LIF's two entry points (MDR schema/mapping definitions, which can be guarded; vs. data, which is validated against its assigned schema + sanity checks). Scope this ADR to the MDR entry point and note the data-vs-type conformance sibling concern (LIF-Initiative#1017). Add the audit evidence that the permissive-name problem is not GraphQL-specific: the same illegal name independently threatens GraphQL (LIF-Initiative#1011/LIF-Initiative#1012), semantic-search/MCP (LIF-Initiative#1016), MongoDB ($/. keys), the composer dot-path split, and JSONata — each sanitizing differently or not at all, which is the core argument for validating once at the MDR boundary. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…eclassify JSONata Verified in code: the MongoDB key constraint (build_mongo_update_ops / insert_one by_alias, query_cache_service/core.py:96-110) and the composer dot-path split (composer/core.py:60) both genuinely break on '$'/'.'-bearing field names. Reclassify the JSONata finding: mapping expressions are author-supplied (Transformation.Expression), not auto-generated from names, so it's an authoring hazard, not an automatic code failure — mitigation is validating that a mapping expression compiles at the MDR write boundary, which the Decision now states explicitly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ues LIF-Initiative#1018 (Mongo) & LIF-Initiative#1019 (Composer) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
Author
|
@cbeach47 @thelmick-unicon — this ADR (0001, Proposed) is ready for ratification when you have time. It captures the field-naming / source-standard-normalization decision behind the #1011/#1012 work (normalize at the MDR boundary, keep source name as metadata). No code — just the decision to bless or push back on. |
11 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description of Change
Drafts ADR 0001 (Proposed) under
docs/design/adr/data_model/capturing a conflict that has surfaced repeatedly but was never recorded as a decision: source-standard field names (CEDS et al.) vs. the LIF naming convention vs. consumer technology constraints (GraphQL's/[_A-Za-z][_0-9A-Za-z]*/, Python snake_case, JSON/Mongo verbatim, the translator's case-insensitive lookups).This is the class of problem behind the
iSO639-2LangCodeGraphQL crash (#1011/#1012). The ADR documents the context, the alternatives, and a recommended decision — normalize names on MDR intake to a canonical LIF name, preserve the original source name as provenance metadata ("no loss"), enforce at the MDR write boundary, and keep the #1012 codegen sanitization as defense-in-depth — explicitly marked Proposed for the team to ratify or revise.Also adds the ADR to
docs/INDEX.mdand removesdata_model/from the "template-only placeholders" note.This is a draft for discussion — it should not be merged as
Accepteduntil the team ratifies the decision (the status line says as much). Merging it asProposedto make it visible is also fine; the team can flip the status in a follow-up.Related Issues
Part of #1014 · refs #1011, #1012, #1013
Type of Change
Project Area(s) Affected
Checklist
Additional Notes
Follows the repo ADR template (Status / Context / Decision / Alternatives / Consequences / References). The non-technical naming guide and enforcement/lint pieces from #1014 are intentionally not in this PR — this is just the decision record.
🤖 Generated with Claude Code