3 WCO Data Model 4 XML Guidelines nd Edition 5 6

1

2

WCO Data Model 3

XML Guidelines 4

2nd

Edition 5

6

WCO Data Model XML Guidelines.

ii

7

Amendment History

Change Number

Description Page(s) affected

Version Effective Date

1 Release of 1st Edition of WCO Data Model XML Guidelines together with WCO Data Model Version 3

- 1st Edition

December 2009

2 Merge WCO XML Schema Customization Guide into this Guidelines.

18-29 2nd Edition

September 2012

3 Add usage of “Date Time” data type in the ”Basic Rules” section.

3

4 Add rules in the “Basic Rules” section on maintaining the message structure of a WCO XML Message.

3-4

5 Add the “Extensions” section. 7-10

6 Add the “Namespaces” section. 13-14

7 Add “Binary Object” data type, remove “Date” data type and add the “formatCode” XML attribute for “Date Time” data type in the Annex.

30-33

8 9


iii

TABLE OF CONTENTS 10 11 12 SECTION I BACKGROUND AND GENERAL PRINCIPLES .............................................. 1 13 1 Purpose .......................................................................................................................... 1 14 2 Background .................................................................................................................... 1 15 3 Basic Rules ..................................................................................................................... 2 16 4 Mini Message ................................................................................................................. 6 17 5 Extensions ...................................................................................................................... 7 18

5.1 Principles ................................................................................................................ 7 19 5.2 Mechanism ............................................................................................................. 7 20 5.3 Governing Rules ..................................................................................................... 8 21 5.4 Example Technical Solution ................................................................................... 9 22

6 Document Metadata ..................................................................................................... 11 23 7 Digital Signature ........................................................................................................... 12 24 8 Namespaces ................................................................................................................. 13 25

8.1 Namespace Assignment Convention .................................................................... 13 26 8.2 Use of Uniform Resource Name (URN) for Namespace ....................................... 13 27

9 Dictionary Entry Names (DENs) of WCO Data Elements .............................................. 15 28 9.1 Dictionary Entry Name Structure .......................................................................... 15 29 9.2 WCO DM DEN Naming Convention ..................................................................... 15 30

9.2.1 Authority ........................................................................................................... 16 31 9.2.2 Semantic Rules ................................................................................................ 16 32 9.2.3 Syntactic Rules ................................................................................................. 16 33 9.2.4 Lexical Rules .................................................................................................... 16 34 9.2.5 Uniqueness Rule .............................................................................................. 16 35 9.2.6 Assigned DENs ................................................................................................ 17 36

SECTION II WCO XML SCHEMA CUSTOMIZATION ...................................................... 18 37 10 Characteristics of the Sample XML Schemas ........................................................... 18 38

10.1 Purpose of XML Schema Customization .............................................................. 18 39 10.2 How Class and Class Attribute are represented in the Sample XML Schema ....... 19 40

11 Customizing the Sample XML Schema .................................................................... 20 41 11.1 Customization using the Graphical View of an XSD Editor. .................................. 21 42

11.1.1 Trim Class (non-leaf XML element) Operation .............................................. 21 43 11.1.2 Trim Class Attribute (leaf XML element) Operation ....................................... 23 44 11.1.3 Modify Cardinality Operation ......................................................................... 24 45

11.2 Customization using Text Editor ........................................................................... 25 46 11.2.1 Trim Class (non-leaf XML element) Operation .............................................. 25 47 11.2.2 Trim Class Attribute (leaf XML element) Operation ....................................... 27 48 11.2.3 Modify Cardinality Operation ......................................................................... 28 49

50 Annex: List of Attributes of Core Component Types used in WCO Data Model 51 52

53


iv

List of Tables 54 55 Table 1: Document names ................................................................................................... 14 56 57 List of Figures 58 Figure 1: Schema design to be followed in the Extension mechanism ................................... 8 59 Figure 2: Example of non-leaf and leaf XML elements (XSD Editor) .................................... 19 60 Figure 3: Example of non-leaf and leaf XML elements (Text Editor) ..................................... 20 61 Figure 4: Highlighting a non-leaf XML element (XSD Editor) ................................................ 21 62 Figure 5: Completing the operation (non-leaf XML element / XSD Editor) ............................ 22 63 Figure 6: Highlighting a leaf XML element (XSD Editor) ....................................................... 23 64 Figure 7: Complete the operation (leaf XML element / XSD Editor) ...................................... 24 65 Figure 9: Highlighting a non-leaf XML element (Text Editor) ................................................ 26 66 Figure 10: Complete the operation (non-leaf XML element / Text Editor) ............................. 27 67 Figure 11: Highlighting a leaf XML element (Text Editor) ..................................................... 28 68 Figure 13: Changing cardinality (Text Editor) ....................................................................... 29 69 70


Page 1 2nd

Edition Final 27-02-2012

SECTION I BACKGROUND AND GENERAL PRINCIPLES 71

72

1 Purpose 73 74 These Guidelines have been established to assist developers with a basic set of rules to 75 establish WCO XML messages. The Guidelines include definitions of what the final XML 76 message looks like. The Guidelines do not stipulate the use of any specific XML specification 77 such as DTD or XML Schema, these are technical methods to describe the structure and 78 which method used (if any), is left at the discretion of each implementer. Nevertheless, the 79 Guidelines contain a package of XML artefacts1 which are intended to illustrate and facilitate 80 the identification of information content. 81 82 83

2 Background 84 85 The Extensible Markup Language (XML) offers a way to define formats for exchanging 86 business data and enables the development of open and flexible applications for automating 87 electronic transactions over public networks. The function of the XML message is to carry 88 and convey information. 89 90 XML based applications have flourished based on non-standard semantics and structures 91 which limit the interoperability between and within different business domains. To overcome 92 these limitations, a consistent framework 2 for the development of XML messages is 93 established by referencing the open specifications developed through public processes such 94 as the Electronic Business Extensible Markup Language (UN/CEFACT/ebXML) Core 95 Components Technical Specification V2.01 (CCTS V2.01), ISO 11179 and UN/CEFACT 96 XML Naming and Design Rules V2.0. While it is recognized that these are evolving 97 standards and frameworks, it is however necessary to underscore the need for the 98 Guidelines to produce specifications that promote cross border and cross domain 99 interoperability, which is crucial for any e-business standard. 100 101

102 1 The XML artefacts are not intended for use in validating the information content. Therefore these

artefacts will not contain detailed restrictions placed on the data elements, e.g. lengths and code lists. 2 The framework covers the processes of deriving WCO XML messages from the WCO Data Model.


Page 2 2nd


3 Basic Rules 103 104 - The WCO Data Model is the only source for business rules, repetitions, formats, core data 105 types, code sets, class definitions and message structure. The business rules set by the 106 administration that is defining the subsets, will be the supplementary source. 107 108 - For all document assembly based on the WCO DM, the root class would become the root 109 element for the corresponding XML representation. 110 111 - The XML document shall be supplied with a namespace which provides process 112 information for XML parsers. An explanation on namespace assignment can be found 113 under title 8. 114 115 - The class name is the same as the XML tag name to be noted in UpperCamelCase, e.g. 116 TransportEquipment becomes <TransportEquipment>. 117 118 - The XML tag name for a class attribute is the concatenation of the Property Term and the 119 Representation Term of the Dictionary Entry Name of the class attribute in UpperCamelCase 120 with separators and spaces removed, e.g. the attribute with WCO Ref 029 “Border Transport 121 Means. Discharge Completed. Date Time” is represented as 122 <DischargeCompletedDateTime>. An explanation on Dictionary Entry Names of WCO data 123 elements can be found under title 9. When forming the XML tag names, the following rules 124 have to be observed: 125 126 - The Representation Term “Identifier” shall be abbreviated as “ID” in the XML tag. For 127 example, the tag name for WCO Ref 165 “Transport Equipment. Seal. Identifier” is 128 represented as <SealID>. 129 130 - If the word “Identification” is the final word of the Property Term and the Representation 131 Term is “Identifier”, then the word “Identification” shall be removed from the XML tag name. 132 If the word “Indication” is the final word of the Property Term and the Representation Term is 133 “Indicator”, then the word “Indication” shall be removed from the XML tag name. For 134 example, the tag name for WCO Ref R033 “Crew Member. Identification. Identifier” is 135 represented as <ID>. 136 137 - If the Representation Term is “Text”, “Text” shall be removed from the XML tag name. For 138 example, the tag name for WCO Ref R011 “Carrier. Name. Text” is represented as <Name>. 139 140 - In the case that the class is a sub-class of a super-class, the “missing” attribute names 141 should be taken from the super-class, e.g. class AdditionalDocument with WCO Ref D006, 142 the attribute name comes from super-class Document, i.e. type which becomes 143 <TypeCode>. 144 145 - The data types may be supplemented with metadata as specified in the UN/CEFACT Core 146 Components Technical Specification V2.01. For example: WCO Ref 131, Total Gross 147 Weight requires a value, say 250 and an optional Measurement Unit Code requires a value, 148 say KGM for kg. The XML attribute names listed in the column “Attribute Name” in the 149 Annex shall be used to represent the supplementary metadata. In this example, the data item 150 Total Gross Weight is represented by <TotalGrossMassMeasure 151 unitCode=”KGM”>250</TotalGrossMassMeasure>. In this Annex, all attributes that can be 152 used have been mentioned and the choice is left to the implementer and the needs of the 153 users of the XML specifications. 154


Page 3 2nd


155 - Regarding “Date Time” data type, the XML attribute “formatCode” is used to specify the 156 format of the date/time content. WCO XML and EDIFACT messages will both use codes 157 such as 102, 304 and 602 to represent the date time format CCYYMMDD, 158 CCYYMMDDHHMMSSZZZ and CCYY respectively. For example, the Arrival Date of a 159 Border Transport Means can be represented as <ArrivalDateTime formatCode="102">2007-160 10-15</ArrivalDateTime>. 161 162 - The XML element for a class shall contain XML elements for the associated classes only 163 which are directly associated to that class in order to maintain the message structure 164 presented in the class diagrams. In other words, the XML element for any class which is not 165 directly associated to a class shall not be presented under the XML element for that class. 166 e.g. <Commodity> shall not be presented under <Declaration> in the CRI message as 167 Commodity class is not directly associated to Declaration class in the CRI class diagram. To 168 include <Commodity> in the CRI message, XML elements for the intermediate classes, i.e. 169 <Consignment> and <ConsignmentItem>, shall be added as shown below: 170 171 <Declaration xmlns="urn:wco:datamodel:WCO:CRI:1"> 172 <Consignment> 173 <ConsignmentItem> 174 <Commodity> 175 … 176 </Commodity> 177 </ConsignmentItem> 178 </Consignment> 179 </Declaration> 180 181 - The XML elements for a class shall contain XML elements for the class attributes of that 182 class. In situation where the occurrence of the XML element for a class attribute is optional 183 (i.e. minimum occurrence is zero) and no data is applicable, the XML element for that class 184 attribute shall be omitted. In the following example, optional XML elements 185 <CountrySubDivisionID> and <CountrySubDivisionName> are omitted because both XML 186 elements do not store any data. The XML elements for other class attributes are presented 187 under <Address>. 188 189 As a result, 190 191 <Address> 192 <CityName>Brussels</CityName> 193 <CountryCode>BE</CountryCode> 194 <CountrySubDivisionID></CountrySubDivisionID> 195 <CountrySubDivisionName></CountrySubDivisionName> 196 <Line>Rue du Marché, 30</Line> 197 <PostcodeID>B-1210</PostcodeID> 198 </Address> 199 200 becomes 201 202 <Address> 203 <CityName>Brussels</CityName> 204 <CountryCode>BE</CountryCode> 205 <Line>Rue du Marché, 30</Line> 206 <PostcodeID>B-1210</PostcodeID> 207 </Address> 208 209

210


Page 4 2nd


- The XML elements for the associated classes to a class shall be presented under the XML 211 element for that class. In situation where the occurrence of the XML element for an 212 associated class is optional (i.e. minimum occurrence is zero) and there is no XML element 213 presented under the XML element for that associated class, the XML element for that 214 associated class shall be omitted. In the following example, <Pointer> which does not 215 contain any XML element shall be omitted. <Pointer> contains no XML element because the 216 XML elements, i.e. <DocumentSectionCode>, <SequenceNumeric> and <TagID>, which do 217 not store data are omitted. 218 219 Consequently, 220 221 <Amendment> 222 <ChangeReasonCode>112</ChangeReasonCode> 223 <Pointer> 224 <DocumentSectionCode></DocumentSectionCode> 225 <SequenceNumeric></SequenceNumeric> 226 <TagID></TagID> 227 </Pointer> 228 </Amendment> 229 230 becomes 231 232 <Amendment> 233 <ChangeReasonCode>112</ChangeReasonCode> 234 </Amendment> 235 236

237


Page 5 2nd


A sample segment for a CRI message with the basic rules applied is shown below: 238 239 <Declaration xmlns="urn:wco:datamodel:WCO:CRI:1"> 240 <ID>CRI0745557</ID> 241 <IssueDateTime formatCode=”304”>2007-10-11T09:00:00+08:00<IssueDateTime> 242 <TotalGrossMassMeasure unitCode=”KGM”>100000</TotalGrossMassMeasure> 243 <TypeCode>422</TypeCode> 244 <BorderTransportMeans> 245 <ArrivalDateTime formatCode=”102”>2007-10-15</ArrivalDateTime> 246 <BuiltYearDateTime formatCode=”602”>1991</BuiltYearDateTime> 247 <CargoFacilityLocationName>HKHKC</CargoFacilityLocationName> 248 <DepartureDateTime>2007-10-11T13:00:00+08:00</DepartureDateTime> 249 <FirstArrivalLocationID>HKHKC</FirstArrivalLocationID> 250 <ID>9365790</ ID> 251 <JourneyID>4550</JourneyID> 252 <Name>ABC GENERAL</Name> 253 <RegistrationNationalityID>KR</RegistrationNationalityID> 254 <ScheduledConveyanceID>8645663</ScheduledConveyanceID> 255 <StayID>07353415</StayID> 256 <TypeCode>1501</TypeCode> 257 <CrewMember> 258 <ID>K04587446</ID> 259 </CrewMember> 260 <CrewMember> 261 <ID>L56687427</ID> 262 </CrewMember> 263 <Master> 264 <BirthDateTime formatCode=”102”>1961-12-01</BirthDateTime> 265 <ID>H00456688999</ID> 266 <Name>PETER PAN</Name> 267 </Master> 268 </BorderTransportMeans> 269 <Carrier> 270 <ID>554688-001</ID> 271 <Name>ABC LTD</Name> 272 </Carrier> 273 … 274 </Declaration> 275 276 277

278


Page 6 2nd


4 Mini Message 279 280 Apart from the standard procedure messages for the WCO governmental procedures, 281 individual cross-border regulatory agency (CBRA) may impose local requirements over the 282 standard procedure messages. In such cases, not all WCO data elements and/or classes in 283 the standard procedure message are required and a subset or a trimmed-down version of 284 the standard procedure message, i.e. a mini message, would be needed. 285 286 Mini messages are also needed for meeting the requirements of the WCO SAFE Framework 287 of Standards (FoS). Under SAFE FoS, CBRAs should require the exporter/importer/carrier or 288 his/her agent to submit only particular sets of data elements 3 as advance electronic 289 declaration. Such advance electronic declarations include advance export goods declaration 290 (AEX), advance import goods declaration (AIM), advance export cargo declaration (ACRE) 291 and advance import cargo declaration (ACRI) which should be subsets based on EX12, IM12, 292 CRE and CRI respectively according to the ISCM Guidelines4. 293 294 The following basic steps shall be followed when deriving a mini message: 295 296 - Choose the appropriate standard procedure message to be trimmed down. For instance, 297 select EX12 as a base message for the mini message AEX. 298 - Retain the data elements and classes of the standard procedure message that are required 299 according to the business scenario. 300 - Purge those data elements and classes of the standard procedure message that are not 301 required. 302 303 304

305 3 Refer to pages I/17 - I/21 of the “ WCO Framework of Standards to Secure and Facilitate Global

Trade” published by WCO in June 2005. 4 Customs Guidelines on Integrated Supply Chain Management published by WCO in June 2004.


Page 7 2nd


5 Extensions 306 307 In international data exchange the use of extensions should be avoided. On national level it 308 may not be possible to avoid the use of extensions because not all the national requirements 309 can be added to the WCO Data model. 310 311

5.1 Principles 312 313 In case extensions are used the main things to note are: 314 315

1 Don’t use extensions for things supported by the language itself 316 2 Make sure extensions are optional outside its intended domain 317 3 Put extension elements in a different namespace 318 4 Encourage the use of schemas to define extension elements 319 5 Consider the impact of sending an “extended” message to a system that does not 320

understand the extension 321 6 Build systems so that they ignore extensions they do not understand 322 7 If possible, report that an extension has been ignored (as a warning, not an error) 323

324

5.2 Mechanism 325 326

An optional XML schema called Extended Data Set is proposed to be introduced. 327

328

This schema will include elements that are not in the WCO Data Model, especially those that 329 are not foreseen as data elements that would be commonly required by Members under a 330 Cross-border regulatory requirement. 331


Page 8 2nd


Data Set (ds:)

Unqualified Datatypes (udt:)Qualified

Dataypes (qdt:)

Extended

Data Set (eds:)

Document

<<import>> <<import>>

<<import>>

<<import>>

<<import>>

<<import>>

<<import>>

332

Figure 1: Schema design to be followed in the Extension mechanism 333

The colored components already exist in the data model schema specifications. The 334 Extended Data Set to the right side is the extension component proposed. Users of Extended 335 Data Set may harm the prospects of full interoperability between the family of users of WCO 336 Data Model. Therefore, the use of extensions is therefore not encouraged. 337

338

5.3 Governing Rules 339

340

1. Extended Data Set should be used with great care and should never be used for data 341 that is properly conveyed in standard WCO elements allowed elsewhere in the 342 document. 343

2. Extended Data Set should be used only as a last resort for data that cannot be 344 accommodated by the present structures of the WCO Data Model. 345

3. Use of Extended Data Set will require a special agreement between the users of the 346 specific customization set, requiring specific agreement between relevant parties. 347

4. The Extended Data Set will be governed by publication and maintenance procedures 348 outside the scope of WCO Data Model. 349

350 351

Page 9 2nd


5.4 Example Technical Solution 352 353 Technical solutions for extension and code list extension are described below. 354 355 Technical solution for XML extension is based on the design principles. There are four 356 extension examples regarding data elements and classes: 357 358

1. Include a localized data element e.g. "Consignment. Consolidation. Indicator" is 359 added to class "Consignment" 360

2. Include a localized class and its related data elements e.g. class "Tax Payer" is 361 added under class "Declaration" 362

3. Include a WCO data element which is not covered in a particular WCO procedure 363 document e.g. data element ID 156 "Border Transport Means. Departure. Date Time" 364 is added to EX1 365

4. Include a WCO class which is not covered in a particular WCO procedure document. 366 E.g. class "FreeTradeZone" is added to EX1 under class "GoodsShipment" 367

368 The following abstracted example illustrated how these extension examples are represented 369 in XML. Namespace prefix "eds" is used to identify the extended data elements and classes. 370 371 <Declaration xmlns="urn:wco:datamodel:HK:EX1:1" xmlns:eds="urn:wco:datamodel:HK:EDS:1" 372 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 373 xsi:schemaLocation="urn:wco:datamodel:HK:EX1:1 374 ..\maindoc\HK_EX1_1p0.xsd"> 375 <ID>0A93ID35W0BRXS</ID> 376 ... 377 <BorderTransportMeans> 378  379  381  382 <eds:DepartureDateTime formatCode="102" >2001-08-23</eds:DepartureDateTime> 383 ... 384 </BorderTransportMeans> 385 ... 386 <GoodsShipment> 387 <SequenceNumeric>1</SequenceNumeric> 388 <Consignment> 389 <SequenceNumeric>1</SequenceNumeric> 390  391  392  393 <eds:ConsolidationIndicator>true</eds:ConsolidationIndicator> 394 </Consignment> 395 ... 396  397  399  400 <eds:FreeTradeZone> 401 <eds:Name>Huangpu Free Trade Zone</eds:Name> 402 </eds:FreeTradeZone> 403 </GoodsShipment> 404 ... 405  406

Page 10 2nd


 407  408 <eds:TaxPayer> 409 <eds:Name>XYZ Co Ltd</eds:Name> 410 <eds:Contact> 411 <eds:Communication> 412 <eds:ID>2961-5000</eds:ID> 413 <eds:TypeID>TE</eds:TypeID> 414 </eds:Communication> 415 </eds:Contact> 416 </eds:TaxPayer> 417 </Declaration> 418 419

420 Regarding technical solution for code list extension, the same design principle is applied to 421 Code data type. An XML attribute "listName" which represents supplementary component 422 "Code. List Name. Text" is used to present the name of a list of codes. If the content of a 423 code is an extended code value, a value such as "Extended Code List of UNTDED 1001" is 424 assigned in the XML attribute. If the content is a standard code value (no matter standard 425 code list or extended code list is used), the XML attribute is not shown. 426 427 For instance, "Additional Document. Type. Code" which is used to distinguish different types 428 of additional documents adopts UNTDED 1001 code list. However, some documents such as 429 Consignment Note are not codified in the UNTDED code list. As such, extended code value 430 such as "CN" is needed as shown below: 431 432 <AdditionalDocument> 433 <ID>11928890044</ID> 434 <TypeCode listName="Extended TDED 1001 Code List">CN</TypeCode> 435 </AdditionalDocument> 436 437 For standard codes such as 741 which stands for Master Air Waybill in UNTDED code list, 438 XML attribute is not shown. 439 440 <AdditionalDocument> 441 <ID>A1087749844</ID> 442 <TypeCode>741</TypeCode> 443 </AdditionalDocument> 444 445 By adopting such approach, sender can identify extended codes used and prepare a 446 standard WCO XML message by removing XML tags with extended codes. 447 448 If sender and receiver agree to exchange extended codes, users can opt to use XML 449 attribute "name" which represents supplementary component "Code. Name. Text" to present 450 the textual equivalent of the code content. As such, the receiver can manipulate the 451 extended codes as textual description is given. For example, receiver knows the code 452 description of extended code "CN" is "Consignment Note" as shown below and can further 453 process the content: 454 455 <AdditionalDocument> 456 <ID>11928890044</ID> 457 <TypeCode listName="Extended TDED 1001 Code List" name="Consignment 458 Note">CN</TypeCode> 459 </AdditionalDocument> 460 461

462


Page 11 2nd


6 Document Metadata 463 464 Standard procedure messages and mini messages require metadata to differentiate 465 themselves from each other as well as providing supplementary information regarding the 466 messages. An XML envelope <DocumentMetadata> will be used to encapsulate the 467 required metadata as well as the standard procedure message or mini message itself. 468 Within the <DocumentMetadata> envelope, the metadata are represented by tag pairs which 469 include: 470

<WCODataModelVersion> : The WCO Data Model Version of the encapsulated WCO 471 Document type or a WCO Document type from which the encapsulated mini-message is 472 derived. e.g. 3.0. This tag pair is mandatory and will occur once. 473

<WCODocumentName> : The abbreviated name of the WCO Document type that is 474 encapsulated or from which the encapsulated mini-message is derived, e.g. IM1, CRE, etc. 475 The full list of abbreviated name of the WCO Document type can be found in table 1 476 Document names (see title 8). This tag pair is mandatory and will occur once. 477

<CountryCode> : The country, represented using ISO 3166-1 Country Code, that 478 specified this customized version of mini-message. This tag pair is optional and will occur 479 at most once. 480

<AgencyName> : The name of the Government agency that specified this customized 481 version of mini-message. This tag pair is optional and will occur at most once. 482

<AgencyAssignedCountrySubDivisionID> : The country subdivision, as assigned by the 483 corresponding Government agency, that this customized version of mini-message is 484 applicable. This tag pair is optional and will occur at most once. 485

<AgencyAssignedCustomizedDocumentName> : The abbreviated name, as assigned 486 by the aforesaid Government agency, of this customized version of mini-message , e.g. 487 HKAIM. This tag pair is optional and will occur at most once. 488

<AgencyAssignedCustomizedDocumentVersion> : The version number, as assigned by 489 the aforesaid Government agency, of this customized version of mini-message , e.g. 490 "Revision 7.1b". This tag pair is optional and will occur at most once. 491 The <DocumentMetadata> envelope shall be supplied with a namespace which provides 492 process information for XML parser. The namespace shall be 493 urn:wco:datamodel:WCO:DM:1. 494 495 The following example shows the structure of the XML message after encapsulating the 496 metadata using the <DocumentMetadata> envelope: 497 498 <DocumentMetadata xmlns="urn:wco:datamodel:WCO:DM:1" > 499 <WCODataModelVersion>3.0</WCODataModelVersion> 500 <WCODocumentName>AIM</WCODocumentName> 501 <CountryCode>HK</CountryCode> 502 <AgencyName>Customs and Excise Department</AgencyName> 503 <AgencyAssignedCustomizedDocumentName>HKAIM 504 </AgencyAssignedCustomizedDocumentName> 505 <AgencyAssignedCustomizedDocumentVersion>Revision 506 7.1b</AgencyAssignedCustomizedDocumentVersion> 507 <Declaration xmlns="urn:wco:datamodel:WCO:IM1:1"> 508 ... 509 </Declaration> 510 </DocumentMetadata> 511 512 513


Page 12 2nd


7 Digital Signature 514 515 In case authentication and non-repudiation for a WCO message is needed, the W3C 516 enveloping XML signature5 will be adopted. The WCO message including the metadata, as 517 a data object, will be signed. The XML signature will have the following structure: 518 519 <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> 520 <SignedInfo> 521 ... 522 </SignedInfo> 523 <SignatureValue/> 524 <KeyInfo> 525 ... 526 </KeyInfo> 527 <Object> 528 <DocumentMetadata xmlns="urn:wco:datamodel:WCO:DM:1" > 529 ... 530 </DocumentMetadata> 531 </Object> 532 </Signature> 533 534 The 5 outer tag pairs (i.e. <Signature>, <SignedInfo>, <SignatureValue>, <KeyInfo>, 535 <Object>) will follow the syntax and semantics of the W3C enveloping signature. 536 537 538

539 5 For details please refer to http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/

http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/


Page 13 2nd


8 Namespaces 540 541 Namespace is used to differentiate concept within a domain, the universal name 542 (combination of namespace and local name) of different concept should be different. If the 543 concept is the same, the universal name and hence the namespace and the local name 544 should be the same. For example, if Commodity in IM1 and CRE are the same, then the 545 namespace of IM1 and CRE should be the same. If Commodity in IM1 and CRE are 546 different, then the namespace of IM1 and CRE should be different. 547 548 Depending on how the concept is treated, i.e. if classes and data elements across 549 documents are the same or not, there are basically three options when deciding how 550 namespace is used in WCO documents. These options would be: 551 552 a) All documents in WCO DM use the same namespace 553 b) Same document family use the same namespace 554 c) Each document use its own namespace 555

556 In option C, classes and data elements in each document have different semantic meaning, 557 e.g., Declaration class in IM1 and CRE are different. This option is proven to be easy to 558 handle and is already widely used. This is why it has been decided to recommend the use of 559 option C. Document names as well as respective abbreviations are listed in table 1. 560 561 Below explains the Namespace Assignment Convention for assigning namespace to WCO 562 Data Model (WCO DM) Instance Document6. Recommendations of the UN/CEFACT XML 563 Naming and Design Rules V2.07 were adopted as far as possible. 564 565

8.1 Namespace Assignment Convention 566 567 The namespace for an Instance Document is defined using the “xmlns” attribute in the root 568 element”. 569 570

8.2 Use of Uniform Resource Name (URN) for Namespace 571 572 Namespaces are usually represented in the form of Uniform Resource Names (URNs). 573 574 The syntax of the URN that represents the Namespace for Instance Document is 575 urn:wco:datamodel:[customsAdministration]:[name]:[version] 576 where 577

[customsAdministration] = either the string “WCO” or the ISO 3166-1 Alpha-2 Country 578 Code of individual Customs Administration; 579

[name] = the abbreviated name of the Instance Document in table 1 or the abbreviated name 580 of the customized document assigned by individual Customs Administration; 581 [version] = major version number; sequentially assigned, starting with the number 1. 582 583 For example, the namespace for WCO IM1 Instance Document is 584 6 A WCO DM Instance Document is the document, as defined in the WCO Data Model XML

Guidelines, to be exchanged between different stakeholders. 7 Available at: http://www.uncefactforum.org/ATG/atg_news_download.htm

http://www.disa.org/cefact-groups/atg/downloads/XML%20Naming%20And%20Design%20Rules%20V2.0.pdf


http://www.uncefactforum.org/ATG/atg_news_download.htm


Page 14 2nd


urn:wco:datamodel:WCO:IM1:1. 585 586 The namespace for the localized Hong Kong IM1 Instance Document is 587 urn:wco:datamodel:HK:IM1:1 588 589 590

Document Name Abbreviated Name for Data Modelling purposes WCO Overall Declaration DEC Response RES for Customs Procedures specified in Kyoto Convention Import declaration IM Export declaration EX

Cargo Report Import CRI Cargo Report Export CRE Conveyance Report CONV

Transit TRT for Customs Procedures specified in WCO SAFE FoS Advance Export Goods Declaration AEX Advance Import Goods Declaration AIM Advance Export Cargo Declaration ACRE Advance Import Cargo Declaration ACRI

Table 1: Document names 591

592 593 594 595

596


Page 15 2nd


9 Dictionary Entry Names (DENs) of WCO Data Elements 597 598 599 One or more Dictionary Entry Names (DENs) are assigned to every WCO data element to 600 facilitate adoption of XML as exchange format of the WCO Data Model (WCO DM). In short, 601 some components of each DEN will be transformed into the names of XML tags according to 602 the recommendations of the UN/CEFACT XML Naming & Design Rules V2.08 as far as 603 possible. 604 605

9.1 Dictionary Entry Name Structure 606 607 According to the ISO 11179-5:20059 Naming and Identification Principles, a DEN may 608 consist of an object class term, a property term, a representation term, and qualifier term(s). 609 The object class term represents an object, which is a set of ideas, abstractions or things in 610 the real world. The property term represents a characteristic common to all members of an 611 object. The representation term describes the form of representation of the characteristic 612 being described, e.g. Name, Amount, Text, Number, etc. Lastly, qualifier term(s) may be 613 attached to object class term, property term, and representation term if necessary to 614 distinguish one data element from another. 615 616 Adhering to ISO 11179-5:2005, three DEN components have been assigned to each WCO 617 data element. The WCO derived the DEN object class terms from the corresponding WCO 618 DM object class names. Similarly, the DEN property terms are derived from the 619 corresponding WCO DM object class attributes. And the representation terms are derived 620 from the form of representation of the corresponding WCO data elements. 621 622 The WCO needs not and does not assign any qualifier terms because the name of any 623 object class in WCO DM is already unique, and the name of any class attribute belonging to 624 the same object class is also unique. 625 626

9.2 WCO DM DEN Naming Convention 627 628 Taken into consideration the recommendations about naming conventions stated in the ISO 629 11179-5:2005 and naming rule principles adopted by UN/CEFACT Core Components 630 Technical Specification CCTS v2.0110), the naming convention as stipulated in sub-sections 631 3.1 through 3.6 has been formulated. The naming convention is developed for and applied to 632 WCO DM version 3 and beyond. 633 634

635 8 Available at: http://www.uncefactforum.org/ATG/atg_news_download.htm

9 Available at: http://standards.iso.org/ittf/PubliclyAvailableStandards/c035347_ISO_IEC_11179-

5_2005(E).zip 10

Available at: http://www.unece.org/cefact/ebxml/CCTS_V2-01_Final.pdf


http://standards.iso.org/ittf/PubliclyAvailableStandards/c035347_ISO_IEC_11179-5_2005(E).zip




http://www.unece.org/cefact/ebxml/CCTS_V2-01_Final.pdf


http://www.uncefactforum.org/ATG/atg_news_download.htm





Page 16 2nd


9.2.1 Authority 636 637 The WCO is the authority that assigns names and enforces the naming convention. 638 639

9.2.2 Semantic Rules 640 641

(a) For each DEN, there will be one and only one object class term. The name of the 642 corresponding object class in the WCO DM shall form the object class term in the DEN. 643

(b) For each DEN, there will be one and only one property term. The name of the 644 corresponding class attribute of the corresponding object class in the WCO DM shall form 645 the property term in the DEN. 646

(c) For each DEN, there will be one and only one representation term. The 647 representation term shall describe the form of representation as stated in the definition of the 648 corresponding WCO data element. 649

9.2.3 Syntactic Rules 650 651

(a) The object class term shall occupy the first (leftmost) position in the DEN. 652 (b) The property term shall occupy the next position in the DEN. 653 (c) The representation term shall occupy the last position in the DEN. 654

655

9.2.4 Lexical Rules 656 657

(a) The object class term, property term and representation term shall be separated by 658 a dot and single space. For example, “Commodity. Brand Name. Text”. 659

(b) All the words in the names of the object class terms, property terms, and 660 representation terms shall begin with capital letter. Name parts and words in multi-word 661 terms shall be separated by spaces. For example, the WCO DM object class attribute 662 “customsStatus” shall become the DEN property term “Customs Status”. 663

(c) Nouns shall be used in singular form only unless the concept itself is in plural form. 664 For example, “Customs” is allowed whereas “Items” is not allowed. Verbs (if any) shall be in 665 present tense. 666

(d) The allowable abbreviations in object class term, property term and representation 667 term are ID, UCR, LPCO and ISPS. 668 669

9.2.5 Uniqueness Rule 670 671 The property terms of all DENs that share the same object class term shall be different. The 672 uniqueness will also ensure that the names of XML tags derived are not violating the W3C 673 XML syntax rules. 674 675

676


Page 17 2nd


9.2.6 Assigned DENs 677 678 The assigned DENs are recorded under the following four new columns in the WCO data 679 elements spreadsheet: 680 681

(a) WCO DM Dictionary Entry Name 682 (b) Object Class Term 683 (c) Property Term 684 (d) Representation Term 685

686 It is noted that WCO DM Dictionary Entry Name is a concatenation of the object class term, 687 property term, and representation term separated by the symbol “.”. 688 689

690


Page 18 2nd


SECTION II WCO XML SCHEMA CUSTOMIZATION 691

10 Characteristics of the Sample XML Schemas 692 693 Sample XML schemas for WCO Data Model are provided to CBRAs for reference in 694 constructing their own schemas. These sample XML schemas are built using the Russian 695 Doll model approach, which allows easy customization of the schemas through trimming off 696 unnecessary class / class attributes to suit the specific requirements of individual CBRAs. 697 698 The sample XML schemas have made use of UN/CEFACT Unqualified Data Type XML 699 Schema to represent the Core Component Technical Specifications (CCTS) Core Data 700 Types of the WCO data elements, thereby facilitating interoperability between WCO XML 701 instance documents derived from these schemas with instance documents derived from 702 UN/CEFACT XML schemas and UBL (Universal Business Language) XML schemas. 703 704 The sample XML schemas also make use of a Data Set (DS) schema as the building block. 705 The DS schema defines each WCO data element in a named type (named complex type or 706 named simple type). This ensures that all the XML leaf elements in the sample XML 707 schemas must be WCO data elements. 708 709 The illustrations provided in these guidelines are based on the XML tool “Altova XML Spy”. 710 Users may adjust the instructions in order to apply the method in their own tools. In fact a 711 simple text editor can also be used to carry out the method described in these guidelines, 712 which is also illustrated below. 713 714

10.1 Purpose of XML Schema Customization 715 716 The sample XML schemas are derived from WCO Data Model class diagrams which 717 represent B2G (Business to Government) /G2B (Government to Business) documents 718 involved in particular customs procedures. As the B2G/ G2B overall model contains the 719 maximum set of common data elements used by all CBRAs, not all data elements in each 720 B2G / G2B document will be needed by an individual government agency. Those extra data 721 elements will become XML elements not used in the XML schema and may lead to 722 unnecessary confusion. Besides, individual administration may need to restrict the cardinality 723 of class or class attribute to reflect their local requirements, e.g. local regulation stipulates 724 that only one border transport means information in a Cargo Report Import procedure is 725 needed. 726 727 The purpose of this document is to illustrate how individual CBRA can make reference to and 728 customize the sample XML schemas to suit their specific needs, by means of trimming off 729 unnecessary classes/class attributes, and modifying the cardinality of classes/class 730 attributes. 731 732

733


Page 19 2nd


10.2 How Class and Class Attribute are represented in the Sample XML Schema 734 735 In the sample XML schema, a class is represented by a non-leaf XML element whereas a 736 class attribute is represented by a leaf XML element. Figure 2 shows how these are 737 represented using the graphical features of an XSD Editor11 software and Figure 3 shows 738 the representation when using a Text Editor. 739 740

741

Figure 2: Example of non-leaf and leaf XML elements (XSD Editor) 742

743 11

XSD editor is a software for creating XML Schemas .

Class attribute

Class


Page 20 2nd


744

Figure 3: Example of non-leaf and leaf XML elements (Text Editor) 745

746

11 Customizing the Sample XML Schema 747 748 After determining the requirements of their XML messages, individual CBRAs can use the 749 following three operations to customize the sample XML schema to match their 750 requirements. The three operations include: (1) trim class operation, (2) trim class attribute 751 operation, and (3) modify cardinality operation. The following sections will illustrate how to 752 perform these operations using an XSD Editor (graphical view), and then illustrate how these 753 can be performed using a Text Editor. Nevertheless, readers can also use other suitable 754 tools to carry out the operations. 755 756

757

Class attribute

Class


Page 21 2nd


11.1 Customization using the Graphical View of an XSD Editor. 758 759

11.1.1 Trim Class (non-leaf XML element) Operation 760 761 1. Open the XML schema with XSD Editor in the graphical view or tree view. 762 2. Browse to the XML element representing the class and highlight it by clicking the XML 763 element as shown in Figure 4. 764 765

766

Figure 4: Highlighting a non-leaf XML element (XSD Editor) 767

768 769


Page 22 2nd


3. Press delete key to complete the operation as shown in Figure 5. 770

771

Figure 5: Completing the operation (non-leaf XML element / XSD Editor) 772

773 774


Page 23 2nd


11.1.2 Trim Class Attribute (leaf XML element) Operation 775 776 1. Open the XML schema with XSD Editor Graphical view or tree view. 777 2. Browse to the XML element representing the class attribute and highlight it by clicking 778 the XML element as shown in Figure 6. 779 780

781

Figure 6: Highlighting a leaf XML element (XSD Editor) 782

783 784


Page 24 2nd


3. Press delete key to complete the operation as shown in Figure 7. 785 786

787

Figure 7: Complete the operation (leaf XML element / XSD Editor) 788

789

11.1.3 Modify Cardinality Operation 790 791 1. Open the XML schema with XSD Editor in the graphical or tree view. 792 2. Browse to the XML element representing the class/class attribute and highlight it by 793 clicking the XML element as shown in Figure 8. 794 3. Change the value of minOcc and maxOcc in the Details Window as circled in Figure 8. 795 796

797

Figure 8: Changing cardinality (XSD Editor) 798


Page 25 2nd


799 Note: The value of minOcc must be smaller than or equal to the value of maxOcc. For 800 compatibility, the value of minOcc should be larger than or equal to the original value 801 whereas the value of maxOcc should be smaller than or equal to the original value. 802

11.2 Customization using Text Editor 803 804

11.2.1 Trim Class (non-leaf XML element) Operation 805 806 1. Open the XML schema with Text Editor. 807 2. Search the XML element which represents the class. 808 3. Select the text between <xsd:element …> and the corresponding </xsd:element> which 809 should be at the same level of the <xsd:element …>, as shown in Figure 9. 810 811


Page 26 2nd


812

Figure 9: Highlighting a non-leaf XML element (Text Editor) 813

814


Page 27 2nd


4. Press delete key to complete the operation as shown in Figure 10. 815 816

817

Figure 10: Complete the operation (non-leaf XML element / Text Editor) 818

819

11.2.2 Trim Class Attribute (leaf XML element) Operation 820 821 1. Open the XML schema with Text Editor. 822 2. Search the XML element which represents the class attribute. 823 3. Select the text between <xsd:element …> and the corresponding </xsd:element> which 824 should be at the same level of the <xsd:element …>, as shown in Figure 11. 825


Page 28 2nd


826

Figure 11: Highlighting a leaf XML element (Text Editor) 827

828 4. Press delete key to complete the operation as shown in Figure 12. 829 830

831

Figure 12: Complete the operation (leaf XML element / Text Editor) 832

833

11.2.3 Modify Cardinality Operation 834 835 1. Open the XML schema with Text Editor. 836 2. Search the XML element representing the class/class attribute. 837 3. Change the value of minOccurs and maxOccurs, as circled in Figure 13. 838


Page 29 2nd


839

Figure 13: Changing cardinality (Text Editor) 840

841 Note: The value of minOccurs must be smaller or equal to the value of maxOccurs. For 842 compatibility, the value of minOccurs should be larger than or equal to the original value 843 whereas the value of maxOccurs should be smaller than or equal to the original value. There 844 will be no minOccurs/maxOccurs XML attribute when the occurrence is 1. 845 846 847

Annex

List of Attributes of Core Component Types used in WCO Data Model Ref. Core

Component Type Name

Data Type of Core Component Type

Core Component Type Description Attribute Name Attribute Description Mandatory / Optional

Attribute Data Type

Remarks

Page 30

1 a) Amount Decimal A number of monetary units specified

in a currency where the unit of the

currency is explicit or implied.

currencyID The currency of the

amount.

Mandatory String Use UN/ECE Rec. 9

code list. The

UN/ECE Rec. 9 is

also published as ISO

4217.

2 a) Binary

Object

Binary A set of finite-length sequences of

binary octets.

format The format of the

binary content.

Optional String

b) mimeCode The mime type of the

binary object.

Optional String Reference IETF RFC

2045, 2046, 2047.

c) encodingCode Specifies the decoding

algorithm of the binary

object.


2045, 2046, 2047.

d) characterSetCo

de

The character set of

the binary object if the

mime type is text.


2045, 2046, 2047.

e) uri The Uniform Resource

Identifier that identifies

Optional String

Annex


Component Type Name



Attribute Data Type

Remarks

Page 31

where the binary object

is located.

f) fileName The filename of the

binary object.

Optional String

3 a) Code String A character string (letters, figures, or

symbols) that for brevity and/or

language independence may be used

to represent or replace a definitive

value or text of an attribute together

with relevant supplementary

information.

listID The identification of a

list of codes.

Optional String

b) listAgencyID An agency that

maintains one or more

lists of codes.

Optional String Use UN/EDIFACT

data element 3055

code list.

c) listAgencyName The name of the

agency that maintains

the list of codes.

Optional String

d) listName The name of a list of Optional String

Annex


Component Type Name



Attribute Data Type

Remarks

Page 32

codes.

e) listVersionID The version of the

code list.

Optional String

f) name The textual equivalent

of the code content

component.

Optional String

g) languageID The identifier of the

language used in the

code name.

Optional String

h) listURI The Uniform Resource


where the code list is

located.

Optional String

i) listSchemeURI The Uniform Resource


where the code list

scheme is located.

Optional String

4 a) DateTime String A particular point in the progression formatCode The format of the Optional String Use UN/EDIFACT

Annex


Component Type Name



Attribute Data Type

Remarks

Page 33

of time together with the relevant

supplementary information.

date/time content data element 2379

code list. Examples of

codes to be used:

102 (CCYYMMDD),

304

(CCYYMMDDHHMM

SSZZZ) and 602

(CCYY)

5 a) Identifier String A character string to identify and

distinguish uniquely, one instance of

an object in an identification scheme

from all other objects in the same

scheme together with relevant

supplementary information.

schemeID The identification of the

identification scheme.

Optional String

b) schemeName The name of the


Optional String

c) schemeAgencyI

D

The identification of the


Optional String Use UN/EDIFACT

data element 3055

Annex


Component Type Name



Attribute Data Type

Remarks

Page 34

the identification

scheme.

code list.

d) schemeAgency

Name

The name of the


the identification

scheme.

Optional String

e) schemeVersionI

D

The version of the


Optional String

f) schemeDataUR

I

The Uniform Resource


where the identification

scheme data is

located.

Optional String

g) schemeURI The Uniform Resource


where the identification

scheme is located.

Optional String

6 a) Indicator String A list of two mutually exclusive

Annex


Component Type Name



Attribute Data Type

Remarks

Page 35

Boolean values that express the only

possible states of a property.

7 a) Measure Decimal A numeric value determined by

measuring an object along with the

specified unit of measure.

unitCode The type of unit of

measure.

Mandatory String Use UN/ECE Rec.20

code list

8 a) Numeric Decimal Numeric information that is assigned

or is determined by calculation,

counting, or sequencing. It does not

require a unit of quantity or unit of

measure.

9 a) Percent Decimal Numeric information that is assigned




measure.

10 a) Quantity Decimal A counted number of non-monetary

units possibly including fractions.

unitCode The unit of the quantity Mandatory String Use UN/ECE Rec.20

code list

Annex


Component Type Name



Attribute Data Type

Remarks

Page 36

12) Rate Decimal Numeric information that is assigned




measure.

13) Text String A character string (i.e. a finite set of

characters) generally in the form of

words of a language.

languageID The identifier of the

language used in the

content component.

Optional String

3 WCO Data Model 4 XML Guidelines nd Edition 5 6

Documents

Transcript of 3 WCO Data Model 4 XML Guidelines nd Edition 5 6