Modernized e-file Transmission File Structure and XML Schemas TIGERS Meeting 13 August 2003 Last Updated: 08/05/2003 Transmission File Structure An e-file transmission file is a MIME multi-part document that u Conforms to SOAP 1.1 With Attachments standard u Consists of l A SOAP Envelope (also called Transmission Envelope), which contains A Header - the Transmission Header A Body - the Transmission Manifest lone or More s Each Attachment is a self-contained Return, which is one MIME multi-part document (nested within another, the transmission file) l MIME Boundaries and Content Headers 2 1
Return Structure A Return is a MIME Multipart document A Return contains XML Documents and optional Binary Attachments u XML Structure l Return Header contains information that is common for the whole return lreturn Data contains all of the XML return documents u Binary Attachments are non-xml documents 3 Transmission File Transmission File MIME Multi-Part Content Header MIME Part Boundary and Content Header SOAP Envelope SOAP Header SOAP Body MIME Part boundary MIME Part boundary MIME Part boundary MIME Part boundary MIME Multi-Part End boundary Transmission Header Transmission Manifest Tax Return MIME Multi-Part Content Header MIME Part Boundary and Content Header Return Return Header Return Data MIME Part Boundary and Content Header Binary Attachment MIME Part Boundary and Content Header Binary Attachment MIME Part Boundary and Content Header Binary Attachment MIME Multi-Part End boundary 4 2
Sample Transmission File MIME-Version: 1.0 Content-Type: Multipart/Related; boundary=<mime1120boundary>; type="text/xml" Content-Description: This is a sample structure of a transmission file. X-eFileRoutingCode: MEF --<MIME1120Boundary> Content-Type: "text/xml"; charset=utf-8 Content-Transfer-Encoding: 8bit Content-Location: <Envelope1120> <?xml version="1.0" encoding="utf-8"?> <SOAP:Envelope xmlns=http://www.irs.gov/efile xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:efile="http://www.irs.gov/efile" xsi:schemalocation="http://schemas.xmlsoap.org/soap/envelope/../message/soap.xsd http://www.irs.gov/efile../message/efilemessage.xsd"> <SOAP:Header> <efile:transmissionheader transmissionversion="2002v01">. <SOAP:Body> <efile:transmissionmanifest count= 3"><Reference contentlocation="99009920031210123456" electronicpostmark="2003-03-27t08:20:00-05:00" > </SOAP:Envelope> --<MIME1120Boundary> (return data, composed by the ERO, goes here) --<MIME1120Boundary>-- (return data, composed by the ERO, goes here) --<MIME1120Boundary>-- (return data, composed by the ERO, goes here) MIME BOUNDARY MIME Multi-part Content Header MIME Multi-part Content Header Each return is a MIME multi-part document 5 Transmission Envelope SOAP Envelope SOAP Header SOAP Body SOAP Header u Contains Transmission Header l Control information for the Transmission File SOAP Body u Contains a Transmission Manifest l A list of all Returns in the Transmission File l The electronic postmark, if applicable 6 3
Transmission Header Transmission Control Information Examples utransmission ID utransmission timestamp utransmitter ETIN utype of Process - Test or Production uother process related entries 7 Transmission Manifest The Transmission Manifest lists all Returns by their content locations in the MIME content headers Each Return has a globally unique Return ID that matches the Return s content location in the MIME content header Content-Location = ReturnId 8 4
Sample Transmission Envelope MIME-Version: 1.0 Content-Type: Multipart/Related; boundary=<mime1120boundary>; type="text/xml" Content-Description: This is a sample structure of a transmission file. X-eFileRoutingCode: MEF --<MIME1120Boundary> Content-Type: "text/xml"; charset=utf-8 Content-Transfer-Encoding: 8bit Content-Location: <Envelope1120> <?xml version="1.0" encoding="utf-8"?> <SOAP:Envelope xmlns=http://www.irs.gov/efile xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:efile="http://www.irs.gov/efile" xsi:schemalocation="http://schemas.xmlsoap.org/soap/envelope/.../message/efilemessage.xsd"> <SOAP:Header> <efile:transmissionheader transmissionversion="2002v01"> <TransmissionId>TID01</TransmissionId> <Timestamp>2003-05-01T12:11:17+05:01</Timestamp> <Transmitter> <ETIN>12345</ETIN> </Transmitter> <ProcessType>T</ProcessType> </efile:transmissionheader> </SOAP:Header> <SOAP:Body> <efile:transmissionmanifest count="1"> <Reference contentlocation="99009920031210123456 electronicpostmark="2002-03-27t08:20:00-05:00" > </Reference> </efile:transmissionmanifest> </SOAP:Body> 9 Sample Return Reference and Content-Location <SOAP:Header><efile:TransmissionHeader transmissionversion="2002v01">.. <SOAP:Body> <efile:transmissionmanifest count="4"> <Reference contentlocation="01000020020860000001" electronicpostmark="2003-03-27t08:20:00-05:00" /> <Reference contentlocation="01000020020860000002" electronicpostmark="2003-03-27t08:20:10-05:00" /> <Reference contentlocation="01000020020860000003" electronicpostmark="2003-03-27t08:20:20-05:00" /> <Reference contentlocation="01000020020860000004" electronicpostmark="2003-03-27t08:20:30-05:00" /> </efile:transmissionmanifest> </SOAP:Envelope> --<MIME1120Boundary> Content-Type: Multipart/Related; boundary=<return001partboundary>; type=text/xml Content-Location: <01000020030860000001> Content-Description: data for the first return (one or more parts) follows. --<Return001PartBoundary> Content-Type: text/xml; charset=utf-8 Content-Transfer-Encoding: 8bit Content-Location: <ReturnData001> (Return (XML) data for the return goes here) --<Return001PartBoundary>-- --<MIME1120Boundary> Content-Type: Multipart/Related; boundary=<return002partboundary>; type=text/xml Content-Location: <01000020020860000002> Content-Description: This is the second return in the transmission file. --<Return002PartBoundary> ( other parts in the return, if any, go here) 10 5
Sample Return - Return Header <ReturnHeader binaryattachmentcount="0" subsidiaryreturncount="1"> <ReturnId>01000020032091234567</ReturnId> <Timestamp>2003-07-28T11:12:55</Timestamp> <TaxPeriodEndDate>2003-07-31</TaxPeriodEndDate> <ISPNumber>AAAAAA</ISPNumber> <SoftwareId>00000000</SoftwareId> <Originator> <EFIN>010000</EFIN> <Type>ERO</Type> <PractitionerPIN> <EFIN>010000</EFIN> <PIN>12345</PIN> </PractitionerPIN> </Originator> <PINEnteredBy>Taxpayer</PINEnteredBy> <SignatureOption>PIN Number</SignatureOption> <ReturnType>1120</ReturnType> Originator 11 Sample Return - Return Data 12 6
Sample Return - Return Documents 13 Acknowledgement File Acknowledgement File MIME Multi-Part Content Header MIME Part Boundary and Content Header SOAP Envelope SOAP Header SOAP Body MIME Part boundary and Content Header MIME Part boundary and Content Header MIME Part boundary and Content Header MIME Part boundary and Content Header MIME Part boundary and Content Header MIME Multi-Part End boundary The acknowledgement file structure is similar to the structure of the transmission file except that it has no nested MIME multi-part documents. Acknowledgement Header Acknowledgement Manifest Transmission Acknowledgement Return Acknowledgement Return Acknowledgement Return Acknowledgement Return Acknowledgement 14 7
Sample Acknowledgement File MIME-Version: 1.0 Content-Type: multipart/related; boundary=4444741.1049296259836.mimeboundary; type="text/xml" Content-Description: 1120 acknowledgement. --4444741.1049296259836.MIMEBoundary Content-Type: text/xml; charset=utf-8 Content-Transfer-Encoding: 8bit Content-Location: Envelope1120 <SOAP:Envelope xmlns=http://www.irs.gov/efile xmlns:efile="http://www.irs.gov/efile"> <SOAP:Header><efile:AcknowledgementHeader transmissionversion="2003v01">. <SOAP:Body> <efile:acknowledgementmanifest count="2"> <Reference contentlocation="tid01"/> <Reference contentlocation="01000020020860000001 "/> </efile:acknowledgementmanifest> </SOAP:Body> </SOAP:Envelope> --4444741.1049296259836.MIMEBoundary Content-Type: text/xml; charset=utf-8 Content-Transfer-Encoding: 8bit Content-Location: TID01 <TransmissionAcknowledgement xmlns="http://www.irs.gov/efile" xmlns:efile="http://www.irs.gov/efile" xmlns:xsi="http://www.w3.org/2001/xmlschemainstance" xsi:schemalocation="http://www.irs.gov/efile../message/efilemessage.xsd"transmissionversion="2003v01"> <TransmissionId>TID01</TransmissionId><TransmissionTimestamp>2002-03-27T14:30:0005:00</TransmissionTimestamp> <TransmissionStatus>A</TransmissionStatus><GTXKey>P20020327143000.0500</GTXKey></TransmissionAcknowledgement> --4444741.1049296259836.MIMEBoundary Content-Type: text/xml; charset=utf-8 Content-Transfer-Encoding: 8bit Content-Location: Return0001 <ReturnAcknowledgement xmlns="http://www.irs.gov/efile" xmlns:efile="http://www.irs.gov/efile" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="http://www.irs.gov/efile../message/efilemessage.xsd" returnversion="2003v01"><returnid> 01000020020860000001 </ReturnId> <BusinessEIN>011248769</BusinessEIN> <ReturnType>1120</ReturnType><ReturnStatus>A</ReturnStatus><PaymentIndicator>Payment Request Received</PaymentIndicator></ReturnAcknowledgement> 15 Sample Return Acknowledgement Acknowledgement File <ReturnAcknowledgement xmlns=http://www.irs.gov/efile xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="http://www.irs.gov/efile../message/efilemessage.xsd"> <ReturnId>01000020020860000017</ReturnId> <Errors errorcount=2 > <Error errorid="1"> <Xpath>/Return/ReturnData/IRS1120/OtherDeductions</Xpath> <ErrorCategory>Missing Document</ErrorCategory> <ErrorMessage> If Form 1120, Schedule J, Line 6e has a non-zero value, then Form 8827 must be attached.</errormessage> <RuleNumber>F1120-035</RuleNumber> <Severity> Reject </Severity> <DataValue></DataValue> </Error> <Error errorid="2"> </Error> </Errors> </ReturnAcknowledgement> 16 8
Sample 1120 Schema File Structure 17 efiletypes Schema File efiletypes.xsd defines data models for: u Reusable data types such as EIN, SSN, etc. l XML Schema built-in types with custom restrictions Length restrictions range restrictions format restrictions e.g., EFIN enumerated lists. u Required attributes for each Return document 18 9
1120x Return Schemas ReturnHeader1120x.xsd contains data elements that apply across all 1120 Return documents ReturnData1120.xsd and ReturnData1120S.xsd specify what and how many Return documents can be included in the Return Separate Schema files exist for each form, schedule, statement,... 19 Return Document Occurrences in a Return The type of Return documents and the limit of their occurrences are defined in ReturnData1120.xsd schema Form 1120 is required with one instance Most other Return document types are optional and allows for only one instance, if present 20 10
efilemessage Schema efilemessage.xsd defines data models for: utransmission Header utransmission Manifest ureturn Header elements common across families (i.e. 1120x, 94x, etc.) uacknowledgement 21 Validating XML Data in Transmission File Before composing the transmission file u validate the transmission envelope XML instance against the SOAP schema and efilemessage.xsd schema u validate the ReturnHeader structure against ReturnHeader1120x.xsd u validate the ReturnData structure against the ReturnData1120.xsd or ReturnData1120S.xsd schema, whichever is applicable 22 11
Attachments to Returns What can be attached? uxml documents statements, elections, etc. (part of tax prep software) unon-xml documents PDF file with 3rd party documents Where can it be attached? uxml documents can be attached to any document (form, schedule, ) or to any field in any document ubinary file can be attached to the return 23 Attachments to Returns How to attach? uuse the referencedocumentid attribute to attach XML documents uattach binary attachments to the tax return as MIME parts 24 12
Attaching multiple dependency documents to a Form Attachments to form IRS1120 and to an element on form IRS1120 <xml version="1.0" encoding="utf-8"?> <Return returnversion="2002v01"> <ReturnHeader binaryattachmentcount="0" subsidiaryreturncount="0"> <ReturnId>01000020020860000001</ReturnId> <Timestamp>2002-03-26T13:00:05-05:00</Timestamp> </ReturnHeader> <ReturnData documentcount= 3"> <IRS1120 documentid="doc0001" referencedocumentid="depc1 DEPd1" > </IRS1120> <OtherIncome referencedocumentid="depa1">8870</otherincome> <StockOwnershipForeignCorpStmt documentid="depc1"> </StockOwnershipForeignCorpStmt> <DualConsolidatedLossesStmt documentid="depd1"> <Statement>Statement One</Statement> </DualConsolidatedLossesStmt> </ReturnData> Element with document, Itemized Other Income Schedule Documents attached to Form 1120 25 Schedule Modernized e-file Assurance Testing Begins 3 Nov 2003 1120/1120S/990 1041 & 1065 1040 Release 1 1/2004 Release 2 7/2004 Release 3 1/2005 Release 4 1/2006 Release 5 1/2008?? 53 Forms and Schedules 44 Forms and Schedules Fed/State 26 13
FED/State - Why use XML? Flexible enough to allow for functionality required by states Have been finalized after extensive dialogue with software developers and service providers Not practical to change filing structures for Fed/State filing 27 SOAP Transmission Structure Multiple SOAP attachments within one transmission may be ufederal Return ufed/state Return (with one or multiple state returns attached to one Federal Return) ustate Stand-Alone Returns 28 14
Benefits of XML include: Industry standard Tools for XML development and mapping to legacy systems available in the marketplace at reasonable cost Format (schema) validation identifies Errors in file structure Missing mandatory fields Basic edits at point of entry Cleaner data Reuse of IRS structures and data elements reduces development time for states and software developers, encouraging wider implementation 29 TAG Sub-Group Transmission Working Group Recommendations uuse IRS 1120 XML transmission and return structures ustate return be an XML document 30 15
Other Decisions to be Made May state returns contain attachments such as PDF images of balance sheets or income statements? What data is needed in transmission and return headers? What validations are required? IRS and states will work with TIGERS to determine the final structure 31 Questions 16