Standardize VAT number

[pvdbosch]

VAT number is a commonly used type, which is currently in Draft status. Can we graduate it, and create a datatype (~ OpenAPI type)?

The current description in FedVoc is based on: https://en.wikipedia.org/wiki/VAT_identification_number

A value added tax identification number or VAT identification number (VATIN) is an identifier used in many countries, including the countries of the European Union, for value added tax purposes.

In the EU, a VAT identification number can be verified online at the EU's official VIES website. It confirms that the number is currently allocated and can provide the name or other identifying details of the entity to whom the identifier has been allocated. However, many national governments will not give out VAT identification numbers due to data protection laws.

The full identifier starts with an ISO 3166-1 alpha-2 (2 letters) country code (except for Greece, which uses the ISO 639-1 language code EL for the Greek language, instead of its ISO 3166-1 alpha-2 country code GR) and then has between 2 and 13 characters. The identifiers are composed of numeric digits in most countries, but in some countries they may contain letters.

Foreign companies that trade with non-enterprises in the EU may have a VATIN starting with "EU" instead of a country code, e.g. Godaddy USA EU826010755 and Amazon USA AWS EU826009064.

For the VatNumber OpenAPI type, we can check that the first two characters are letters, but restricting the length could be risky. Non-EU VAT numbers can be longer, and EU vat number length might evolve.

[pvdbosch]

from the wikipedia page, some non-EU VAT numbers allow special characters:

• Mexico: MXP&G851223B24
• Venezuela: VEJ-30595991-8

Besides the first two letters having to be uppercase (country code) I'd keep any additional structure validation outside of the API contracts, so compatibility isn't that easily broken. Some APIs may choose to provide structure validation specific to its context (e.g. limiting to EU vat numbers only) that can be changed without breaking the contract.

[pvdbosch]

Proposed type:

VatNumber:
  description: A value added tax identification number or VAT identification number (VATIN)
  type: string
  pattern: "^[A-Z]{2}.+$" # 2 letter uppercase country, followed by 1 or more characters

update: spaces might be used as separator, so allowing whitespace

[pvdbosch]

Will be added as data type in Organization ontology. I'll add it to next version of belgif-organization-identifier in OpenAPI

Add in description or comments that its the international number, with two first letters the ISO 3166-1 Alpha2 code.

[pvdbosch]

Updated type, added as beta in belgif-organization-identifier

    VatNumber:
      description: An international Value-Added Tax Identification Number or VAT Identification Number (VATIN)
      type: string
      pattern: "^[A-Z]{2}.+$" # Starts with ISO 3166-1 alpha-2 country code, followed by 1 or more characters in a country-specific format

[pvdbosch]

No comments by REST design WG. Feedback requested at FPS Fin.

[lievenja]

I checked internally with specialists at FPS Fin. They confirm the proposed pattern (= start with ISO 3166-1 alpha-2 country code, followed by 1 or more characters in a country-specific format) is OK for international VAT Numbers. Whatever comes after the ISO-code needs to be generic. Internally there is no additional validation on these VAT Numbers.

For EU VAT Numbers however there is some internal validation by a module provided by EU (Taxud), but I don't know the details as this is not that straightforward.

[pvdbosch]

Thanks for the feedback, @lievenja .The EU vat number validation rules might also be too complex or volatile in order to set them in stone in API contracts. I'll go ahead and release this definition then.

[pvdbosch]

Definition from glossarium DmfA:

•   Label xml : VATNbr
•   Intitulé FR/NL : NUMÉRO DE TVA / BTW-NUMMER
•   Description FR /NL : Numéro TVA qui identifie de manière unique une entreprise. / BTW-nummer dat op eenduidige wijze een onderneming identificeert.
•   Domaine de définition FR / NL : 
Les positions 1 et 2 correspondent au préfixe du pays d’établissement de l’entreprise. 
Les positions de 3 à 30 sont composées de chiffres et/ou de lettres.
Il est à noter que la structure d’un numéro de TVA intracommunautaire est différente pour chaque pays membre de l’UE. /

De posities 1 en 2 komen overeen met de prefix van het vestigingsland van de onderneming. 
De posities 3 tot 30 bestaan uit cijfers en/of letters.
Merk op dat de structuur van een intracommunautair BTW-nummer anders is voor elke EU-lidstaat.
•   Longueur : 30 positions
•   Pattern uniquement pour les glossaires DmfA et non pour tous les glossaires : ([A-Z]{2}[A-Za-z0-9]{0,28})

Though also in agreement that the last part of the pattern would better be omitted from the OpenAPI definition.

[pvdbosch]

I propose to update FedVoc (comment column of vatNumber) as such:

New

An international Value-Added Tax Identification Number or VAT Identification Number (VATIN).

It is used in many countries, including the countries of the European Union, for value added tax purposes. In the EU, a VAT identification number can be verified online at the EU's official VIES website. It confirms that the number is currently allocated and can provide the name or other identifying details of the entity to whom the identifier has been allocated.

The full identifier starts with an ISO 3166-1 alpha-2 (2 letters) country code (except for Greece, which uses the ISO 639-1 language code EL for the Greek language, instead of its ISO 3166-1 alpha-2 country code GR) followed by a character string in a country-specific format.

Foreign companies that trade with non-enterprises in the EU may have a VATIN starting with "EU" instead of a country code, e.g. Godaddy USA EU826010755 and Amazon USA AWS EU826009064.

In Belgium, the VAT Identification Number is the same as the organization's enterprise number prefixed by "BE".

Old

A value added tax identification number or VAT identification number (VATIN) is an identifier used in many countries, including the countries of the European Union, for value added tax purposes.

In the EU, a VAT identification number can be verified online at the EU's official VIES website. It confirms that the number is currently allocated and can provide the name or other identifying details of the entity to whom the identifier has been allocated. However, many national governments will not give out VAT identification numbers due to data protection laws.

The full identifier starts with an ISO 3166-1 alpha-2 (2 letters) country code (except for Greece, which uses the ISO 639-1 language code EL for the Greek language, instead of its ISO 3166-1 alpha-2 country code GR) and then has between 2 and 13 characters. The identifiers are composed of numeric digits in most countries, but in some countries they may contain letters.

Foreign companies that trade with non-enterprises in the EU may have a VATIN starting with "EU" instead of a country code, e.g. Godaddy USA EU826010755 and Amazon USA AWS EU826009064.

Changes

• first line aligned with openapi
• removed "However, many national governments will not give out VAT identification numbers due to data protection laws.". I think this only holds for non-EU countries and it's already implied by first line "identifier used in many countries"
• specify "followed by a character string in a country-specific format" instead of a non-robust generalization ("then has between 2 and 13 characters. The identifiers are composed of numeric digits in most countries, but in some countries they may contain letters.")
• Added "In Belgium, the VAT Identification Number is the same as the organization's enterprise number prefixed by "BE".

If OK, we can also change it from "Draft" to "Standard" and set "inOpenAPI" to "yes".

[pvdbosch]

released the openapi schema in https://github.com/belgif/openapi-organization-identifier/releases/tag/v1.1.0

[MarcBruyland]

Issue is closed as decided in the functional workgroup on 2024-04-12.

[pvdbosch]

@MarcBruyland , could you update the vatNumber row with column "inOpenApi" set to "yes"?

[MarcBruyland]

done