Make BrAPI Lists Ordered

[mlm483]

Feature Request

@BrapiCoordinatorSelby I think BrAPI lists serve the most use cases if they are ordered lists. Currently, there is nothing in the spec that requires ordering to be preserved. The BrAPI-Java-TestServer generally returns list items in the same order they were created in, but this is only due to the default order in which PostgreSQL returns rows when an ORDER BY clause is omitted and is not guaranteed by any means.

Possible Implementations

Adopt UUID v7

Version 7 UUIDs are time-sortable, the first 48 bits are a timestamp with millisecond precision. For entities created by the same system in the same millisecond, implementations usually use an increasing counter to ensure monotonicity within each millisecond as well.

Pros

• This doesn't require adding new fields.

Cons

• It's a little too clever, people generally won't look at a UUID and understand it's v7 and time-sortable. The purpose of an integer field called "position" for example is far more obvious.
• It's probably better to store and represent list order explicity.
• Poor options for existing data migration: either preserve primary keys of existing data and forgo time-sortability or migrate to UUID v7 and change primary keys of existing entities.

Add Field(s) to List Items

Adding a created timestamp and/or an integer list position field to list items could work in at least two ways. (1) The new field could be added to the API spec and explicitly passed back and forth when creating and reading lists (an integer position would make sense in this case) or (2) it could be a means of transparently preserving the original order of the list (a timestamp would be suitable in this case).

Pros

• Explicit, obvious function.
• Forces a data migration, but will not change primary keys.

Cons

• Requires change to API spec or at least data model.

[mlm483]

An example of transparently maintaining the ordering of BrAPI lists can be seen here in Breeding Insight's fork of the BrAPI-Java-TestServer.

[BrapiCoordinatorSelby]

hmmm I'm not sure I see the argument for adding an explicit order field to the Lists spec. JSON arrays are ordered and the order will be maintained from client to server. its up to the server implementation to maintain the order of the items sent from the client. And that can be done without altering the spec, as you have demonstrated with the test server.
I would be open to adding text to the spec stating that maintaining the order is a required/recommended best practice. But I don't see why the JSON data models need to become more complicated?

[mlm483]

I see your point. I thought of a case where adding an explicit order field could be useful, though it might not be real use case.

• If someone wanted to preserve non-contiguous ordering (and potentially slot in other items later).
• If adding new items to a list in specific positions, one would want to specify item positions in the POST to /lists/{listDbId}/data.

I realize that's a little contrived, but it does make me think that if the documentation is changed to recommend that implementations preserve order, it would be worth describing the recommended behavior of the /lists/{listDbId}/data POST endpoint specifically as well. I think append is the most natural behavior.