Usability issues with Django form fields expecting specific patterns

[Thibaud Colas]

Related: #32338, #32339.

• Test form I’m basing this report on: ​http://django-admin-tests.herokuapp.com/forms/example_form/p/
• Form fields definitions: ​https://github.com/thibaudcolas/django_admin_tests/blob/main/django_admin_tests/forms.py
• Template: ​https://github.com/thibaudcolas/django_admin_tests/blob/main/django_admin_tests/templates/django_admin_tests/example_form.html

Django offers a lot of fields that expect specific formats:

• Date and time fields – DateField, DatetimeField, TimeField, SplitDateTimeField, DurationField
• More technical fields which have very specific formats: SlugField, JSONField, UUIDField, RegexField, GenericIPAddressField

The default widget markup for all of those fields never displays the expected format. For some fields this can somewhat be addressed via the field’s label or help text (for example having "JSON" in the label, or a description of a regex pattern in help text). But not for all. This is particularly problematic for date and time fields:

• Even though end users know about date formats, just saying a field expects a "Date" is never enough to know which specific format is expected.
• Django supports providing supported formats globally via settings, and at the field level. Ideally the widget would display the format(s) it’s accepting based on this configuration, rather than having to hard-code it in help text, which is prone to being incorrect / falling out of date / not being set.
• The default error messages for invalid formats are vague ("Enter a valid date.", "Enter a valid date/time.", "Enter a valid duration.").

I don’t think this is something that can necessarily be solved for all cases directly in Django, but thought it would be worth raising nonetheless. As-is, having default templates for those widgets makes it easy for developers to overlook the need for this guidance. And we end up with forms that are impossible to fill.

Solutions I can think of are:

• Update documentation to at least express the need for communicating the expected format to end users. Ideally have examples of communicating those formats for specific field types.
• Find a way to auto-display the format alongside the help text for the field.
• Update the error messages to actually display the expected formats, rather than a basic "Enter a valid <field type>".

I hope this makes sense, even though again this isn’t as clear-cut as the other forms issues I noticed.

[Carlton Gibson]

Hi Thibaud.

Initially let's accept this as a Documentation issue. Certainly we can do that right? 😀

Very happy to consider specific changes that you come up with here too!

Without some idea of what we might do though, it's a bit needsinfo — maybe targeted changes for single fields to begin...?
A proof-of-concept here would help push it forward.

Thanks! 👍

[Thibaud Colas]

Thank you, I think I’ll start with getting more familiar with the documentation so I can figure out where best to address this. And as I do I’ll likely have to come up with code snippets that might inform further changes.

I think it would also be good to get feedback from others here – on the specific issues outlined here, and perhaps also more generally on how much it’s Django’s role to make sure it’s not too easy to misuse.

[Thibaud Colas]

I have discussed this again with a coworker, and we think that as an immediate action it would be best to have "accessibility considerations" as a standalone page in the forms / fields documentation, or cover it separately for each field, as preferred.

For the issues listed here, this would allow us to:

• Recommend using help_text (or template overrides?) to display the expected date format, with practical copy-paste-able examples
• At the same time we could briefly mention why this is better than alternatives (having the format in error messages or as a placeholder attribute – both better than nothing but poor in comparison).

Additionally, in the future, we could also cover common considerations for other field types:

• How it’s rarely appropriate to use type="number" even if the field might be storable as a number (see ​https://technology.blog.gov.uk/2020/02/24/why-the-gov-uk-design-system-team-changed-the-input-type-for-numbers/).
• How a type=”date” input should be favoured if browser support for a given project allows it

And broader considerations that are relevant for all field types:

• Usage of fieldsets
• Usage of autocomplete / autocapitalize attributes
• Visually distinguishing between optional and required fields

---

This goes beyond what I reported here initially, and I’d still personally prefer something that could be done in Django core directly, but thought it would be worth mentioning nonetheless.

[Carlton Gibson]

HI Thibauld.

I think a small section in the docs would be great. We don't want to write a whole guide, but showing some basics and (if there are canonical resources) pointing on to more would likely be in scope.

I think we can get some changes here into core too... :)

[Surya]

Hi Thibauld and Tom,

I am a new contributor and after looking into issue tracker, I see this as a ticket that I would love to work on if nobody else is working on it.

In case I get to work on this, I had a couple of questions regarding what needs to be done. Carlton asked me to ask my question here, so here it goes.

1. For the suggestion of having explicit instructions on the Django documentation about the format of the form fields, as described in the ticket, should I focus on mentioning the default formats for the following fields -

Date and time fields – DateField, DatetimeField, TimeField, SplitDateTimeField, DurationField
More technical fields which have very specific formats: SlugField, JSONField, UUIDField, RegexField, GenericIPAddressField

2. Should the changes in the documentation extend to issues such as #32339 or #32338 on why it should be avoided?

Please forgive me if I have not been able to understand the ticket responsibility the way it is intended, and I would be very grateful if the scope of the changes required could be pointed out to me by any senior member of the community.

Thanks,
Surya

[Thibaud Colas]

See PR [Accessibility guidelines for all contributors #17338 ​https://github.com/django/django/pull/17338] for the next step on adding accessibility docs in Django. After this, I believe [Add guidelines for accessibility in documentation #17340 ​https://github.com/django/django/pull/17340] will be a good step in adding accessibility considerations in documentation.

After _that_, I think we’ll be in an excellent place for someone to pick up this ticket and write the right docs. We don’t necessarily need all of this to be merged though if someone wants to already take a look. A good first step would be to identify where in Django’s documentation we could document what’s discussed in this ticket.

[Priya]

Replying to Thibaud Colas:

Hi Thibaud,

After _that_, I think we’ll be in an excellent place for someone to pick up this ticket and write the right docs.

What I can understand by going through this ticket is that we need to add more explicit examples of input formats to the form fields in our Docs. To get more clarity, I would like to know if the requirement is somewhat like detailed examples stated in DateTimeField ​https://docs.djangoproject.com/en/5.0/ref/forms/fields/#datetimefield whereas just a link to accepted formats is given in DateField ​https://docs.djangoproject.com/en/5.0/ref/forms/fields/#datefield. So are we looking to provide more information here in DateField or DurationField, let's say, where link is given?

A good first step would be to identify where in Django’s documentation we could document what’s discussed in this ticket.

If my understanding of the ticket is apt, I would say adding the details within the respective fields themselves would be better as it would provide an easier understanding to the end user at a glance rather than moving to an altogether different section.

Please correct me if I am proceeding in the wrong direction.

[Ayush Khatri]

"This issue can be resolved by:

Adding placeholders to widgets like DateInput and TimeInput for better usability (e.g., 'YYYY-MM-DD' for dates).

Customizing error messages in DateField and similar fields to clearly communicate the expected format.

Updating templates to display placeholders and help texts dynamically.

Enhancing documentation with examples of expected formats for various fields.

I am assigning this issue to myself and will submit a patch addressing these points soon. Please let me know if any further inputs are needed."