ROM1 - revenue.ie

1 Revenue Online Services rom1 Schema Notes Page 1 of 40 Revenue Online Services Schema Notes rom1 Last Updated 23/02/2015 Document Version Revenue Online Services rom1 Schema Notes Page 2 of 40 CONTENTS Contents .. 2 0 Document Information .. 3 Synopsis .. 3 Change History .. 3 Abbreviations used in this Document .. 3 Additional Information .. 4 1 Schema Overview .. 5 Supported Functions .. 5 Schemas .. 5 Business Overview .. 5 Return of Oil Movement Processes .. 5 2 SUBMIT .. 6 rom1 6 rom1 SubmissionResponse .. 8 3 rom1 Types .. 9 GeneralDetails Type .. 9 Declarant Type .. 9 Type .. 10 ProductBalances Type .. 11 ProductBalance Type.

2 11 InwardMovements Type .. 13 SupplierRecord 13 OutwardMovements Type .. 15 NonTradeAggType Type .. 16 NonTradeCustomerRecord Type .. 17 NonTraderType Type .. 17 NonTraderOutOfStateType Type .. 18 NonTradeLineItemType Type .. 19 TradeCustomerRecord Type .. 20 rom1 Common Types .. 21 Shipment .. 21 TraderType .. 22 UnlicencedTraderGroup .. 22 TraderOutOfStateType .. 23 LineItemTransType .. 24 TaxRefGroup .. 24 OutOfStateTaxRefGroup Type .. 25 LineItemType .. 25 CommonNameAddressGroup Type .. 26 Appendix 1 rom1 Types .. 27 Enumerated Types .. 27 Simple Types .. 28 Appendix 2 ROS Common Types .. 30 Enumerated Types .. 30 Appendix 3 Error Messages.

3 31 Appendix 4 Product Balances .. 33 Appendix 5 - Sample 34 Authorised Warehousekeeper .. 34 Distributor .. 36 Forecourt Retailer .. 39 Revenue Online Services rom1 Schema Notes Page 3 of 40 0 DOCUMENT INFORMATION Synopsis This document contains all the validation rules, which must be passed to enable a successful upload onto ROS for rom1 return. This is a draft version and may be subject to further changes. Change History Table 1: Change History Version Number Section Affected Change Description Date Initial Revision 10/07/2012 Section , , Appendix 1 Replace positive3 simple type with positive4 to represent a range 1-9999 for NumDeliveries, NumCustomers elements 04/09/2012 Add Section Add rom1 SubmissionResponse element 24/09/2012 Table 15, 19, 25, 31, 38 Clarification to Produce Names (DERV ) updated to (DERV - ROAD DIESEL) and (ULTRA_LOW_SULPHER) updated to (ULTRA_LOW_SULPHER_MARKED_GAS_OIL) 06/11/2012 Appendix 1 Table 33 Update CountyType list 29/11/2012 Tables 23,24,27 Table 25 Clarification regarding Tax numbers.

4 Removal of Country under the LineItemTransType. 30/11/2012 Table 21 Table14 Table 8 Updated description of SAD and eAD. Update to the maximum number of NonTradeCustomerRecord. Update description of AutoFuelLicence and MarkedFuelLicence. 07/12/2012 , Nil Declarations added to Inward Movements and Outward Movements Specify that In State supplier must use Excise Licence number. Specify that In State customer must use Excise Licence number. 30/10/2014 Table 5 Removed instruction to mark Forecourt Retailer outward movements as Nil Declaration. A value of either true or false is acceptable. 20/01/2015 Table 33 Updated incorrect county codes from version Updated text description for InNilDeclaration and OutNilDeclaration 23/02/2015 Abbreviations used in this Document Abbreviation Description rom1 Return of Oil Movement XML eXtensible Mark-up Language eAD Electronic Administrative Document SAD Single Administrative Document Revenue Online Services rom1 Schema Notes Page 4 of 40 Additional Information Information on existing ROS 3rd party webservices is available here.

5 Revenue Online Services rom1 Schema Notes Page 5 of 40 1 SCHEMA OVERVIEW This document contains the element definitions, field & cross-field dependency rules for the Revenue rom1 schema. The element descriptions include the following: Name Type Required (in the request) Description. o Required data format. o Restricted data values where appropriate. o Maximum and minimum values where applicable. o Dependent elements other elements that are optional but required in certain circumstances if other elements are not provided. The element rules must be fulfilled for Revenue to accept and process the request. Supported Functions The following functions are supported using the rom1 schema.

6 These map to rom1 business processes as outlined in Section 2 below. Submit rom1 Return Schemas There is one primary schema containing definitions for rom1 requests and responses. There are also a number of supporting schemas that have custom types defined. Table 2 below outlines details of these schemas. Table 3 rom1 Schemas Name File Namespace Prefix New or Modified Reference rom1 Requests & Responses N/A New Section 2 ROS Types ros: Existing Appendix 2 The new and modified schemas will be made available on the ROS website as part of the rom1 software release. Business Overview Return of Oil Movement Processes Submit rom1 Return Third parties can submit a rom1 Return through ROS.

7 Only one rom1 return can be included in a single request. The information that needs to be submitted for each Return is dependant on a number of factors. These include whether the Return is for an Auto-Fuel licence, Marked Fuel licence, or both, whether the trader type is an Authorised Warehousekeeper, Distributor or Forecourt Retailer and whether Suppliers/Customers Excise Licence numbers are known. Full details on the validation rules can be found in Section 3. Please also note the following points in relation to submitting returns: Only one rom1 Return can be made for an excise licence number combination (Auto-Fuel and/or Marked Fuel) in any given filing period. To notify Revenue of a rom1 Return, a rom1 request needs to be submitted.

8 If the rom1 submission is unsuccessful, the submission fails validation, a list of Errors will be returned. See Appendix 3 for more details on error messages. Please note that if validation fails for any of the submitted data then the entire submission will fail and the rom1 will not be processed. The validation error needs to be resolved and the rom1 re-submitted. Revenue Online Services rom1 Schema Notes Page 6 of 40 2 SUBMIT rom1 Request Figure 1 rom1 request A rom1 request contains all of the information required to submit a rom1 Return to Revenue. The request contains a number of mandatory and optional elements. Some fields may be deemed mandatory/optional based on certain conditions ( the Trader Type of the declarant, or the type of Excise Licence that the Return is being filed for).

9 These conditions will be clearly indicated in the field description. The attributes/elements of a rom1 Request are listed below. Table 4 rom1 request attributes Name Type Minimum Value/Length Maximum Value Required (Y/N) Description / Validation Unit Text Characters Y The unit of volume for mineral oil within the Return. Can be either litre or hectolitre. Warehousekeepers, Distributors and Forecourt Retailers submit returns in litres. See Appendix 1 for more detail formversion Numeric 1 1 Y Version of the form Form version must be 1 language Text Character 1 1 Y The language used in the form. Can be set to E (English) or G (Gaelige) See Appendix 1 for more detail product Text Characters 1 20 Y The name of the software/software company used to generate the return.

10 Table 5 rom1 request elements Name Type Required (Y/N/C) Description / Validation GeneralDetails GeneralDetails Y General details for the submission. This includes the declarants excise licence number(s), the type of trader they are, and the filing period associated with the Return. See Section below for details. ProductBalances ProductBalances Y Contains a list of balances for the product types associated Revenue Online Services rom1 Schema Notes Page 7 of 40 Name Type Required (Y/N/C) Description / Validation with the Return. Balances represent the opening and closing stock balances for oil products within a monthly return period. Product types included in this list are dependant on the type of excise licence number (Auto-Fuel or Marked Fuel) and trader type.