Exploring OpenAPI Overlay Through Open Banking Posted in Design Chris Wood May 28, 2025 You know the drill. A new API release comes along, and regardless of whether you are doing design-first or code-first for your APIs, you need to rely on Mrs. Copy and Mr. Paste somewhere to make an update to an OpenAPI description. While having a single source of truth for your OpenAPI description is absolutely what you should be shooting for, there’s always some late edit, tweak for a header field your API gateway needs, or copy by a tech author that needs to be added. The ideal solution to merging information into your OpenAPI description is to implement a documentation pipeline with prescribed operations to help you manage merges and changes from different sources. This is the sweet spot for the OpenAPI Overlay Specification. Overlay facilitates implementing automated processes to apply some of the changes described above. For example, adding a header field prescribed by your API gateway that is not needed or defined by your implementation is a great use case for Overlay. The application of Overlay can, however, be applied much more widely than a single organization, and a worked example comes in the shape of the UK Open Banking Standards. These standards have special provisions for editing API descriptions, making open banking a great application for Overlay. New to Overlay? Read our introduction to see how it works. API Specifications in UK Open Banking The UK open banking ecosystem is based on standardized APIs defined, maintained, and released by a centralized body. The vast majority of account servicing payment service providers (ASPSPs) (a fancy way to say a bank in open banking regulation terminology) must adhere to the standardized API design provided through several OpenAPI description documents. The guidelines for implementing the standards do, however, allow an ASPSP to change the API description in several ways, with the constraint being that changes must be published at the ASPSP developer portal. The changes permitted include the following: Removing API operations: Under the Revised Payment Services Directive (PSD2) (the regulation that dictates parts of the open banking standards), ASPSPs must make the same functions available through an API that are available to customers through their online and mobile banking portals. ASPSPs are not, however, forced to implement new functionality they do not offer that is described in the standards. For example, if an ASPSP does not offer file-based payments to customers, it does not need to provide it via its PSD2 APIs. ASPSPs can, therefore, remove this if they choose from their published API description. Defining recommended values as enumerations: The UK Open Banking standards implemented a policy of providing standardized enumeration values that ASPSPs could adopt, either partially or fully, and supplement with their own values. These enumerations are provided using a Specification Extension called x-namespaced-enum. ASPSPs are obliged to publish the values they support, ideally as an enum property of a string, where they diverge from the standardized list so that API consumers know what is supported. Such values include supported account types, payment rails, and identifiers for financial institutions for payment routing. Adding supplementary data: Supplementary data is an ISO 20022 term that refers to properties of a message that are not specifically described by the message and are therefore treated as an unparsable “blob” that can be ignored. The concept of supplementary data was reused in the UK Open Banking standards to create standardized properties ASPSPs can use to add additional properties that reflect what is available in online and mobile banking channels. Examples of such properties might include additional payment references or identifiers for a specific international payment route. ASPSPs must publish these changes to ensure third-party providers (TPPs) (the fintech services) can correctly populate the data. The changes permitted under the UK Open Banking Standards are a great way of showing how Overlay can work on industry standards and take the manual heavy lifting out of making such changes. Let’s take a hypothetical example using “The Bank of M&D,” which wants to tailor the standards to the specifics of its open banking APIs. Removing API Operations Suppose The Bank of M&D wants to remove all unsupported API operations, which makes sense as they do not want to deal with constantly returning 404 to masses of API calls to operations that are not implemented. (The fact they do not implement them is described in a central Confluence site and is not necessarily machine-readable). Please note that all JSONPath expressions in these examples adopt RFC 9535 semantics in accordance with the Overlay Specification. RFC 9535 contains limited support for matching JSON property names using a wildcard or regular expression, so if you are an avid fan of, for example, JSONPath Plus, you might find the expressions overly verbose. The Bank of M&D does not support file payments or any international payment, so their first step is to create Action Objects that remove these: - target: $.paths['/file-payments'] remove: true - target: $.paths['/file-payment-consents'] remove: true - target: $.paths['/file-payment-consents/{ConsentId}'] remove: true - target: $.paths['/file-payment-consents/{ConsentId}/file'] remove: true - target: $.paths['/file-payments'] remove: true - target: $.paths['/file-payments/{FilePaymentId}'] remove: true - target: $.paths['/file-payments/{FilePaymentId}/payment-details'] remove: true - target: $.paths['/file-payments/{FilePaymentId}/report-file'] remove: true - target: $.paths['/international-payment-consents'] remove: true - target: $.paths['/international-payment-consents/{ConsentId}'] remove: true - target: $.paths['/international-payment-consents/{ConsentId}/funds-confirmation'] remove: true - target: $.paths['/international-payments'] remove: true - target: $.paths['/international-payments/{InternationalPaymentId}'] remove: true - target: $.paths['/international-payments/{InternationalPaymentId}/payment-details'] remove: true - target: $.paths['/international-scheduled-payment-consents'] remove: true - target: $.paths['/international-scheduled-payment-consents/{ConsentId}'] remove: true - target: $.paths['/international-scheduled-payment-consents/{ConsentId}/funds-confirmation'] remove: true - target: $.paths['/international-scheduled-payments'] remove: true - target: $.paths['/international-scheduled-payments/{InternationalScheduledPaymentId}'] remove: true - target: $.paths['/international-scheduled-payments/{InternationalScheduledPaymentId}/payment-details'] remove: true - target: $.paths['/international-standing-order-consents'] remove: true - target: $.paths['/international-standing-order-consents/{ConsentId}'] remove: true - target: $.paths['/international-standing-orders'] remove: true - target: $.paths['/international-standing-orders/{InternationalStandingOrderPaymentId}'] remove: true - target: $.paths['/international-standing-orders/{InternationalStandingOrderPaymentId}/payment-details'] remove: true All operations relating to these payment types have now been removed. The OpenAPI description now contains many orphaned objects, of course, as there’s no support in the Overlay Specification to remove them through introspection and, therefore, unlikely to direct support in Overlay-specific tools. However, The Bank of M&D has the option of using Spectral or Vacuum to chase them down and add rules to remove in the future. Leaving orphaned objects in place makes no functional difference to the OpenAPI description, but removing them reduces bloat and cognitive load for developers trying to comprehend the content of the API description. Defining Recommended Values as Enumerations The API governance policies at The Bank of M&D mean that namespaced operations must also be replaced with enum values listing only the values that apply to a given property. For example, in the versions published with the standards, the Schema Object OBInternalAccountIdentification4Code has a namespaced enumeration with all standards values listed: OBInternalAccountIdentification4Code: description: >- Name of the identification scheme, in a coded form as published in an external list. For a full list of values refer to `OBInternalAccountIdentification4Code` in *OB_Internal_CodeSet* [here](https://github.com/OpenBankingUK/External_Internal_CodeSets) type: string x-namespaced-enum: - UK.OBIE.BBAN - UK.OBIE.IBAN - UK.OBIE.PAN - UK.OBIE.Paym - UK.OBIE.SortCodeAccountNumber - UK.OBIE.Wallet The Bank of M&D policy is to list exactly the supported values, as they believe this represents a better developer experience and reduces errors due to payment initiation requests for unsupported account types. The Bank of M&D, therefore, implements the following Action Objects to remove the namespaced enumeration values and replace them with the values they support through an enum: - target: $.components.schemas.OBInternalAccountIdentification4Code['x-namespaced-enum'] remove: true - target: $.components.schemas.OBInternalAccountIdentification4Code update: enum: - UK.OBIE.IBAN - UK.OBIE.SortCodeAccountNumber Note the semantics of Overlay here, namely that the update is a merge with the existing target object. A rule is also implemented to specifically remove the namespaced enumeration. However, from the perspective of the API description this could be ignored as it is a Specification Extension and only applied to audiences who can comprehend it. Adding Supplementary Data The final change The Bank of M&D wants to make is to add a property they support in their online channels called StructuredDebtorReference, which allows an additional narrative to be added to customer payments that is displayed in their transaction list. The Bank of M&D wants to add this to ensure they are in line with their understanding of the requirements of PSD2 in the UK (and their lawyer told them so…). Adding the required property means adding another Action Object. This time, however, The Bank of M&D is replacing a Reference Object with an inline Schema Object, meaning they must remove the Reference Object first. Leaving the Reference Object in place means the new objects and reference will live side by side, which is invalid in OpenAPI. The Bank of M&D also needs to avoid updating the source Schema Object OBSupplementaryData1 as this is shared by many operations, and StructuredDebtorReference only applies to immediate domestic payments. The property must also appear in both the consent and the payment instruction payload due to the rules around intent lodging in the standards and how payment details must appear. The Bank of M&D therefore, adds the following Action Objects to their Overlay: - target: $.components.schemas.OBWriteDomesticConsent4.properties.Data.properties.Initiation.properties.SupplementaryData['$ref'] remove: true - target: $.components.schemas.OBWriteDomesticConsent4.properties.Data.properties.Initiation.properties.SupplementaryData update: type: object properties: StructuredDebtorReference: description: Proprietary property that allows a structured debtor reference to be provided type: string minLength: 1 maxLength: 70 - target: $.components.schemas.OBWriteDomestic2.properties.Data.properties.Initiation.properties.SupplementaryData['$ref'] remove: true - target: $.components.schemas.OBWriteDomestic2.properties.Data.properties.Initiation.properties.SupplementaryData update: type: object properties: StructuredDebtorReference: description: Proprietary property that allows a structured debtor reference to be provided type: string minLength: 1 maxLength: 70 The final policy of updating Supplementary Data to include additional reference completes The Bank of M&D Overlay. The great thing is that this policy is now encoded so it can be executed by tooling and run repeatedly and deterministically at every new standards release. Mrs Copy and Mr Paste can rest easy from now on. Using Overlay with Industry Standards The application of Overlay in this scenario makes a lot of sense, and its application is not restricted to the UK open banking ecosystem. Other major standards, such as the Berlin Group, take a framework approach, providing a superset of open banking and open finance operations that can be pared down to market or financial institution requirements. Other industry standards that provide a framework described using OpenAPI — take HIPAA in healthcare —also take this approach, typically implementing a lot of redundancy in the API description. Overlay provides a systematic and deterministic way of reducing the noise when implementing standards-based APIs. Overlay provides a real boost for automation, both with and without industry standards. Charting a course for the future of Overlay is also interesting, as the Actions that can be supported could be supplemented by automated operations based on introspection of a given OpenAPI description. We’ve already hinted at one such idea in the example of removing orphaned, unreferenced operations automatically when the parent API operation is removed. If you are interested in getting involved and helping steer the Overlay ship, head over to the Overlay Specification repository, check out the existing issues, or join the discussions to help shape the next version of Overlay. The latest API insights straight to your inbox
