Clarify rules about custom property names - #2095
Conversation
matthew-white
left a comment
matthew-white
left a comment
There was a problem hiding this comment.
Questions and comments about these user docs
| Custom Properties let you control which Entities each App User or Public Link receives. For example, if your organization works across multiple regions, you can create a ``region`` Custom Property, assign each App User a region, and configure an :ref:`Entity List access filter <entity-list-access-filter>` so each user receives only Entities from their region. | ||
|
|
||
| Go to the :guilabel:`Custom Properties` tab for a project to see the available Custom Properties and add new ones. Custom Property names follow the same rules as form field names or Entity property names: they can't have spaces in them, must start with a letter, and can only contain letters, numbers, _ or -. | ||
| Go to the :guilabel:`Custom Properties` tab for a project to see the available Custom Properties and add new ones. Custom Property names follow the same rules as form field names or Entity property names: they can't have spaces in them, must start with a letter or underscore, and can only contain letters, numbers, and a limited set of symbols (``_``, ``-``, and ``.``). |
There was a problem hiding this comment.
Here, "letter" isn't restricted to English A-Z. It includes letters with diacritical marks, Chinese characters, etc. So users may still think that the validation is stricter than it actually is.
There was a problem hiding this comment.
I think that's ok. It's another one of those things where accented characters are allowed for overall consistency across identifier names but I would absolutely not recommend them.
| Custom Properties let you control which Entities each App User or Public Link receives. For example, if your organization works across multiple regions, you can create a ``region`` Custom Property, assign each App User a region, and configure an :ref:`Entity List access filter <entity-list-access-filter>` so each user receives only Entities from their region. | ||
|
|
||
| Go to the :guilabel:`Custom Properties` tab for a project to see the available Custom Properties and add new ones. Custom Property names follow the same rules as form field names or Entity property names: they can't have spaces in them, must start with a letter, and can only contain letters, numbers, _ or -. | ||
| Go to the :guilabel:`Custom Properties` tab for a project to see the available Custom Properties and add new ones. Custom Property names follow the same rules as form field names or Entity property names: they can't have spaces in them, must start with a letter or underscore, and can only contain letters, numbers, and a limited set of symbols (``_``, ``-``, and ``.``). |
There was a problem hiding this comment.
Should we mention that two leading underscores aren't allowed? How about reserved property names — label, name, displayName?
There was a problem hiding this comment.
What is displayName? 😬
I don't feel strongly about it. I think it's unlikely enough that folks will come up with these names themselves that the errors from Central can stand on their own for those who do.
There was a problem hiding this comment.
displayName does seem pretty unlikely. Same for two leading underscores hopefully. name doesn't seem terribly unlikely to me though.
the errors from Central can stand on their own
One thing on my mind is that the errors in Central aren't super specific. E.g., Backend just says, "This is not a valid property name." It doesn't say, "name is reserved as a system property." I'm sure the user will figure it out, but I don't think it's necessarily obvious why a name like name would be a problem.
| Custom Properties let you control which Entities each App User or Public Link receives. For example, if your organization works across multiple regions, you can create a ``region`` Custom Property, assign each App User a region, and configure an :ref:`Entity List access filter <entity-list-access-filter>` so each user receives only Entities from their region. | ||
|
|
||
| Go to the :guilabel:`Custom Properties` tab for a project to see the available Custom Properties and add new ones. Custom Property names follow the same rules as form field names or Entity property names: they can't have spaces in them, must start with a letter, and can only contain letters, numbers, _ or -. | ||
| Go to the :guilabel:`Custom Properties` tab for a project to see the available Custom Properties and add new ones. Custom Property names follow the same rules as form field names or Entity property names: they can't have spaces in them, must start with a letter or underscore, and can only contain letters, numbers, and a limited set of symbols (``_``, ``-``, and ``.``). |
There was a problem hiding this comment.
Code references:
|
I'm wondering where these rules came from in the first place, because they are stricter than the dataset property names, but I didn't happen to implement them in the backend. Should Central be doing more to check properties like this? |
|
@lognaturel, I had been thinking after the meeting last week that I should close this PR. I just hadn't gotten around to it yet. Or is that wrong and I should go ahead and merge? I'm happy for us not to be more explicit than the current docs if that helps users avoid awkward cases. Also happy to merge though. |
We discussed in the team meeting last Thursday the user docs intentionally document stricter rules than what's technically allowed, so that we don't lead users to choosing names that would be inconvenient in certain settings. I'm not seeing a case where Backend needs to be doing more validation than it currently is. |
|
Just to link issues, I've also filed getodk/central#2182 about making it clear in Central Frontend what makes a property name valid or not. Probably we'll want the rules/explanation in Central to match what we document here. Or maybe we link from Central to the user docs. |
3 participants
Creating a PR based on getodk/central#1875 (comment)
The rules in the user docs about custom property names are stricter than what Central enforces. In the issue linked to above, there was confusion because a leading underscore actually is allowed. For property names, two leading underscores are disallowed, but one is accepted.
I'll leave a few line comments as well with thoughts about these rules and whether they could be further clarified.