Changing IO field order causes note type to malfunction in various ways

[glutanimate]

Steps to reproduce

1. Head to Tools → Manage note types, select the Image Occlusion note type, and click Fields
2. Change one of the following:
   • Move the Occlusion field to any position other than the first
   • Move the Image field to any position other than the second
3. Confirm your changes and proceed to add or edit an IO note

Expected behavior

Adding, editing, and reviewing IO notes works as usual.

Actual behavior

Adding, editing, or reviewing IO notes no longer works, in some scenarios silently, while in others with an error message that's not easily interpreted as a user.

---

Screencasts

Scenario 1: Moving the Header field to position 1, and thus bumping Occlusion and Image down by one. Result: IO notes can no longer be edited or added.

https://github.com/ankitects/anki/assets/5459332/303c1801-afb2-4e96-992c-30ef17549d0b

Scenario 2: Moving the Image field down by 1. Result: IO notes can no longer be reviewed properly.

https://github.com/ankitects/anki/assets/5459332/332cb96d-413e-478a-9dd1-52fc4bb697eb

---

Thoughts on the impact

• Anki note types typically do not depend on the order of their fields, so it having an effect in this case is fairly idiosyncratic and would end up surprising users as an unexpected pitfall.
• What characterizes this idiosyncrasy in particular is that we currently have a disconnect in behavior between the handling of IO notes across various parts of Anki: Rendering depends on field names while adding and editing depends on field indices.
• Given that we do not prevent users from making these types of changes and also do not provide informative & actionable error messages explaining the situation, this could end up being a headache for some users.
• Some scenarios that could prompt users to mess with the field order:
  • Given that the Occlusion field is currently set as the sort field, which some users might want to change as it makes it difficult to tell different IO notes apart in the browser, they might be inclined to also change the field order while they're at it (even though it's not necessary to designate the sort field)
  • Users coming from IOE will expect to be able to freely rearrange and rename the fields in the IO note type, as field order does not have an impact on IOE (IOE maps fields by their name, and in order for this to work for renamed fields, allows users to specify custom field names in its options menu)
  • Another fairly common scenario where users might run into this is when using add-ons like Add note id or Ze Add note id. Users of these add-ons will typically move the Note ID field to position 1 in order to bypass duplicate detection.
  • But even if there weren't any concrete scenarios we can think of at the moment, I think we should strive to avoid idiosyncrasies like this as they just introduce more custom behavior that users will have to learn, increasing the friction in using Anki's note type system.
• I think it's also important to point out that, from my experience, note type configuration issues were some of the most common causes for support requests about IOE, so hopefully that's something we can avoid with native IO.

[glutanimate]

Thoughts on a solution

Given that Anki field names are fully internationalized, mapping and identifying fields by their display name does not seem like a viable solution. Instead, I would propose the following:

• Let's extend NoteField or NoteFieldConfig (and, accordingly, EditorField.FieldData) with an additional property that allows us to equip individual fields with a stable internal identifier, e.g. in the case above occlusion for Occlusion (and its various translations)
• With an identifier specified, we could then update any IO logic that currently depends on field indices to instead match against field identifiers, decoupling both field naming and order from their programmatic handling.

In this scenario users would still be able to delete key fields like Occlusion and Image from the Fields dialog, and recreating them with the right identifiers specified would not be user-accessible. So I would additionally propose that we prevent users from deleting these fields, e.g. by extending the note type config with a list of required field identifiers, or by encoding the removability of a field in the note field config.

You could argue that users can also easily break other default note types by deleting key fields, but I would say that the situation is quite different here: For regular text note types, users have full control over their editing and rendering end-to-end. They can freely play around with field order, naming, and their referencing in their templates with no impact on internal Anki logic. With IO this is not the case as the editing and rendering behavior of IO notes lies outside the control of users.

WDYT @dae @krmanik ?

[glutanimate]

Another case to add to the scenarios above: Deleting either the Header or Back Extra field (or, more accurately, modifying the note type so that it has <4 fields) will also cause IO to stop working.

To handle this one, perhaps we could perform the check in image_occlusion::notetype -> io_notetype_if_valid before saving the notetype and thus prevent users from creating an invalid notetype? Right now these changes are accepted without an error in the Fields dialog. But I would also argue that, in order to be consistent with other default note types, we shouldn't depend on fields being present that aren't essential to internal editing & rendering logic.

[dae]

Header and Back Extra are currently essential, because in the mobile use-case those fields are shown in the I/O editor, and the Rust code expects to be able to write them when a note is added or updated.

On adding a unique identifier instead of using field index: you make some good points. It would need to fall back on the indexes if the identifiers were not found though, as these notetypes are already in use by AnkiMobile users.

A separate option for whether a field is removable or not feels like it might be overkill - what if we just made any field with a unique identifier protected?

[glutanimate]

Header and Back Extra are currently essential, because in the mobile use-case those fields are shown in the I/O editor, and the Rust code expects to be able to write them when a note is added or updated.

I see. I don't think there's any harm in also protecting them in that case. Albeit I'd still argue that, if we want to be fully consistent, it would be nice if we could treat all fields other than Image and Occlusion as regular fields at some point in the future.

(I had forgotten that the custom IO fields tab implementation on mobile only shows Header and Back Extra. I do think that this is something more advanced users will run into and be confused about, but IMHO not a major issue for now).

It would need to fall back on the indexes if the identifiers were not found though, as these notetypes are already in use by AnkiMobile users.

Good point :+1:

Though would it perhaps make sense to also have some kind of migration routine for those existing notetypes? I would assume that these could already be present in a significant number of user collections, even if those users haven't used IO, yet (as I assume it's similar to desktop where the note type will get created either at launch or when using the editor).

what if we just made any field with a unique identifier protected?

I think that would work nicely as well.

[krmanik]

I think preferences can also be used, it will be up to user to select the field for adding occlusion data and image data. Using the prefs we can directly access the fields and hide the field in add, edit, browse mode, and show it in configuration.

[dae]

I'm afraid I'm not sure that's the best idea - it adds extra complexity to the UI, and more ways things can go wrong. The user will already be able to rename the fields if they want - isn't that enough?

Though would it perhaps make sense to also have some kind of migration routine for those existing notetypes?

Sure, this could be handled in Check DB fairly easily.