Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

Message Structure Table and Validation Rules Artefacts

Design Improvements Proposal Paper

Unclassified 1 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

Unclassified 2 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

Background Information

As the ATO introduces support for services using multiple message formats (i.e. XBRL, XML & JSON), changes need to be made to the Message Structure and Validation Rule design artefacts to accommodate the delivery of services that use one or more of the message formats. The design artefacts currently have a very strong XBRL focus and the changes will introduce additional information to these to better describe the format specific design aspects. As an example, these changes include providing more detailed data type information to reduce/eliminate the need to refer to the SBR AU XBRL Taxonomy for data type definitions. This will also allow non-XBRL messages to be defined using the design artefacts alone. The change management aspects of the artefacts are also being updated. The presentation of the communications sheet is being updated to have one row per change. This change was requested by external stakeholders as the current practice of placing all changes in a single MS Excel cell was often exceeding Excel’s row height limits for display/print. Some additional metadata is also being added to describe the driver for change and the action (e.g. Add, Remove, Update etc.). As part of the ongoing process improvements and to incorporate feedback from external stakeholders, changes to validation/business rule formats are being introduced in the 2016/17 financial year. The new Technical Business Rule format will replace the current Structured English format and will use a more concise function based language that is similar to other ATO systems (e.g. ELS). A transition plan is detailed later in this document. The new Technical Business Rule format is the first step in a bigger process of rule harmonisation that is being undertaken. Rule harmonisation will allow for better rule re-use across multiple services than the current solution offers. This document does not discuss the full harmonisation process in detail.

Unclassified 3 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

Purpose of the document

This document describes a proposal for design changes to the Message Structure Table (MST) artefact, the Validation Rules (VR) artefact and the introduction of new Technical Business Rule format into the design artefacts.

The ATO is looking for an agreement with SwDs to move forward with these proposed changes/improvements.

Unclassified 4 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

Proposed changes/improvements

1.1 Communications Worksheet Due to limitations with MS Excel, and to improve clarity/filtering options, the format of the communications sheet is being enhanced. This change applies to both the MST and VR artefacts. This change feeds into the broader process improvement activities including the automation of release/package note documentation.

Current format (example): All changes for a version are currently located in a single cell. For large changes, the content in the description often exceeds MS Excel’s row height limit, resulting in some content not being displayed. As data is combined into one cell, it is also difficult to read and identify individual changes and perform impact assessment.

Version Release Date Description of changes 0.2 18.08.2016 Consultation feedback

MOD: Employer Declaration Context should not mandatory. Context Structure Label Employer.TrueAndCorrect Table changed Min FROM 1 TO 0

Context label name altered to improve clarity. Context Structure Table changed Label FROM Employer.Payroll TO Employer.PayrollPeriod

Message Structure Table Alias PAYEVNT20. Context changed FROM Employer.Payroll TO Employer.PayrollPeriod … …

New Format (example): Data previously bundled together in the ‘Description of Changes’ column is now being separated into Driver/Action and Comments. In addition, there will be a new row for each individual change. This will allow for filtering of, for example, Modifications, Deletes, Addition which will assist with impact assessment etc. Version Date Driver Action Comments 0.2 18/08/2016 Consultation feedback MOD Employer Declaration Context should not mandatory. Context Structure Label Employer.TrueAndCorrect Table MODIFY Min FROM 1 TO 0 0.2 18/08/2016 Consultation feedback MOD Context label name altered to improve clarity Context Structure Table MODIFY Label FROM Employer.Payroll TO Employer.PayrollPeriod 0.2 18/08/2016 Consultation feedback MOD Message Structure Table Alias PAYEVNT20 MODIFY Context FROM Employer.Payroll TO Employer.PayrollPeriod

Unclassified 5 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

1.2 Message Structure Table Artefact There are changes to the following sections in the MST Artefact:  Communications sheet – refer to section 3.1 for details.  CST worksheet  MST worksheet

1.2.1 CST Worksheet Changes The following table lists the existing and new/updated columns in the CST. Existing columns have been included for context. Description/Definitions are only provided for new/updated columns. Column Name Change Description/Definition Seq Num No Change Label No Change Start/Instant Date No Change End Date No Change Description No Change Period Type No Change Min Occurs Renamed Renamed from “Min” to improve clarity Max Occurs Renamed Renamed from “Max” to improve clarity Identifier Scheme No Change Identifier Value No Change Dimension #:Namespace No Change Prefix Dimension #: Name No Change Dimension #: Type No Change Dimension #: Value No Change Dimension #: Element No Change Dimension #: Alias1 No Change For XML based messages, will contain the full XPath XML - XPath New expression describing where the element(s) using this context will be located. For JSON based messages, will contain the full JSONPath JSON - JSONPath New expression describing where the element(s) using this context will be located.

Unclassified 6 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

1.2.2 MST Worksheet Changes The following table lists the existing and new/updated columns in the MST. Existing columns have been included for context. Description/Definitions are only provided for new/updated columns. Column Name Change Description/Definition Seq Num No Change Parent Seq Num No Change Alias No Change Element Type No Change Label No Change ELS Tag No Change Min Occurs Renamed Renamed from “Min” to improve clarity Max Occurs Renamed Renamed from “Max” to improve clarity TREF ID No Change Namespace Prefix No Change Element Name No Change Context No Change Period Type No Change Balance Type No Change Business Definition No Change Business Guidance No Change Report Guidance No Change Legal Reference Order Change Moved this column, was previously located after ELS Tag. Data Type New The SBR taxonomy data type or the base data type Pattern New Defines the exact sequence of characters that are acceptable (e.g. regular expression) Full Enumeration New Defines a list of acceptable values. List of valid values, separated by a “|” character Min Length New Specifies the minimum number of characters or list items allowed. Must be equal to or greater than zero Max Length New Specifies the maximum number of characters or list items allowed. Must be equal to or greater than zero Total Digits New Specifies the exact number of digits allowed. Must be greater than zero

Note: Used for defining a very small number of SBR AU Taxonomy data elements Fractional Digits New Specifies the maximum number of decimal places allowed. Must be equal to or greater than zero

Note: Used for defining a very small number of SBR AU Taxonomy data elements XML - XPath New For XML based messages, will contain the full XPath expression describing the element name and location. For JSON based messages, will contain the full JSONPath JSON - JSONPath New expression describing the element name and location.

Unclassified 7 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

1.3 Validation Rules Artefact There are changes to the following section of the VR Artefact:  Communications sheet – refer to section 3.1 for details.  Validation Rules worksheet

1.3.1 Validation Rules Worksheet Changes The following table lists the existing and new/updated columns in the MST. Existing columns have been included for context. Description/Definitions are only provided for new/updated columns. Column Name Change Description/Definition Seq Num No Change Alias No Change Label No Change Context Instance No Change Element Name No Change English Business Rule No Change Legacy Rule New Used for transition during the 2016/17 financial year.

Specifies the validation rule using Structured English.

Please refer to section 3.4 for details on the new Technical Business Rule format and Transition Plan Technical Business Rule New Format For new services and those being transitioned during the 2016/17 financial year onwards, specifies the validation rule using the new Technical Business Rule format

For existing service specifications, this column specifies the validation rule using Structured English.

Please refer to section 3.4 for details on the new Technical Business Rule format and Transition Plan Applies to XBRL Payloads New Identifies if the validation rule applies to XBRL payloads. Valid values are: ‘Y’, ‘N’ or ‘n/a’

Y - rule is applied to a XBRL payload N - rule is not applied to a XBRL payload n/a - service does not use XBRL payloads Applies to XML Payloads New Identifies if the validation rule applies to XML payloads. Valid values are: ‘Y’, ‘N’ or ‘n/a’

Y - rule is applied to a XML payload N - rule is not applied to a XML payload n/a - service does not use XML payloads Applies to JSON Payloads New Identifies if the validation rule applies to JSON payloads. Valid values are: ‘Y’, ‘N’ or ‘n/a’

Y - rule is applied to a JSON payload N - rule is not applied to a JSON payload n/a - service does not use JSON payloads Rule Type No Change

Unclassified 8 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

Column Name Change Description/Definition Schematron ID No Change Message Code No Change Message - Short No Change Description No Change Last Updated No Change

Unclassified 9 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

1.4 New Technical Business Rule Format The intent of the new rule format is to achieve the following goals: o Reduce inconsistencies in how rules are written o Reduce interpretation errors o Ensure rules are machine parsable o Enable code generation for the ATO o Enable code generation for third parties o Enable harmonisation of rules to reduce the number of rules that need to be managed

The new rule format is similar to the ATO’s ELS system, however the longer term intent is to use meaning full tag names such as ^ABN, ^TFN, ^AddressLine1 etc.

1.4.1 Summary of Changes Whilst a comprehensive reference of functions is currently being produced for the common MIG, the below items are some of the more salient changes:  The text “IF” and “RETURN VALIDATION MESSAGE ENDIF” is removed leaving just a Boolean expression. When the expression evaluates to true, an error message will be returned.  Element identifiers (Aliases) for all data elements o All data elements in a message used in validation (& transformation) need to have a unique identifier in the MST. This includes all data stored in XBRL Context definitions (e.g. identifier schemes, identifier values, dates, dimension values). o Tuples can now have Aliases  Element identifier (Aliases) format changes o ESR leverages off existing ATO parsing technology which requires element identifier form to be changed from: [Field123] to: ^Field123  Replacement of statements such as “ANY OCCURRENCE OF [Field123] > 1” with function based equivalents such as “AnyOccurrence(^Field123, ^Field123 > 1)”

Unclassified 10 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

Examples of old vs new rule format

Structured English New Technical Business Rule format IF [FRM111] > [FRM222] ^FRM111 > ^FRM222 RETURN VALIDATION MESSAGE ENDIF

[FRM111] = FRM111 = [FRM222] = ^FRM222 =

IF [FRM333] = FALSE AND [FRM444] ^FRM333 = FALSE CONTAINS NUMERICS SET(0-9) AND RETURN VALIDATION MESSAGE ContainsSet(^FRM444, '0-9') ENDIF

[FRM333] = ^PTR333 = [FRM444] = ^PTR444 = * full element definitions have been removed for clarity

1.4.2 Transition Plan

As indicated in Section 3.3.1, the Legacy Column in the VR Spreadsheet has been introduced to assist the transition between rules written in Structured English and the new Technical Business Rule format. The column will be used during the 2016/17 financial year and will be phased in/out as follows.  The transition will impact only those existing services being updated throughout the 2016/17 FY. The legacy column will be removed for the final publication of these services (document version V1.0).  Where a service has not changed, but an update occurs in a future year, there will be no transitional arrangements (i.e. Legacy Rule column not used)  New services won’t be subject to this transitional approach using the Legacy Column  Bug fixes/production support initiated changes to existing services will not necessarily result in the new rule format being applied.

Unclassified 11 of 12 Design Improvements Proposal Paper Message Structure Table and Validation Rules Artefacts

Recommendation

The above proposals are recommended for implementation1 by the ATO pending confirmation from the SwD group.

END OF DOCUMENT

1 Implementation includes changes to service artefacts and also updates to the ATO Common MIG document.

Unclassified 12 of 12