The Berlin Group openFinance API Framework foundational course

Module 5: The Data and Documentation Ecosystem

Effective implementation of the openFinance API Framework requires a thorough understanding of its documentation and data definitions. The Berlin Group provides a comprehensive set of resources that are structured to provide clarity and precision for both business and technical stakeholders.

The openFinance Data Dictionary

The Data Dictionary is the semantic foundation of the entire framework. It is a single, central document that provides an exhaustive definition for every data element, complex data type, and enumeration used across all API services. This document is the single source of truth for the meaning and interpretation of data.

A key feature of the Data Dictionary is its deep alignment with the global ISO 20022 standard for financial messaging. By rooting its definitions in this international standard, the framework ensures semantic interoperability. This means that when the API uses an element like instructedAmount, its definition is consistent with how that concept is understood globally in the financial industry. This alignment is vital for avoiding ambiguity in data interpretation and greatly simplifies the task for financial institutions to map the API's data structures to their internal core banking and processing systems.

Navigating the Documentation: Hierarchy and Purpose

The Berlin Group publishes a suite of documents, each with a specific purpose. Understanding this hierarchy is essential for correct implementation.

Implementation Guidelines (IGs): These are the most critical documents for developers and architects. The IGs are the normative source of truth for the technical specification of each service. They contain the detailed definitions of API endpoints, HTTP methods, request and response message flows, and the precise data structures for the payloads. In the event of a discrepancy between an IG and another document (like an OpenAPI file), the Implementation Guidelines always prevail.
Operational Rules (ORs): While IGs define the "how" from a technical perspective, the Operational Rules define the "what" and "why" from a business and operational perspective. These documents are typically associated with services that are part of a larger scheme (like Request to Pay). They cover aspects such as participant roles and responsibilities, liability models, dispute resolution processes, and other business-level agreements.
OpenAPI Specifications (YAML files): These files provide a machine-readable representation of the APIs defined in the Implementation Guidelines. They are published in OpenAPI (formerly Swagger) format and are available in the Berlin Group's public GitLab repository. These files are an invaluable practical tool for developers, as they can be used to automatically generate client-side code, power interactive API documentation portals, and configure testing tools. However, it is imperative to remember that they are a non-normative convenience; the IGs remain the definitive specification.

Accessing the Resources

All official documentation and resources are made available to the public free of charge under a Creative Commons license, reflecting the open and collaborative nature of the initiative.

The Berlin Group Website: The official website (https://www.berlin-group.org/) is the primary distribution channel for all final, published documentation in PDF format, including the Implementation Guidelines, Operational Rules, and the Data Dictionary.
GitLab Repository: The OpenAPI (YAML) files are maintained in a public GitLab repository. This allows for version control, community issue tracking, and easy access for development teams and toolchains.

Table 5.1: Key Berlin Group openFinance Framework Documents

A new architect or developer approaching the framework for the first time can easily be overwhelmed by the sheer volume of documentation. This table serves as a quick-reference map to this ecosystem. By structuring the documents by service and type, it provides immediate clarity. For example, it makes it clear that to understand the technical implementation of Request to Pay, one must consult the "RTP Implementation Guidelines," whereas to understand the business rules and participant obligations, the "RTP Operational Rules" is the correct document. This structured overview is an invaluable aid for efficient learning and targeted implementation planning.

Document / Service Name	Document Type	Core Purpose
Core-PSD2 Compliance	Implementation Guidelines	Defines the normative technical specification for the core XS2A services (AIS, PIS, FCS).
Extended PIS V2	Implementation Guidelines	Defines the normative technical specification for advanced payment functionalities beyond core PIS.
Extended PIS V2	Operational Rules	Defines the business and operational rules for using extended payment services.
Extended AIS V2	Implementation Guidelines	Defines the normative technical specification for accessing non-payment accounts (e.g., savings, loans, securities).
Request to Pay V2	Implementation Guidelines	Defines the normative technical specification for the RTP messaging API.
Request to Pay V2	Operational Rules	Defines the business and operational rules for the RTP scheme.
Verification of Payee	Implementation Guidelines	Defines the normative technical specification for the beneficiary name and IBAN matching service.
Push Account Information V2	Implementation Guidelines	Defines the normative technical specification for subscribing to and receiving push notifications for account events.
Push Account Information V2	Operational Rules	Defines the business rules for push notification services.
Resource Status Notification	Implementation Guidelines	Defines the webhook-based normative technical specification for receiving asynchronous status updates on resources.
Discovery API	Implementation Guidelines	Defines the normative technical specification for programmatically discovering an ASPSP's capabilities.
Data Dictionary V2 Suite	Data Dictionary	Provides the single source of truth for all data element definitions across the framework.

Module 5 Quiz

1. If a developer finds a discrepancy between the Implementation Guidelines PDF and the OpenAPI (YAML) file for a specific service, which document should be considered the normative source of truth?

A. The OpenAPI (YAML) file, because it is machine-readable.
B. The Data Dictionary.
C. The Implementation Guidelines PDF document.
D. The Operational Rules document.

2. Where are the official OpenAPI (YAML) files for the openFinance framework maintained and distributed?

A. On the European Commission's official website.
B. In a public GitLab repository managed by the Berlin Group.
C. They are emailed to participants upon request.
D. On the websites of individual member banks.

3. What is the purpose of the openFinance Data Dictionary?

A. To define the business rules for payment schemes.
B. To list all participating banks in the Berlin Group.
C. To provide a glossary of acronyms like TPP and ASPSP.
D. To provide the single, authoritative definition for every data element and object used in the APIs.