CR2 Changelog for fixes, corrections, clarifications and simplifications

[nickevansuk]

Proposer

ODI

Proposal

The table below documents the changes that have been made to the Open Booking API specification’s Editor's Draft since the specification’s initial Candidate Release on 27 May 2019, including the rationale for each change.

This proposal seeks to ensure consensus exists on the changes made, which are all technical improvements and clarifications rather than functional or scope changes, and recommends the publishing of an updated Editor’s Draft as an official “CR2”.

This proposal includes 15 breaking changes, which are mostly simple property renames or other minor changes. Only a small number of these are likely to affect any existing implementation. These are highlighted in bold in the changelog below.

These changes are available to view in the current Editor's Draft here.

Process

The changes made are in response to feedback or tooling development, and are either minor error corrections, obvious clarifications, or obvious simplifications. They do not expand the scope of the existing specification, and tighten it up to aid implementation.

Where changes to the specification document are more substantial, an associated GitHub issue has been created for the change.

Please do comment on this issue (or the more specific issue if it exists), referencing the change number in this list if you have any concerns, questions, or feedback.

Note that some of the changes made below rely on proposed corresponding changes to the Modelling Specification, which must be formalised and released before this specification can be released.

Changelog

Change Number	Commit	Description	Rationale	Issue
1	0551314	`orderQuantity` was removed in a previous revision to the specification to simplify it, however the example was not updated. This change fixes the example to match the specification.	Fixed typo
2	1089178	Include better description of status of the document	Making it clear that the Editor’s Draft is an evolving document, as per this Changelog
3	173ea13	Correct the `OrderProposal` `@id` format in the examples to match the specification	Fixed typo
4	5468424	The namespace of the broker property was incorrectly specified as `https://openactive.io/broker` has been corrected to `https://schema.org/broker`	Fixed typo
5	1658227	Fix typo in example: `BrokerAgent` to `AgentBroker` in the example	Fixed typo
6	d13e293 8fb9f06	Fix inconsistency of the terms `totalTaxSpecification` and `totalPaymentTaxSpecification` used in the spec and the examples and rename instead to just `totalPaymentTax` Breaking change: was introduced in August. Renaming of `totalPaymentTaxSpecification` property required.	This change makes it clearer that this property complements `schema:totalPaymentDue`
7	2e73e8d	Add `brokerRole` and `broker` to OrderQuote examples, and remove `orderItemStatus` from OrderQuote examples, to match specifications	Fixed typo
8	f6d947a ad5e76f	Replaced `https://openactive/` with `https://openactive.io/`	Fixed typo
9	f1df771	based on anything anything other	Fixed typo
10	86b6a9b	Mandate security to enforce that Customers can only change their own Orders	This was previously a “SHOULD”, however is clearly a security issue if not implemented, so has been updated to a “MUST”
11	cf773bb	Switched to `@type` and `@id` in line with plans for new modelling spec and tooling. Breaking change: was introduced in October. Renaming of `@type` `@id` properties required. OpenActive libraries already do this automatically.	The tooling work has made it clear that using the original JSON-LD terms for `@type` and `@id` will greatly simplify tooling implementation in the longer term. A proposal exists for such an update to the modelling specification, which is not a breaking change, due to the 2.0 specification allowing for either to be used. This change was made to the Open Booking API CR specification to ensure early adoption during booking work and within tooling being developed.	219
12	c246a82 96161d6 0639413	Include `seller` `@id` in requests for C1, C2, P and B. Not a breaking change as existing implementations should simply ignore this.	Although it was originally envisaged that the Seller ID could be derived from the authentication token by the Booking System, the variety of authentication approaches permissible within the specification mean that this is not always possible. Including the “seller” ID in requests ensure that both Broker and Booking System are explicit about their expectations, and makes it easier to implement on both sides in a variety of authentication scenarios.
13	edef5bd	Replace the definition of the `description` property within `OpenBookingError` from “A slightly longer, human-readable summary of the problem type. It largely SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization or to provide specific information about why the error occurred in that particular case.” to “A human-readable explanation specific to this occurrence of the problem, providing specific information about why the error occurred in this particular case.”	The error model was derived from RFC7807, however our definition of the Error “description” property was not correctly inferred. This change brings the error model in line with RFC7807 by updating the definition of the “description” property.
14	4a1a39d	Rename `OpenBookingError` property `status` to `statusCode` Breaking change: was introduced in November. Renaming of `status` property to `statusCode` required. OpenActive libraries already do this automatically.	Bringing the property name in line with RFC7807.
15	4a1a39d	Improved clarity of the definition of `name` and `statusCode` properties of OpenBookingError - such that they “MUST communicate the associated Use Case defined in this section of the specification” and “that MUST match the associated Status Code defined in this section of the specification”.	This change ensures that the `name` and `statusCode` are used correctly.
16	beadbd8	Corrected the OrderQuote Deletion example, which was previously duplicating the Order Deletion example	Fixed typo
17	beadbd8	Fixed OrderQuote IDs in examples to match the `/order-quotes/` pattern	Fixed typo
18	89723f2 8494554	Removed minor version from media type, and added “Brokers will receive data in the most current format within that major version”. Breaking change: media type needs to be updated to remove the trailing “.0”.	The media type versioning definition was overly complex, which added unnecessary complexity to implementations. The ability for brokers to request specific minor versions of responses, which by definition would not contain breaking changes, did not appear to merit the additional complexity required to implement this. The spec now only includes major version the in media type, and does not allow locking down to minor version. This encourages non-breaking improvements to the API spec to be made, and for breaking changes to force a major version number increase.
19	8494554	Updated example to use `PrivacyPolicy` and `TermsOfUse` instead of just `Terms`	Fixed typo
20	8494554	Replaced “See the Modelling-Opportunity-Data for more information” with “See the Modelling-Opportunity-Data specification for more information”	Fixed typo
21	8494554 97aec7e	Allowed the Seller to be an `schema:Organization` or `schema:Person`, including clarifying that a logo must be used for a `Person`, rather than a photo.	This brings the Open Booking API specification in line with the Modelling Specification 2.0, which allows for both.
22	8494554	Update the `customer` property to a MUST in the response to indicate that the `customer` must be reflected back. Breaking change: customer property must now be included in response	In pre-CR versions of the specification the customer was not necessarily reflected back, however this was changed prior to the CR release for consistency. This change makes the model consistent with the rest of the specification.
23	ca67285	Update examples to ensure the name of the TaxChargeSpecification ("VAT at 20%") is consistent with the rate (0.2)	Fixed typo
24	36c89e3	Added missing `seller` `@id` to model	Fixed typo
25	5de4440	Clarify `IncompleteBrokerDetailsError` use based on existing required fields in the specification i.e. that `name` is the only required property.	Improves clarity
26	9b71746 b9928aa	Clarify `OrderItem` `@id` is only required for P and B responses, and not for C1 and C2 responses.	Improves clarity
27	4ef3fee	Remove `invalidParams` and `method` from OpenBookingError, and update `instance` to match RFC7807. Not a breaking change as unrecognised parameters are ignored by the Broker.	Implementation of `invalidParams` and `method` did not add any clear value, and also increased complexity. The error model now very closely reflects RFC7807.
28	595c840	Fix example to use correct UUID for OrderItem	Fixed typo
29	0c45881	Replace use of `attendeeInstructions` with restriction properties for booking restrictions. Breaking change: if attendeeInstructions was being used for restrictions, new properties must be used instead	`attendeeInstructions` was being used incorrectly to describe booking restrictions, which was not in line with Modelling Opportunity Data 2.0. The specification has been updated to leverage this proposal instead.	221
30	0639413	Clarify that orderProposalVersion is only required in approval flow, and fixed examples to pass validator	Fixed typo
31	2a29ce6	availableChannel is only required in open data, so should not be included in requests or responses	Fixed typo
32	a1ff286	Fixed Offer for Broker request to only include `@id`, and `openBookingFlowRequirement` is not included in request	Fixed typo
33	7306f11 2d13c35	Added properties to SessionSeries example to conform to minimum specified by the Modelling Opportunity Data specification	Bringing example in line with Modelling Opportunity Data 2.0 and 125.
34	7306f11	Added `orderRequiresApproval` to examples	This property is required, and was not present in the examples
35	bc8b882	Added specification for opportunity data properties Not breaking as additional (removed) properties are ignored by the Broker, and required properties were already required in the modelling specification.	The current specification does not provide guidance on which opportunity data properties to include in responses, which will likely lead to increased complexity and unnecessary variance between implementations.	125
36	b20f311	Make additionalProperty optional in the property table, as it is specified as a MAY elsewhere	Fixed typo
37	b3ec86b	Added clarity for when to include opportunity data in feeds, by repeating the wording in the requests / responses section	Improves clarity
38	b020ba5 \ 5875bf5	Added clarity to expectations around opportunity data for requests and responses, to make clear what the examples already show. Requests should include only @type and @id, and responses should include full opportunity data.	Improves clarity
39	aeedc56	Added clarity to explanations about when an orderProposalVersion should be returned i.e. not in the Orders Feed or by B.	Improves clarity
40	52e1597 \ 1d77213 4c5e876	Clarify Orders feed property specification and processing in line with existing examples, by replacing the column in the `Order` data model table with more concrete paragraphs of text. Clearly define the model property statuses (borrowing text from the modelling specification), and also remove the implied granular “PATCH” that is problematic for implementers. Additionally introduce the concept of “Replacement” in order to make properties of the Orders feed optional where they do not provide any functional benefit. Breaking change: if the Orders Feed previously did not supply the properties that were shown in the example, it may need properties added or removed to match. “Identifier” will also need to be added, though this is just the UUID which should already be readily available.	Improves clarity, and reduces the scope for misinterpretation and implementation divergence.	126 124
41	52e1597	Fix `unitTaxSpecification`, `additionalProperty` and `error` property specifications to match examples.	Fixed typo
42	18fbcc7	Align orderSellerNote and orderCustomerNote property specifications with the rest of the specification, as they were “RECOMMENDED” and should be “OPTIONAL” or N/A	Fixed typo
43	c6f2b33	The specification infers in multiple places that orderRequiresApproval is only present in C1/C2 (OrderQuote). This change adds a sentence to make this explicit.	Improves clarity
44	aef3684	Add orderProposalStatus to P response example, to bring the example in line with the specification.	Fixed typo
45	1663f70	Added the clarity that Broker may also use Middleware to access API, and better linking of the Authentication Credentials terms	Improves clarity
46	225b248	Added that all priceCurrency values within an Order, OrderQuote, or OrderProposal must be identical.	Clarifies potential ambiguity of implementation
47	e851c83	Clarify prepayment, availableChannel, Offer, and OfferOverride. Specify the default behaviour already inferred by the specification explicitly, removing ambiguity around underspecified properties.	Improves clarity
48	fc8c5ca \ 539ac53 e1d2b4b	totalPaymentDue and totalPaymentTax must be calculated excluding any OrderItems that include errors, with the exception of IncompleteAttendeeDetailsError and IncompleteAttendeeDetailsError. Breaking change: an update to the total tax calculation may be required	When OrderItems simply lack attendee details, they should be included in the totalPaymentDue, as this is much more intuitive. This was an oversight with the late introduction of attendee details into the specification.
49	89b4a7b \ 24cca98	Clarify requirement for Opportunity id, Offer id, and Seller id to be present in the open feed	Improves clarity
50	c9f5ae1 \ d5edc66	Clarified that UUID must meet RFC4122, and made the paths in the examples explicit. Also clarified security around UUIDs being unique within authentication credentials. This was implied by examples and existing text, but could be open to interpretation.	Improves clarity
51	0733cc5	Simplify API discovery in line with the direction of the Dataset API Discovery spec Breaking change: if the endpoint paths did not follow the examples, they will be updated to match	The previous API discovery explanation was inconsistent and was more relevant to an older version of the specification. It was also inconsistent with the current direction of the Dataset API Discovery and schema.org. This change greatly simplifies discovery to just a Base Url, without impacting existing implementations that have followed the example paths. Also reduces testing surface area and makes swagger files more useful.	2
52	e08401c	Clarified not to use `givenName` and `familyName` for the Seller, and use `name` instead. This is implied by the specification (which does not mention givenName and familyName in this context) but is not explicit.	Improves clarity
53	96161d6	Clarify use of Seller Id, and clarify that idempotency is applicable to all endpoints, which is already implied by the REST verbs in use.	Improves clarity
54	9e0e190	Clarify the definitions of Order UUIDs, Order @id, orderProposalVersion and Order Proposal UUID.	Improves clarity
55	839b237	Introduce a simple `position` property to OrderItem in C1, C2, P and B. Breaking change: reflect back position `property` for C1, C2, P and B.	This is required so that the Broker can reliably match OrderItem errors in responses to their requests.	129
56	4d799a3	Remove unnecessary duplicate property definition for “totalPaymentDue”	Fixed typo
57	576c315	Added description to availableChannel	Fixed typo
58	27458df	Make `name` property required for `BookingService`, otherwise the `bookingService` property state of REQUIRED for `Order` does not follow. Breaking change: if examples were not followed, will need to include the “name” of the BookingService	Fixed typo
59	19a9664	Updated the definition of Broker to more clearly separate the API client from the actual economic actor by introducing the term “Booking Partner”: \ \ “Broker: The organisation, that provides an application allowing Customers to make bookings. For simplicity the API client is referred to as the Broker throughout this specification, however other API clients are permissible, and Booking Partner is the collective term for different types of clients of this API.” \ \ “The term Booking Partner is used to refer to the authenticating party represented by the Authentication Credentials, which is distinct from the Broker represented by the broker property. The Booking Partner may be a Broker, or a Middleware, or any other authenticating party (including the Seller if brokerRole is set to NoBroker).”	Improves clarity, with more subtle changes than proposed in 128, and no changes to diagrams	128
60	855e688	Clarify use of `schema:Person` for `attendee`, and the purpose and use of the `identifier` property for analytics. ““The `identifier` property MAY be provided by the Broker if a unique identifier for the Customer or `attendee` is available, to allow the Booking System to provide analytics based on repeat visits of the same guest. However such an `identifier` MUST only be matched only within each unique set of Authentication Credentials to prevent identifier collisions between Booking Partners.”	Improves clarity
61	25e84c8	Align specification with Modelling Specification regarding use of Schema.org properties, without affecting backwards compatibility. Add versioning policy to reflect the implication that new versions will be backwards aim to be backwards compatible.	Fixed typo and improves clarity
62	30da5c7	Clarify confusing specification around the payment reconciliation detail validation (including the inconsistent preconditions based on totalPaymentDue before it was known), by creating a dedicated section to explain this, and relaxing and simplifying the requirements. Breaking change: Added MissingPaymentDetailsError to complement IncompletePaymentDetailsError.	Improves clarity
63	8b16c77	Added recommended structure for OrderItem ID URLs and added consistency with examples Fixed OrderProposal example, and removed unnecessary and underspecified OrderItem ID requirement from OrderProposal	Improves clarity and fixed typo
64	abb4f60	Fixed inconsistency around Seller authorisation in Authentication Credentials	Improves clarity and fixed typo
65	ec7dd9d	Clarified sharing of logic between C1 and C2, to be clear that the endpoints themselves are separate	Improves clarity and fixed typo
66	9cb2c0e	Rename “accessToken” to “accessPass” so it does not clash with OAuth2 terminology Breaking change: Renaming of `accessToken` property to `accessPass` required. OpenActive libraries already do this automatically.	As OAuth2 is also mentioned in the specification we should not be introducing conflicting terms.
67	47399d9	Fixed typos in model tables in specification	Fixed typos
68	4d0a752	Clarified use of orderProposalVersion and seller properties	Improves clarity
69	0ec43ad	Clarify use of openBookingFlowRequirement in the open feed (and that it is not present in other endpoints), in line with examples	Improves clarity
70	8296bf8	Unlock additional experimentation for barcode extension point by allowing barcode to be supplied by the Broker	The specification inadvertently restricted experimentation around the supply of barcodes by the Broker. This minor change allows for such experimentation, without any change in behaviour if not supported.
71	7803e94	Improved bookable cross-references, and renamed UnavailableOpportunityError OpportunityOfferPairNotBookableError Breaking change: Renaming of `UnavailableOpportunityError` property to `OpportunityOfferPairNotBookableError` required. OpenActive libraries already do this automatically.	Make error name more self-documenting, as previous error name was ambiguous
72	5ce123b	Match case of “Orders feed” references, and harmonised reference to P	Fixed typos
73	36f3566	Add clarity that capacity calculations take into account the current lease	Improves clarity
74	2fcb73e	Clarify that tax calculations are not to be attempted by the Broker	Improves clarity
75	39fdfb7	Clarify requirements of @id as an identifier, without requiring the reader to infer the reference from other specifications	Improves clarity
76	3ac987b	Clarify booking without payment via the `prepayment` property, by creating a section summarising the existing behaviour Breaking change: Require `prepayment` property on `totalPaymentDue`, if prepayment has been implemented	Improves clarity	131
77	db6b5d7	Provide concrete recommendations around implementation of OAuth2 for Booking Systems to encourage convergence and define terms. Note as these are recommendations only they are not breaking changes, and are designed to make implementation easier.	There is confusion amongst current implementers around how best to handle authentication - this change provides recommendations that facilitate convergence of authentication between booking systems, which will greatly simplify the Broker's integration requirements and lower the barrier to entry for them: especially for Booking Systems that support multiple Sellers.	132
78	1565973	Allow consent to terms to be remembered by the Broker when `requiresExplicitConsent` is used.	Previous recommendations for `requiresExplicitConsent` did not allow for consent to be remembered, which was inconsistent with the ability to remember Customer responses for attendee details, and additional details.
79	672c350	Clarify OrderItems must not be cancelled after the event has occurred as it is referenced inconsistently throughout the specification	Improves clarity
80	c2306ea	Clarify that duplicate attendees require duplicate Person objects, which is implicit in the specification but not stated	Improves clarity
81	3bc41f0	Rename `OrderConfirmed` and `OrderProposed` to `OrderItemConfirmed` and `OrderItemProposed`; as both enum values relate to the OrderItem rather than the Order Breaking change: Renaming of `OrderConfirmed` and `OrderProposed` to `OrderItemConfirmed` and `OrderItemProposed` required. OpenActive libraries already do this automatically.	Improves clarity