[lmi] Re: Calculation summary XML resources structure (with some examples) v2

[Evgeniy Tarassov]

<?xml version="1.0"?>
<!--
   Column formatting information like number-formatting, title, etc.

   Copyright (C) 2002, 2003, 2004, 2005, 2006 Gregory W. Chicares.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License version 2 as
   published by the Free Software Foundation.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

   http://savannah.nongnu.org/projects/lmi
   email: <address@hidden>
   snail: Chicares, 186 Belle Woods Drive, Glastonbury CT 06033, USA

   $Id: $

   TODO:
   - add uniqueness constraints for (name,basis) in every document
       (illustration.xml, format.xml)
   - add a custom namespace header to the Schema and
       to the data XML files.
-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema";>
   <xs:annotation>
       <xs:documentation>
           This document describes the structure of illustration data
           XML file and other XML files containing information used
           in a report generation.
           Files:
           - data.xml - illustration data generated for a particular user. It
               could be rendered as an XML file or kept in memory
               during processing.
           - format.xml - XML file containing for each column its titles and
               format strings for columns with numerical data.
           - schema.xsd - current document. Describes the structure
               of previously mentioned files.
           - [media].xsl - XSL template files used to render data.xml.
               These templates use format.xml file to render
               data.xml file data in a human readable way for the [media]
               (media: html, csv, xsl-fo, etc)
       </xs:documentation>
   </xs:annotation>

<!--
   *************************************
                common part
   *************************************
-->
   <xs:simpleType name="basis_type">
       <xs:annotation>
           <xs:documentation>
               Basis type constants (from enum_run_basis in xenumtypes.hpp).
               TODO: we should make these constants human-usable
                     something like "current", "guaranteed",  "current_zero",
                     or maybe simply "curr", "guar", "curr_zero".
           </xs:documentation>
       </xs:annotation>
       <xs:restriction base="xs:string">
           <xs:enumeration value="run_curr_basis" />
           <xs:enumeration value="run_guar_basis" />
           <xs:enumeration value="run_mdpt_basis" />
           <xs:enumeration value="run_curr_basis_sa_zero" />
           <xs:enumeration value="run_guar_basis_sa_zero" />
           <xs:enumeration value="run_curr_basis_sa_half" />
           <xs:enumeration value="run_guar_basis_sa_half" />
       </xs:restriction>
   </xs:simpleType>

   <xs:simpleType name="name_type">
       <xs:annotation>
           <xs:documentation>
               Column name type. This type have no impact on generated reports
           </xs:documentation>
       </xs:annotation>
       <xs:restriction base="xs:QName" />
   </xs:simpleType>

<!--
   *************************************
             illustration data
   *************************************

   This schema keeps distinction between double- and string-based values,
   such as double_string, double_vector vs scalar_string, scalar_vector.
   This way we can introduce additional checks, and prepare for a smooth
   transition to the approach when number formatting is done on xslt side,
   for the case if we decide to do that.
-->
   <xs:simpleType name="string_data_type">
       <xs:annotation>
           <xs:documentation>
               Nodes representing string data.
               We keep this type to be able to smoothly add
               some additional check on string-based node values,
               in case we need to excessivly debug our xml data flows.
           </xs:documentation>
       </xs:annotation>
       <xs:restriction base="xs:string">
           <!-- add any additional checks on string-based values here -->
       </xs:restriction>
   </xs:simpleType>

   <xs:simpleType name="double_data_type">
       <xs:annotation>
           <xs:documentation>
               Nodes representing double data.
               We keep this type to be able to smoothly add
               some additional check on string-based node values,
               in case we need to excessivly debug our xml data flows.

               Currently any number-formatting is done in the C++ code.
               See ledger_xml_io.cpp for details on possible formatting.
               Comments fragment from ledger_xml_io.cpp:
               | Formats
               |
               | F0: zero decimals
               | F1: zero decimals, commas
               | F2: two decimals, commas
               | F3: scaled by 100, zero decimals, with '%' at end:
               | F4: scaled by 100, two decimals, with '%' at end:
               |
               | Presumably all use commas as thousands-separators, so that
               | an IRR of 12345.67% would be formatted as "12,345.67%".
               |
               | So the differences are:
               |   'precision' (number of decimal places)
               |   percentage (scaled by 100, '%' at end) or not
               | and therefore F0 is equivalent to F1
               There could be some additional formats introduced later on,
               such as 'bp' (in 10000 fractions as opposed to 100
fractions for '%')
           </xs:documentation>
       </xs:annotation>
       <xs:restriction base="xs:string">
           <!-- add any additional checks on double-based values here -->
       </xs:restriction>
   </xs:simpleType>

   <xs:complexType name="string_scalar_type">
       <xs:annotation>
           <xs:documentation>
               Nodes representing string scalars.
               Attributes:
               - a required "name" attribute
               - an optional "basis" attribute
           </xs:documentation>
       </xs:annotation>
       <xs:simpleContent>
           <xs:extension base="string_data_type">
               <xs:attribute name="name" type="name_type" use="required" />
               <xs:attribute name="basis" type="basis_type" use="optional" />
           </xs:extension>
       </xs:simpleContent>
   </xs:complexType>

   <xs:complexType name="double_scalar_type">
       <xs:annotation>
           <xs:documentation>
               Nodes representing double scalars.
               See double_data_type for additional information.
               Attributes:
               - a required "name" attribute
               - an optional "basis" attribute
           </xs:documentation>
       </xs:annotation>
       <xs:simpleContent>
           <xs:extension base="double_data_type">
               <xs:attribute name="name" type="name_type" use="required" />
               <xs:attribute name="basis" type="basis_type" use="optional" />
           </xs:extension>
       </xs:simpleContent>
   </xs:complexType>

   <xs:complexType name="double_vector_type">
       <xs:annotation>
           <xs:documentation>
               Node representing vector of doubles.
               A node can not have a text value, it can only have "duration"
               children nodes.
               Sub-nodes:
               - ordered set of "duration" nodes of type double_data_type
               Attributes:
               - a required "name" attribute
               - an optional "basis" attribute
           </xs:documentation>
       </xs:annotation>
       <xs:choice minOccurs="0" maxOccurs="unbounded">
           <xs:element name="duration" type="double_data_type">
               <xs:annotation>
                   <xs:documentation>
                       Node representing a particular value of a vector.
                       As "duration" nodes are always ordered inside a "vector"
                       parent node we will use "duration"'s node position()
                       to get its index in the parent container.
                   </xs:documentation>
               </xs:annotation>
           </xs:element>
       </xs:choice>
       <xs:attribute name="name" type="name_type" use="required" />
       <xs:attribute name="basis" type="basis_type" use="optional" />
   </xs:complexType>

   <xs:complexType name="string_vector_type">
       <xs:annotation>
           <xs:documentation>
               Node representing vector of strings
               A node can not have a text value, it can only have "duration"
               children nodes.
               Sub-nodes:
               - ordered set of "duration" nodes of type string_data_type
               Attributes:
               - a required "name" attribute
               - an optional "basis" attribute
           </xs:documentation>
       </xs:annotation>
       <xs:choice minOccurs="0" maxOccurs="unbounded">
           <xs:element name="duration" type="string_data_type">
               <xs:annotation>
                   <xs:documentation>
                       Node representing a particular value of a vector.
                       As "duration" nodes are always ordered inside a "vector"
                       parent node we will use "duration"'s node position()
                       to get its index in the parent container.
                   </xs:documentation>
               </xs:annotation>
           </xs:element>
       </xs:choice>
       <xs:attribute name="name" type="name_type" use="required" />
       <xs:attribute name="basis" type="basis_type" use="optional" />
   </xs:complexType>

   <xs:complexType name="supplemental_report_type">
       <xs:annotation>
           <xs:documentation>
               Supplemental columns name to include into the report.
               TODO: This column list does not describe the actual data,
               it contains some information about what should be included
               into a particular report about that illustration, therefore
               it should be passed as a list of parameters to
               XSL processor at the moment of report generation, or as
               a separate XML file.
               Sub-nodes:
               - an optional 'title' node containing a title for the report
               - an ordered list of columns or spacers
           </xs:documentation>
       </xs:annotation>
       <xs:sequence>
           <xs:element name="title" type="xs:string" />
           <xs:choice maxOccurs="unbounded">
               <xs:element name="column" type="report_column_type" />
               <xs:element name="spacer" type="report_spacer_type" />
           </xs:choice>
       </xs:sequence>
   </xs:complexType>

   <xs:complexType name="report_column_type">
       <xs:annotation>
           <xs:documentation>
               A reference to a column to be included into the report.
               Attributes:
               - a required "name" attribute
               - an optional "basis" attribute
           </xs:documentation>
       </xs:annotation>
       <xs:attribute name="name" type="name_type" use="required" />
       <xs:attribute name="basis" type="basis_type" use="optional" />
   </xs:complexType>

   <xs:complexType name="report_spacer_type">
       <xs:annotation>
           <xs:documentation>
               A node in a report section that indicates a space
between columns.
               It has to be an empty node.
           </xs:documentation>
       </xs:annotation>
   </xs:complexType>

   <xs:complexType name="illustration_type">
       <xs:annotation>
           <xs:documentation>
               The root node type for illustration data XML file.
               Sub-Nodes:
               - any number of "string_scalar" (order does not matter)
               - any number of "double_scalar" (order does not matter)
               - any number of "string_vector" (order does not matter)
               - any number of "double_vector" (order does not matter)
               - an optional last node "supplemental_report" (see the TODO note
                   for "supplemental_report_type" node)
           </xs:documentation>
       </xs:annotation>
       <xs:sequence>
           <xs:choice maxOccurs="unbounded">
               <xs:element name="string_scalar" type="string_scalar_type" />
               <xs:element name="double_scalar" type="double_scalar_type" />
               <xs:element name="string_vector" type="string_vector_type" />
               <xs:element name="double_vector" type="double_vector_type" />
           </xs:choice>
           <xs:element name="supplemental_report"
type="supplemental_report_type"
               minOccurs="0" maxOccurs="1" />
       </xs:sequence>
   </xs:complexType>

   <xs:element name="illustration" type="illustration_type" />

<!--
   *************************************
   columns XML format 'format.xml'
   *************************************
-->
   <xs:complexType name="column_title_type">
       <xs:annotation>
           <xs:documentation>
               Node describing a particular column title string.
               If at a point we decide to restrain the set of column names,
               then we should restrict this type via &lt;xsl:enumeration&gt;.
               The title could indicate a a particular basis it applies to.
           </xs:documentation>
       </xs:annotation>
       <xs:simpleContent>
           <xs:extension base="xs:string">
               <xs:attribute name="basis" type="basis_type" use="optional" />
           </xs:extension>
       </xs:simpleContent>
   </xs:complexType>

   <xs:simpleType name="column_format_type">
       <xs:annotation>
           <xs:documentation>
               Node describing a particular column format.
               The set of formatting rules is fixed in the XMLSchema
and in the c++.
               For the moment only 'f0', 'f1', 'f2', 'f3', 'f4'
values are allowed, and 'bp' could
               be introduced shortly.
           </xs:documentation>
       </xs:annotation>
       <xs:restriction base="xs:string">
           <xs:enumeration value="f0"/>
           <xs:enumeration value="f1"/>
           <xs:enumeration value="f2"/>
           <xs:enumeration value="f3"/>
           <xs:enumeration value="f4"/>
           <!--
               TODO implement
               <xs:enumeration value="bp"/>
           -->
       </xs:restriction>
   </xs:simpleType>

   <xs:complexType name="column_type">
       <xs:annotation>
           <xs:documentation>
               Format of a particular column.
               It contains the "picture string" parameter for
               the xsl function "format-number".
               Link: http://www.w3.org/TR/xslt20/#function-format-number
               Attributes:
               - a required column 'name' attribute
               Subnodes:
               - an optional set of 'title' nodes for different basis values
               - an optional 'format' node used to format double data in C++
                 before writing it into XML
           </xs:documentation>
       </xs:annotation>
       <xs:sequence>
           <xs:element name="title" type="column_title_type"
minOccurs="0" maxOccurs="unbounded" />
           <xs:element name="format" type="column_format_type"
minOccurs="0" maxOccurs="1" />
       </xs:sequence>
       <xs:attribute name="name" type="name_type" use="required" />
   </xs:complexType>

   <xs:complexType name="columns_type">
       <xs:annotation>
           <xs:documentation>
               The root node type of a "formats" XML file.
               Subnodes:
               - any number of "column" nodes (order does not matter)
           </xs:documentation>
       </xs:annotation>
       <xs:choice>
           <xs:element name="column" type="column_type"
               minOccurs="0" maxOccurs="unbounded" />
       </xs:choice>
   </xs:complexType>

   <xs:element name="columns" type="columns_type" />

</xs:schema>