Harmonization and Enhancement of identifier types

[rybtim]

Description

Current identifier type list is not sufficient for the first Go-Live of sharing members.

Recommended to align with the "roll out plan" EU first.

Pool / Gate data model and APIs MUST be adapted to include a way for downloading the identifier types accepted by Catena-X and valid / mandatory for each country. It MUST be ensured in the sharing process, that only those identifier types are used in the business partners. Identifier type list MUST be included as annex in the Pool and Gate API standardization documents, so that it is clear which identifier types are accepted by Catena-X. Portal onboarding and own company data maintenance UIs COULD present this list as a drop-down to select the correct identifier type, when adding an identifier to the business partner.

Current Implementation

In the current (24.05/24.08) implementation, the identifier types can already be uploaded and downloaded to/from the BPDM Pool. They are used in both BPDM Pool and Gate, to mark the identifier of a business partner, legal entity, or address. Currently, there are 26 identifier types defined in the reference implementation / consortial INT environment.

Endpoints

• GET /v6/identifier-types

• POST /v6/identifier-types

Examples:

{
  "technicalKey": "EU_VAT_ID_DE",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "Value added tax identification number",
  "details": [
    {
      "country": "DE",
      "mandatory": true
    }
  ]
},
{
  "technicalKey": "DE_BNUM",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "Handelsregister (HRB)",
  "details": [
    {
      "country": "DE",
      "mandatory": false
    }
  ]
}

Requested Implementation

Data Model Enhancement & Harmonization

• a transliterated name, abbreviation and transliterated abbreviation must be added
• the format of the data, especially the technical key, has been defined and harmonized in syntax and semantic (see below)
• it must be validated by the implementation whether a known identifier type code is used for the technical key

The name must be the local name for the identifier used in the country. If the identifier type is used in multiple countries (e.g. EU-wide or world-wide) it must be the English name. The name must be mandatory. It should not use abbreviations.

The abbreviation is the local short form of the identifier type used in that country. If the identifier type is used in multiple countries (e.g. EU-wide or world-wide) it must be the English short form. The abbreviation must be mandatory.

Both name and abbreviation are required in the local form, to make sure the exact identifier type is meant and not an artificial abstraction, which possibly includes several different identifier types. Note that sometimes it's OK to use the English name and abbreviation, if it's a real-world abstraction for several countries, like the EU VAT ID.

The transliterated name and abbreviation must be the latinised form of name and abbreviation, according to standardized transliteration rules using only Latin letters without diacritics ([A-Za-z]). This is important especially for non-latin based scripts, like Greek, Cyrillic. However, transliterated name and abbreviation must also be included for latin based scripts with diacritics where diacritics should to be replaced by the Latin letters without diacritics.

The technical key must have the form: {scope}_{transliterated abbreviation}. The scope can be either an ISO 3166-1 2-letter country code or the abbreviation of an institution / system (like GLEIF, DUNS). Both scope and abbreviation are capitalized. If the scope or abbreviation includes spaces, they must be replaced by underscores.

Content Correction / Enhancement

• 3 of the 26 existing identifier types are invalid and must be removed / replaced (EU_VAT_ID_CH, EU_VAT_ID_GB, EU_VAT_ID_NO).
• additional codes for the EU, probably also for the whole of Europe, must be added which would mean a total of around 100 identifier types; the list is currently being worked on

Examples

{
  "technicalKey": "DE_EU_VAT_ID",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "European Union Value-added Tax Identification Number",
  "abbreviation": "EU VAT ID",  
  "transliteratedName": "",
  "transliteratedAbbreviation": "",
  "details": [
    {
      "country": "DE",
      "mandatory": true
    }
  ]
},
{
  "technicalKey": "DE_HRB",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "Handelsregister Abteilung B Nummer",
  "abbreviation": "HRB",
  "transliteratedName": "",
  "transliteratedAbbreviation": "",
  "details": [
    {
      "country": "DE",
      "mandatory": false
    }
  ]
},
{
  "technicalKey": "BG_EIK",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "Единен идентификационен код (по БУЛСТАТ)",
  "abbreviation": "ЕИК",
  "transliteratedName": "Edinen identifikatsionen kod (po BULSTAT)",
  "transliteratedAbbreviation": "EIK",
  "details": [
    {
      "country": "BG",
      "mandatory": false
    }
  ]
}

Impact

• BPDM Gate and Pool API

• Portal

  Additional information

• [ ] I'm willing to contribute to this feature

[jjeroch]

Attention @rybtim : Upcoming PI Planning Preparation

As we gear up for the forthcoming PI Planning session, it is crucial that all features under consideration align with our established Feature Quality Standards and Definition of Done (DoD) guidelines. To ensure your feature is thoroughly prepared and stands a strong chance of being prioritized, please provide comprehensive documentation that includes the following components:

1. Feature Summary: An executive overview that encapsulates the essence and objectives of the feature.
2. Change Description:
   • High-Level Overview: A succinct synopsis of the proposed changes and their overarching impact.
   • Detailed Analysis: An in-depth exploration of the specific alterations, including a clear exposition of the anticipated impact on existing systems.
3. Impacted Components: A list identifying all system components that will be affected by the feature implementation, accompanied by a brief explanation of the nature of the impact.
4. Acceptance Criteria: A set of clearly defined conditions that must be met for the feature to be considered complete and acceptable.
5. Test Scenarios: A detailed outline of test cases that cover all functional paths of the feature to ensure robust validation and verification.
6. Risks/Dependencies

Please note that any feature submissions lacking these essential elements will not be eligible for consideration in the upcoming PI Planning. It is imperative that your documentation is both thorough and precise to facilitate a smooth and effective planning process.

Please let me know in case you have any questions

[Grand-Thibault]

@rybtim please add more to the description

[stephanbcbauer]

Was presented in the open planning ⇾ please clarify if the feature has an impact on the portal

[Sebastian-Wurm]

Expert group will be kicked off next week. Gaia-X identifiers and related mapping in portal will be discussed there. Hanno Focken to provide Gaia-X contacts.

[stephanbcbauer]

As discussed in open planning, this feature will stay in Inbox until there is a handover to the related expert group. Please reach out, when the handover is done and the expert group is ready to work on the feature. Please also keep my comment in mind.

Don't just start with the feature. Clarification is still needed. Same for:

• 600

• 599

• 643

Thx

[stephanbcbauer]

@rybtim added you as assignee because we need a contact person for every feature.

[stephanbcbauer]

Didn't think about it before, but since the feature is still in Inbox, the open decision label is not needed. Opinions?

[Sebastian-Wurm]

Didn't think about it before, but since the feature is still in Inbox, the open decision label is not needed. Opinions?

It's OK, please leave the Prep-PI13, though.

[zygokaktus]

test

[Sebastian-Wurm]

List to consider: European Central Bank - Ana Credit National Identifier -> List of National Identifiers in Annex

[Sebastian-Wurm]

Current Implementation

In the current (24.05/24.08) implementation, the identifier types can already be uploaded and downloaded to/from the BPDM Pool. They are used in both BPDM Pool and Gate, to mark the identifier of a business partner, legal entity, or address. Currently, there are 26 identifier types defined in the reference implementation / consortial INT environment.

Endpoints

• GET /v6/identifier-types

• POST /v6/identifier-types

Examples:

{
  "technicalKey": "EU_VAT_ID_DE",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "Value added tax identification number",
  "details": [
    {
      "country": "DE",
      "mandatory": true
    }
  ]
},
{
  "technicalKey": "DE_BNUM",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "Handelsregister (HRB)",
  "details": [
    {
      "country": "DE",
      "mandatory": false
    }
  ]
}

Requested Implementation

Data Model Enhancement & Harmonization

• a transliterated name, abbreviation and transliterated abbreviation must be added
• the format of the data, especially the technical key, has been defined and harmonized in syntax and semantic (see below)
• it must be validated by the implementation whether a known identifier type code is used for the technical key

The name must be the local name for the identifier used in the country. If the identifier type is used in multiple countries (e.g. EU-wide or world-wide) it must be the English name. The name must be mandatory. It should not use abbreviations.

The abbreviation is the local short form of the identifier type used in that country. If the identifier type is used in multiple countries (e.g. EU-wide or world-wide) it must be the English short form. The abbreviation must be mandatory.

Both name and abbreviation are required in the local form, to make sure the exact identifier type is meant and not an artificial abstraction, which possibly includes several different identifier types. Note that sometimes it's OK to use the English name and abbreviation, if it's a real-world abstraction for several countries, like the EU VAT ID.

The transliterated name and abbreviation must be the latinised form of name and abbreviation, according to standardized transliteration rules using only Latin letters without diacritics ([A-Za-z]). This is important especially for non-latin based scripts, like Greek, Cyrillic. However, transliterated name and abbreviation must also be included for latin based scripts with diacritics where diacritics should to be replaced by the Latin letters without diacritics.

The technical key must have the form: {scope}_{transliterated abbreviation}. The scope can be either an ISO 3166-1 2-letter country code or the abbreviation of an institution / system (like GLEIF, DUNS). Both scope and abbreviation are capitalized. If the scope or abbreviation includes spaces, they must be replaced by underscores.

Content Correction / Enhancement

• 3 of the 26 existing identifier types are invalid and must be removed / replaced (EU_VAT_ID_CH, EU_VAT_ID_GB, EU_VAT_ID_NO).
• additional codes for the EU, probably also for the whole of Europe, must be added which would mean a total of around 100 identifier types; the list is currently being worked on

Examples

{
  "technicalKey": "DE_EU_VAT_ID",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "European Union Value-added Tax Identification Number",
  "abbreviation": "EU VAT ID",  
  "transliteratedName": "",
  "transliteratedAbbreviation": "",
  "details": [
    {
      "country": "DE",
      "mandatory": true
    }
  ]
},
{
  "technicalKey": "DE_HRB",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "Handelsregister Abteilung B Nummer",
  "abbreviation": "HRB",
  "transliteratedName": "",
  "transliteratedAbbreviation": "",
  "details": [
    {
      "country": "DE",
      "mandatory": false
    }
  ]
},
{
  "technicalKey": "BG_EIK",
  "businessPartnerType": "LEGAL_ENTITY",
  "name": "Единен идентификационен код (по БУЛСТАТ)",
  "abbreviation": "ЕИК",
  "transliteratedName": "Edinen identifikatsionen kod (po BULSTAT)",
  "transliteratedAbbreviation": "EIK",
  "details": [
    {
      "country": "BG",
      "mandatory": false
    }
  ]
}

[Sebastian-Wurm]

Note that there is currently only little impact to the Portal, namely in the GXDCH mapping, if identifier type codes change. The list of identifier types currently being prepared will include a mapping to the existing GXDCH identifier types.

[MG2023-RB]

Hello Sebastian, thanks. I assume that the format of each identifier is already defined (you stated "must be defined"). I would add that the format is validated by service providers.

[Sebastian-Wurm]

Hello Sebastian, thanks. I assume that the format of each identifier is already defined (you stated "must be defined"). I would add that the format is validated by service providers.

I added that in the description.

[Sebastian-Wurm]

Note that for 24.12 it's OK to have only identifier types relevant for Legal Entity and Address. We know that identifier types for sites also exist, but we want to evaluate this first thoroughly and provide this in a future feature.

[nicoprow]

The requirement looks good to me.

Just a note, we currently have no default list of identifier types in the reference implementation. A clean deployment of the reference implementation leads to an empty list of of identifier types.

[stephanbcbauer]

After a brief consultation with Sebastian, the feature is set to 'backlog' status. Associated committer is also fine with it.

[maximilianong]

@Sebastian-Wurm will invite for a refinement meeting and will post the information here and in Matrix chat.

[nicoprow]

@Sebastian-Wurm

The technical key should constist of the scope and transliterated abbreviation. However, a transliterated abbreviation is not mandatory. From the examples and the context I guess, the idea is that the technical key should take the abbreviation if there is no transliterated abbreviation.

I didn't read an explicit requirement, but it looks to me it is implied that a transliterated name and abbreviation must be given if the name and abbreviation do not completely consist of latin letters. Would that be correct?

[Sebastian-Wurm]

@Sebastian-Wurm

The technical key should constist of the scope and transliterated abbreviation. However, a transliterated abbreviation is not mandatory. From the examples and the context I guess, the idea is that the technical key should take the abbreviation if there is no transliterated abbreviation.

I didn't read an explicit requirement, but it looks to me it is implied that a transliterated name and abbreviation must be given if the name and abbreviation do not completely consist of latin letters. Would that be correct?

That's correct. The assumption is, that if there is no transliterated abbreviation, the abbreviation is sufficient to form the technical key / code as it only contains letters from [A-Za-z]. Alternatively, we can also make the transliterated abbreviation mandatory. Then we would fill it with basically the same value as in the abbreviation, if the abbreviation only contains letters from [A-Za-z]. But that would be somewhat redundant.

So, the form of the technical key could be described maybe better as: "{scope}_{transliterated abbreviation}|{abbreviation}, where abbreviation is taken if transliterated abbreviation is not given. The scope is either an ISO 3166-1 2-letter country code or the (transliterated) abbreviation of an institution / system (like GLEIF, DUNS). Both, scope and (transliterated) abbreviation must be capitalized. If the scope or abbreviation includes spaces, they must be replaced by underscores."

[stephanbcbauer]

@rybtim if this feature is still valid, and we want to have it in the planning for 25.03 the milestone needs to be deleted. Would it be possible for you to also upgrade it to the new feature template

Is the feature already fully refined? If yes, the Backlog status can stay, if not, please set it to Inbox and refine it, with the new template. Thank you very much.

[stephanbcbauer]

Some hints from Release Management (@ther3sa) and Tractus-X Project Lead (@stephanbcbauer)

• Please add contributor/committer
• Please add missing sections from the feature template

[Sebastian-Wurm]

Committers / Contributers: @SujitMBRDI @nicoprow