Repository navigation
862: clarify/normalise "variable reference ('${name}')" error messages - #873
Merged
Merged
Conversation
- consistently use "variable reference ('${name}')" to clarify what
feature these errors are about.
- the variable reference feature resolves any name from the survey
sheet to XPath, including questions/fields or repeat/display groups,
so the terms 'question name', 'field name' are avoided.
- survey 'name' column values are sometimes referred to as 'variables'
and these tokens are "references to variables", but the term
"reference variables" could imply a special type of variable, so
the term "variable reference" is used. The ODK docs refer to this
feature as just "Variables" and so "variable references" separates
this syntax from a survey 'name' column value.
- docs also refer to this feature as '${} notation' but that seemed
like it may be confused with a token substitution error or something
technical; however to further disambiguate the above point, the
example string `('${name}')` is appended to show the syntax and
highlight that the value inside the braces must be a name.
- add include a "Learn more" link to the docs where relevant.
- add error message guideline in ErrorCode docstring.
lindsay-stevens
changed the title
lognaturel
approved these changes
Oct 2, 2026
4 tasks done
4 tasks done
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
2 participants
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.
Closes #862
Related to #634
Why is this the best possible solution? Were any other approaches considered?
The errors and terminology for this feature are a bit nebulous so I've tried to normalise them all in one go. There is existing test coverage for the errors that use these messages (the tests purposely don't rely on the exact message wording) so no tests are changed. Further details are in the commit message.
What are the regression risks?
Downstream tools expecting the old messages would need to be updated to the new messages. It might help to include the error message identifier at some stage but currently they aren't stable enough for that.
Does this change require updates to documentation? If so, please file an issue here and include the link below.
Maybe - on xlsform.org this feature isn't given a name or explicitly documented, it's just used as part of other sections.
Before submitting this PR, please make sure you have:
testspython -m unittestand verified all tests passruff format pyxform testsandruff check pyxform teststo lint code