JSON-LD does not support array ordering so the specification doesn't mandate consistency in request/response array ordering, and hence there is currently no way for a Broker to reliably match the OrderItem error responses from C1 and C2 with their request, especially when they have multiple OrderItems for the same opportunity.
This primarily effects C1 and C2, as OrderItem level error responses are not available from the other endpoints. However there may also be use cases for B and P where the Broker is interested in matching a particular requested item with its response.
Design
Discounting the option where the Broker generates an @id (and hence the URL structure), which it does not do elsewhere except for the endpoint URLs.
Three approaches considered:
1. The Broker generates a UUID for each OrderItem as the identifier, but the Booking System does not use these for the @id
Pros:
Does not require any logic outside of the request handler (as the Booking System is simply reflecting the UUIDs back to the Broker)
Small breaking change
It would potentially make leasing easier to implement for the Booking System, as unique OrderItem IDs could be used to create, extend, or cancel leases on specific items
Cons:
The OrderItems already get assigned a unique @id that is provided by the Booking System at B for subsequent use, so this would duplicate that - and arguably such an @id should then be based on the this new OrderItem UUID for consistency? Otherwise there would be a different identifier for the same OrderItem at a different point in the flow?
This would introduce further potential for UUID clashes and error conditions around this that would need to be handled.
2. The Broker generates a UUID for each OrderItem as the identifier, and the Booking System uses these to reflect back the @id that it immediately generates
Pros:
This would be consistent with the approach taken for an Order
It would potentially make leasing easier to implement for the Booking System, as unique OrderItem IDs could be used to create, extend, or cancel leases on specific items
Cons:
This would introduce further potential for UUID clashes and error conditions around this that would need to be handled.
This would also be a larger breaking change overall, as it would impact existing OrderItem @ids
Assuming it was related to @id, this makes this option very prescriptive. The Open Booking spec already forces booking systems to adopt a UUID at the Order level, however it very flexible at the OrderItem level as to how these are identified. This option extends the impact of the spec further into the booking system.
Given that this is mainly an issue around C1 and C2, this seems like heavy solution.
3. The Broker generates a sequence number for each OrderItem based on their position in the array and includes it in the request; then the Booking System simply reflects this back to the Broker in their response.
Pros:
Does not require any logic outside of the request handler (as the Booking System is simply reflecting the integers back to the Broker)
Simple and easy to implement
Small breaking change
Does not create duplicate identifiers
Cons:
May be less extensible? However given the OrderQuote paradigm is all about not allowing item-level updates without requesting a whole new quote, it is unlikely that any usecase would benefit from UUIDs? (However if an OrderQuote gains OrderItem @id values in future they could easily live alongside this.)
schema:position is described as an integer representing the order of OrderItems within the array, as JSON-LD does not support array ordering. This allows the Broker to match any errors provided in the response to their request. The position of an OrderItem in the response MUST match the position for the same OrderItem provided in request, and implementations MUST use this value to match responses with requests instead of relying on the order of the elements in the array. This is REQUIRED for C1, C2, P and B requests and responses, but MUST NOT be persisted or be present in the Orders Feed or other endpoints.
Proposer
ODI
Why is this needed?
JSON-LD does not support array ordering so the specification doesn't mandate consistency in request/response array ordering, and hence there is currently no way for a Broker to reliably match the OrderItem
errorresponses from C1 and C2 with their request, especially when they have multiple OrderItems for the same opportunity.This primarily effects C1 and C2, as OrderItem level
errorresponses are not available from the other endpoints. However there may also be use cases for B and P where the Broker is interested in matching a particular requested item with its response.Design
Discounting the option where the Broker generates an
@id(and hence the URL structure), which it does not do elsewhere except for the endpoint URLs.Three approaches considered:
1. The Broker generates a UUID for each OrderItem as the
identifier, but the Booking System does not use these for the@idPros:
Cons:
@idthat is provided by the Booking System at B for subsequent use, so this would duplicate that - and arguably such an@idshould then be based on the this new OrderItem UUID for consistency? Otherwise there would be a different identifier for the same OrderItem at a different point in the flow?2. The Broker generates a UUID for each OrderItem as the
identifier, and the Booking System uses these to reflect back the@idthat it immediately generatesPros:
Cons:
@ids@id, this makes this option very prescriptive. The Open Booking spec already forces booking systems to adopt a UUID at the Order level, however it very flexible at the OrderItem level as to how these are identified. This option extends the impact of the spec further into the booking system.3. The Broker generates a sequence number for each OrderItem based on their position in the array and includes it in the request; then the Booking System simply reflects this back to the Broker in their response.
Pros:
Cons:
@idvalues in future they could easily live alongside this.)Proposal: Use Option 3
schema:positionis defined as a REQUIREDschema:IntegeronOrderItem, for C1, C2, P and B requests and responsesschema:positionis described as an integer representing the order ofOrderItems within the array, as JSON-LD does not support array ordering. This allows the Broker to match anyerrors provided in the response to their request. Thepositionof anOrderItemin the response MUST match thepositionfor the sameOrderItemprovided in request, and implementations MUST use this value to match responses with requests instead of relying on the order of the elements in the array. This is REQUIRED for C1, C2, P and B requests and responses, but MUST NOT be persisted or be present in the Orders Feed or other endpoints.