Aanmaak van een XML bestand voor de aangifte van de lijst van ingezeten klanten en aantal verrichtingen. Ed. 2007

Transcriptie

1 Aanmaak van een XML bestand voor de aangifte van de lijst van ingezeten klanten en aantal verrichtingen Ed. 2007

2 Nationale Bank van België, Brussel Alle rechten voorbehouden. De reproductie van deze publicatie, geheel of gedeeltelijk, voor didactische of niet-commerciële doelstellingen is toegestaan mits vermelding van de bron.

3 Inhoudstafel 1. Inleiding 5 2. Uitsluitingen 6 3. Enquêtes waarvoor dit document van belang is 6 4. Identificatie van de tabel 7 5. Structuur van de tabel : identificatie van de kolommen 7 6. Voorbeeld van tabel 8 7. Beschrijving van de gegevens Administratieve gegevens Aangiftegegevens XML Definition Introduction General Principles Structure of content part About CSSR admin parameters XML Schema 'Client list' Dataset 'Client list' table Table Number Definition of a reported cell Sequential number Base All XML Schema definitions together Example Delivery 18 3

4

5 1. Inleiding De statistische aangiften gericht aan de NBB 1 worden elektronisch ingezameld met behulp van een Internet toepassing genaamd CSSR 2. Deze toepassing laat toe : het versturen van bestanden in XML formaat via ; het encoderen van de aangifte met behulp van een webformulier ; het beveiligd uploaden van bestanden met behulp van het webformulier in CSV formaat en het beveiligd uploaden van bestanden in XML formaat via Internet. Dit document beschrijft hoe u een XML bestand moet aanmaken voor de rapportering van de lijst van ingezeten klanten en het aantal verrichtingen. Het is belangrijk te weten dat de rapportering gebaseerd is op de volgende concepten : enquête, tabel, lijn, kolom en cel. Deze begrippen worden hierna toegelicht en aan de hand van een concreet voorbeeld geïllustreerd. 1 NBB : Nationale Bank van België 2 CSSR : Central Server for Statistical Reporting (Centrale server voor de statistische aangiften) 5

6 2. Uitsluitingen Voor de aanmaak van een bestand in CSV formaat dient men beroep te doen op de specifieke documentatie van iedere enquête. Voor de aanmaak van een XML bestand voor het rapporteren van de "activiteiten met het buitenland betreffende diensten, overdrachten en goederen", dient men beroep te doen op de adequate documentatie. 3. Enquêtes waarvoor dit document van belang is Enkel de enquêtes en de tabellen die hieronder worden geïdentificeerd, maken gebruik van de regels vermeld in dit document. IDENTICATIE VAN DE ENQUÊTE L01PKI NAAM VAN DE ENQUÊTE Lijst van ingezeten klanten en aantal verrichtingen 6

7 4. Identificatie van de tabel De enquête hierboven vereist de rapportering van één enkele tabel. Het gaat om tabel Het is noodzakelijk de vorm van deze tabel in elk rapport te respecteren. Tabel Lijst van ingezeten klanten en aantal verrichtingen 5. Structuur van de tabel : identificatie van de kolommen Iedere tabel is samengesteld uit lijnen en kolommen. In een tabel worden de verschillende records voorgesteld onder de vorm van opeenvolgende lijnen geïdentificeerd door opeenvolgende nummers. In een kolom zal men altijd het zelfde soort informatie vinden in de verschillende opeenvolgende records. De kolommen zijn bij conventie geïdentificeerd door een kolomnummer dat dezelfde betekenis heeft in iedere tabel. Een gegeven is opgenomen in een cel op de kruising van een lijn en een kolom. De kolommen dragen de volgende nummers : 99 Ondernemingsnummer (of BTW-nummer) van de klant 50 Aantal betalingen uitgevoerd naar het buitenland 60 Aantal betalingen ontvangen uit het buitenland 7

8 6. Voorbeeld van tabel Dit voorbeeld is afkomstig van de enquête L01PKI, tabel 0010 : "lijst van ingezeten klanten en aantal verrichtingen". KLANT ONDERNEMINGS-NUMMER AANTAL BETALINGEN UITGEVOERD NAAR HET BUITENLAND AANTAL BETALINGEN ONTVANGEN UIT HET BUITENLAND Lijn 1 van dit voorbeeld bevat een record betreffende de onderneming met nummer , die betalingen naar het buitenland heeft uitgevoerd en betalingen uit het buitenland heeft ontvangen. De cel gesitueerd op de kruising van lijn "1" en kolom "99" bevat de melding " ". Qua concepten heeft men : enquête : "L01PKI" tabel : "0010" lijn : "1" kolom : "99" waarde van de cel gedefinieerd door lijn "1" en kolom "99" : " ". 8

9 7. Beschrijving van de gegevens Het XML bestand bevat twee types gegevens : - administratieve gegevens en - aangiftegegevens. 7.1 Administratieve gegevens Deze gegevens dienen om de verstuurde bestanden te beheren, de afzender te identificeren, de inhoud te identificeren en te preciseren langs welk kanaal het ontvangstbewijs en het validatierapport naar de afzender moeten verstuurd worden. De gegevens zijn de volgende : GEGEVEN BESCHRIJVING FORMAAT VOORBEELD admin creation_time creatiedatum van het bestand yyyy-mm-dd hh:mm:ss " :05:32" sender kbo name ondernemingsnummer (BTW-nummer) of identificatie van de OKI naam van de contactpersoon adres van de contactpersoon Num(10) Tekst vrije tekst vrije tekst " " "BE CBF" "Durand Robert" "robert.durant@enterprise. be" telephone telefoonnummer vrije tekst "02/ " fax faxnummer vrije tekst "02/ " _response transform_response transform_acknowledgement adres voor het versturen van het ontvangstbewijs door de NBB het validatierapport van de aangifte moet ofwel in leesbaar formaat ('true") ofwel in html machineformaat ("false") verstuurd worden het ontvangstbewijs moet ofwel in door mens leesbaar formaat ('true") ofwel ofwel in XML formaat ("false") zijn. vrije tekst boolean : "true" "false" boolean : "true" "false" "robert.durant@entreprise. be" "true" "true" 9

10 secure_response GEGEVEN BESCHRIJVING FORMAAT VOORBEELD secure_acknowledgement het validatierapport moet ofwel versleuteld worden ('true") ofwel niet versleuteld worden ("false") - enkel voor de optie "strong secure". het ontvangstbewijs moet ofwel versleuteld worden ('true") ofwel niet versleuteld worden ("false") - enkel voor de optie "strong secure boolean : "true" "false" boolean : "true" "false" lang communicatietaal X(2) waarden : "nl" = Nederlands "fr" = Français "de" = Deutsch "en" = English xsi:type toepassingsdomein = betalingsbalans enquête identificatie van de enquête "false" 'true" "nl" tekst "PrtAcquisitionDataset " tekst " L01PKI" per rapporteringsperiode yyyy-mm " " tblnr identificatie van de tabel tekst "0010" bas rapporteringsbasis N(2) waarde "99" verplicht nihil preciseert of de transacties plaatsgehad hebben voor de periode boolean : "true" "false" "99" "true" (=niets aan te geven) 7.2 Aangiftegegevens De aangiftegegevens identificeren de cellen van elke tabel door de coördinaten van de lijnen en kolommen en registreren de inhoud van elke cel. GEGEVEN BESCHRIJVING FORMAAT VOORBEELD cell identificatie van het element cel - " " rub identificatie van de rapportlijn tekst "1" col identificatie van de kolom tekst "99" 10

11 8. XML Definition Revision History Revision May 2005 Table of Contents 8.1. Introduction 8.2. General Principles Structure of content part About CSSR admin parameters 8.3. XML Schema Client list Dataset Description XML Schema Definition Details Client list table Description XML Schema Definition Details Table Number Description XML Schema Definition Details Definition of a reported cell Description XML Schema Definition Details Sequential number Description XML Schema Definition Details Territorial Base Description XML Schema Definition Details Currency Code Description XML Schema Definition Details 8.4. All XML Schema definitions together 8.5. Example Delivery 11

12 8.1 Introduction The reporting for the 'Client list' is done via the Central Server for Statistical Reporting (CSSR). In this document only specific information related to the reporting itself is described. For general information about usage and functionality of CSSR, we refer to its website. 1. To give a quick summary, a cssr document is divided into two parts Admin part : containing definitions to control the processing of the transfer. This part is independent of the reporting it contains; Content part : an application specific part containing the actual data to report. It is the content part that is further described in this document. A first section will describe the general principles of how the data is structured. Then a detailed description is given of the XML Schema at which the <content> element of the XML document must satisfy. Small examples will be given with their associated definition of the part it highlights. A subsequent section will give the complete XML Schema, followed by a last section with an example of a valid cssr document containing a fictional reporting. 8.2 General Principles Structure of content part The data to report is organized into tables. A table is a two dimensional structure made of : rows identified by a numerical id columns. The tables are identified by reporting period the data relates to a table number, for example 0492 a territorial base - for example 10 <table per=" " tblnr="0010" bas="99" survey="l01pki">... </table> Cells are making up the crossing between a row and a column identified by a sequential number and a column code respectively. A cell can contain only one value. <table per=" " tblnr="0010" bas="99" survey="l01pki" > <cell rub="1" col="099"> </cell> <cell rub="1" col="050">500000</cell> <cell rub="1" col="060">500001</cell> </table> 1 ] by following Statistics > Declarations > Summary [2] in other words it is defined by mlns:xsd=" 12

13 If a declarer has no cells to report, then the table can be declared nihil by using the nihil attribute. The specific tables which are part of the' Client list' can variate in time and will be described in an additional document. In that, for each table, a table number and a list of columns is described. For each column the column code, the format and the semantics will be given About CSSR admin parameters Concerning some CSSR admin parameters, we have : As content_type = 'PrtAcquisitionDataset' The test parameter is not applicable As lang processing parameter may be used, as default 'English' is assumed. 8.3 XML Schema This schema needs definitions defined elsewhere in CSSR 'Client list' Dataset Description Definition of a 'Client list' dataset containing the tables to report:. The <content> element. <content xsi:type="prtacquisitiondataset" xmlns:xsi=" xmlns=" the table elements </content> XML Schema Definition <xsd:complextype xmlns:xsd=" name="prtacquisitiondataset"> <xsd:complexcontent> <xsd:extension base="cssr:content"> <xsd:sequence> <xsd:element name="table" type="cssr:prtacquisitiontable" maxoccurs="unbounded" /> </xsd:sequence> <xsd:attribute name="survey" type="xsd:string" use="required" /> </xsd:extension> </xsd:complexcontent> </xsd:complextype> Details Content : complex Inheriting elements and attributes from the definition of cssr:content ATTRIBUTES NAME TYPE REQUIRED DEFAULT VALUE DESCRIPTION survey xsd:string Yes Code to identify the survey 13

14 CONTENT : A SEQUENCE OF THE FOLLOWING ELEMENTS IN STRICT ORDER NAME TYPE MIN MAX DESCRIPTION table cssr:prtacquisitiontable 1 N 'Client list' table Description A table is the minimal unit of reporting, so when one cell must be updated the complete table must be send again. <table> element <table per=" " tblnr="0010" bas="99" survey="l01pki" nihil="false">... cell elements... </table> <table> element for a nihil declaration <table per=" " tblnr="0010" bas="99" survey="l01pki" nihil="true" /> XML Schema Definition <xsd:complextype xmlns:xsd=" name="prtacquisitiontable"> <xsd:sequence> <xsd:element name="cell" type="cssr:prtcell" minoccurs="0" maxoccurs="unbounded" /> </xsd:sequence> <xsd:attribute name="per" type="xsd:gyearmonth" use="required" /> <xsd:attribute name="tblnr" type="cssr:prttablenumber" use="required" /> <xsd:attribute name="bas" type="cssr:prtbase" use="required" /> <xsd:attribute name="nihil" type="xsd:boolean" default="false" /> </xsd:complextype> Details ATTRIBUTES NAME TYPE REQUIRED DEFAULT VALUE DESCRIPTION per xsd:gyearmonth Yes Reporting period to where the data refers to tblnr cssr:prttablenumber Yes bas cssr:prtbase Yes nihil xsd:boolean No false Used to denote that the table is a nihil declaration (true) or not (false). For a nihil declaration no cells may be reported. CONTENT : A SEQUENCE OF THE FOLLOWING ELEMENTS IN STRICT ORDER NAME TYPE MIN MAX DESCRIPTION cell cssr:prtcell 0 N 14

15 8.3.3 Table Number Description Identification of a table For example 0010 but not XML Schema Definition <xsd:simpletype xmlns:xsd=" name="prttablenumber"> <xsd:restriction base="xsd:string"> <xsd:pattern value="[0-9]{4}" /> </xsd:restriction> </xsd:simpletype> Details Restriction based on xsd:string Definition of a reported cell Description The cell is the smallest unit inside a table, to report. It corresponds to a single value. The <cell> element contains a value to report. Any alphanumerical string is allowed although some restriction applies which are defined in the application. Its format depends on the actual data type expected for the indicated column and table. The following table describes the possible data types. The format of the data types which corresponds to a definition in the XML Schema standard, are identical to the format described there. XML SCHEMA/DATA TYPE string decimal DESCRIPTION a finite sequence of characters. Only characters defined in the "ASCII extended character set" are accepted A real number with in theory infinite precision A point will be used as decimal separator and no grouping character will be used to separate thousands When according to the definition of the table, more decimals are reported then defined, they will be truncated. EXAMPLE In the validation process, based on the definition of the indicated column, restriction are applied on the actual maximal length of a string and the number of significant digits and the scale in case of a decimal. When a decimal is reported with less precision then the one expected according to the column definition, zeros are assumed for the higher precision digits. For example 1.1 will be treated as Some examples of the <cell> element : <cell rub="1" col="099"> </cell> <cell rub="1" col="050">500000</cell> <cell rub="1" col="060">500001</cell> 15

16 XML Schema Definition <xsd:complextype xmlns:xsd=" name="prtcell"> <xsd:simplecontent> <xsd:extension base="xsd:string"> <xsd:attribute name="rub" type="cssr:prtseqnumber" use="required" /> <xsd:attribute name="col" type="xsd:string" use="required" /> </xsd:extension> </xsd:simplecontent> </xsd:complextype> Details Content : simple Inheriting elements and attributes from the definition of xsd:string ATTRIBUTES NAME TYPE REQUIRED DEFAULT VALUE DESCRIPTION rub cssr:prtseqnumber Yes Sequential code col xsd:string Yes Column Code Sequential number Description A positive integer, starting from 1. Gaps between the numbering are allowed, its only purpose is to uniquely identify a reported item XML Schema Definition <xsd:simpletype xmlns:xsd=" name="prtseqnumber"> <xsd:restriction base="xsd:integer"> <xsd:minexclusive value="0" /> </xsd:restriction> </xsd:simpletype> Details Restriction based on xsd:integer Base Description XML Schema Definition <xsd:simpletype xmlns:xsd=" name="prtbase"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="10" /> <xsd:enumeration value="19" /> <xsd:enumeration value="99" /> </xsd:restriction> </xsd:simpletype> 16

17 Details Restriction based on xsd:string ENUMERATION, MUST BE ONE OF THE FOLLOWING VALUES VALUE DESCRIPTION 10 Territorial basis - excluded for L01PKI 19 Foreign seats - excluded for L01PKI 99 Reporting list of clients - only for L01PKI All XML Schema definitions together The following XML Schema contains all definitions for the content part of the 'Client list' reporting'. References to types for which the prefix is xsd, refers to the one made in the XML Schema specifications. 1 <xsd:schema xmlns:xsd=" targetnamespace=" elementformdefault="qualified" attributeformdefault="unqualified"> <xsd:complextype name="prtacquisitiondataset"> <xsd:complexcontent> <xsd:extension base="cssr:content"> <xsd:sequence> <xsd:element name="table" type="cssr:prtacquisitiontable" maxoccurs="unbounded" /> </xsd:sequence> <xsd:attribute name="survey" type="xsd:string" use="required" /> </xsd:extension> </xsd:complexcontent> </xsd:complextype> <xsd:complextype name="prtacquisitiontable"> <xsd:sequence> <xsd:element name="cell" type="cssr:prtcell" minoccurs="0" maxoccurs="unbounded" /> </xsd:sequence> <xsd:attribute name="per" type="xsd:gyearmonth" use="required" /> <xsd:attribute name="tblnr" type="cssr:prttablenumber" use="required" /> <xsd:attribute name="bas" type="cssr:prtbase" use="required" /> <xsd:attribute name="nihil" type="xsd:boolean" default="false" /> </xsd:complextype> <xsd:simpletype name="prttablenumber"> <xsd:restriction base="xsd:string"> <xsd:pattern value="[0-9]{4}" /> </xsd:restriction> </xsd:simpletype> <xsd:complextype name="prtcell"> <xsd:simplecontent> <xsd:extension base="xsd:string"> <xsd:attribute name="rub" type="cssr:prtseqnumber" use="required" /> <xsd:attribute name="col" type="xsd:string" use="required" /> </xsd:extension> </xsd:simplecontent> </xsd:complextype> <xsd:simpletype name="prtseqnumber"> 1 in other words it is defined by mlns:xsd=" 17

18 <xsd:restriction base="xsd:integer"> <xsd:minexclusive value="0" /> </xsd:restriction> </xsd:simpletype> <xsd:simpletype name="prtbase"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="10" /> <xsd:enumeration value="19" /> <xsd:enumeration value="99" /> </xsd:restriction> </xsd:simpletype> <xsd:simpletype name="isocurrency"> <xsd:restriction base="xsd:string"> <xsd:pattern value="[a-z]{3}" /> </xsd:restriction> </xsd:simpletype> </xsd:schema> 8.4 Example Delivery The following example is pure fictional and is not complete. It just demonstrates how cell values must be reported. <cssr_document xmlns=" <admin creation_time=" t10:20:00.000"> <sender kbo=" "> <contact> <name>mr. X</name> <communication xmlns:xsi=" xsi:type=" " /> <communication xmlns:xsi=" xsi:type="telephone" number="02/ " /> </contact> </sender> <receiver /> <processing_parameters> <transform_response>true</transform_response> </processing_parameters> <description>this is a user-description of the delivery</description> </admin> <content xmlns:xsi=" xsi:type="prtacquisitiondataset"> <table per=" " tblnr="0010" bas="99" survey="l01pki"> <cell rub="1" col="099"> </cell> <cell rub="1" col="050">500000</cell> <cell rub="1" col="060">500001</cell> <cell rub="2" col="099"> </cell> <cell rub="2" col="050">10</cell> <cell rub="2" col="060">20</cell> </table> </content> </cssr_document> 18

19 Voor meer informatie Wie meer informatie wenst over deze handleiding en de methodologie kan terecht bij de dienst Betalingsbalans Tel Fax bop@nbb.be Verantwoordelijke uitgever Jean-Jacques Vanhaelen Chef van het departement Algemene statistiek Nationale Bank België de Berlaimontlaan, 14 BE-1000 Brussel Illustraties: Gettyimages Photodisc Gettyimages Digital Vision Nationale Bank van België Opmaak: NBB Betalingsbalans Omslag : Prepress & Image NBB Gepubliceerd in oktober