Development of new API Resources

An organisation (‘submitting organisation’) wishing to develop a new ISO 20022 compliant resource must submit an API Resource Business Justification (API BJ). 

The API BJ is checked for completeness by the ISO 20022 RA.

The API BJ should explain the purpose of the development, the applicable business processes, business transactions (business areas) involved and include a committed timeline for the development.

The RA will first verify that the content is not a duplicate of a similar BJ and second that it could not be achieved through amendments of existing API resources, i.e. the maintenance process, and will thereafter forward the BJ to the responsible ISO 20022 registration bodies as defined in this process for them to provide comments.

In case of comments, the submitting organisation will address those in, if need be multiple, updated versions of the BJ until all justified and reasonable comments have been addressed. Final BJ approval is implicit, if the responsible ISO 20022 registration bodies have no further justified and reasonable comments within four weeks following the last version of BJ.

Following approval of the API BJ, the RA will provide the tools that allow for easy access to the latest version of the ISO 20022 Repository to the submitting organisation with detailed instructions on the deliverables required (see step 3 below). The tool is provided free of charge.

The RA provides the submitting organisation with a clear description of the required deliverables, the materials necessary to set up the required modelling environment and a 'compliance checklist' of rules to observe to develop ISO 20022 compliant API resources.

The submitting organisation wishing to register resources selects the relevant ISO 20022 message elements in the ISO 20022 Repository to design the API resources. If the desired elements are not available, new elements are created following the ISO 20022 API modelling guidelines.

The submitting organisation develops the ISO 20022 compliant API resources and part 1 of the Resource Definition Report within the timeframe indicated in its request for registration (API BJ). If a delay is expected, the submitting organisation promptly informs the RA with a new submission date.

The resources and the report are submitted to the RA that checks the compatibility according to the ISO 20022 modelling guidelines before submission to the responsible ISO 20022 registration bodies for evaluation.  Upon detection of non-compliance, the RA returns to the submitting organisation with a quality report and works with the submitting organisation that is responsible for applying correcting measures until a compliant submission is achieved.

Important: The APIs themselves are out of scope of this process.

When the submission is compliant and complete, the API resource components are registered by the RA before evaluation and appear as ‘provisionally registered’ in the Repository.

The RA generates the evaluation documentation and sends it to the responsible ISO 20022 registration bodies. The documentation consists of:

• A Resource Definition Report (RDR) describing the resources. The RDR is made of three parts:
  • Part 1 is provided by the submitting organisation to describe the business transactions (state diagram, interaction diagram…) for which the proposed resources will be used.
  • Part 2 is a detailed description of the contents of each resource and its definition. It is generated by the RA.
  • Part 3 is a description of the business model components used to create the API resource components. It is generated by the RA.
• JSON Schemas (and ideally a Microsoft Excel spreadsheet) as an equivalent specification of RDR part 1 in a machine-readable format describing the resources.

On top of the evaluation documentation provided by the RA, the submitting organisation is expected to give an introductory presentation to the ISO 20022 registration bodies entrusted with the evaluation and may propose additional documentation to further facilitate the evaluation.

The responsible ISO 20022 registration bodies evaluate each submission. Any correction needs identified during the evaluation cycle will be returned to the submitting organisation. The submitting organisation shall decide either to motivate its decision if changes proposed by the evaluating ISO 20022 registration bodies are not retained, or otherwise to correct and resubmit, potentially, through repeated evaluation cycles, if needed.

The responsible ISO 20022 registration bodies verify that the submission is within the scope expressed in the corresponding request and evaluate the candidate ISO 20022 compliant API resources from a business standpoint before they are officially accepted and published as ISO 20022 compliant resources. The responsible ISO 20022 registration bodies proceed with the evaluation and approve the API resources in maximum one calendar month from receipt of their submission.

Following the positive evaluation and approval, the RA publishes the ISO 20022 compliant API resources on www.iso20022.org as JSON Schemas together with the Resource Definition Reports.

At any time during the registration process and until the resources are approved by the responsible ISO 20022 registration bodies, the submitting organisation may decide to withdraw or suspend its submission by informing the RA and providing the reason for such decision.