<?xml version="1.0" encoding="US-ASCII"?>

<!-- $Id: lrsml.dtd,v 1.25 2002/07/16 20:48:25 flacoste Exp $ -->

<!--

Copyright (C) 2001 Stichting LogReport Foundation LogReport@LogReport.org
 
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

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 (see COPYING); if not, check with
http://www.gnu.org/copyleft/gpl.html or write to the Free Software 
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.

-->

<!--                    
    Document Type Definition for the Lire Report Specification
    Markup Language.

    Please use the following formal public identifier to identify it:

    "-//LogReport.ORG//DTD Lire Report Specification Markup Language V1.0//EN"

    This DTD defines a grammar that is used to specify reports that
    can be generated by Lire.

    NameSpace:

    Elements of this DTD are defined in the namespace
    http://www.logreport.org/LRSML/

    The official URL for this DTD is 
    http://www.logreport.org/LRSML/1.0/lrsml.dtd

    XML documents should reference this DTD by using

    DOCTYPE PUBLIC
   "-//LogReport.ORG//DTD Lire Report Specification Markup Language V1.0//EN"
   "http://www.logreport.org/LRSML/1.0/lrsml.dtd"
                                                                   -->

<!--                    Namespace prefix for validation using the
                        DTD                                        -->
<!ENTITY % LIRE.xmlns.pfx    "lire"                                  >
<!ENTITY % LIRE.pfx          "%LIRE.xmlns.pfx;:"                     >
<!ENTITY % LIRE.xmlns.attr.name "xmlns:%LIRE.xmlns.pfx;"             >
<!ENTITY % LIRE.xmlns.attr
  "%LIRE.xmlns.attr.name; CDATA #FIXED 'http://www.logreport.org/LRSML/'">

<!-- 
    Include needed modules
                                                                   -->
<!ENTITY % lire-types.mod PUBLIC
    "-//LogReport.ORG//ENTITIES Lire Data Types V1.0//EN"
    "lire-types.mod">
%lire-types.mod;

<!ENTITY % lire-desc.mod PUBLIC
    "-//LogReport.ORG//ELEMENTS Lire Description Elements V1.0//EN"
    "lire-desc.mod">
%lire-desc.mod;

<!--                    Parameter entities which defines qualified
                        names of the elements                      -->
<!ENTITY % LIRE.report-spec     "%LIRE.pfx;report-spec"              >
<!ENTITY % LIRE.global-filter-spec "%LIRE.pfx;global-filter-spec">
<!ENTITY % LIRE.display-spec    "%LIRE.pfx;display-spec"             >
<!ENTITY % LIRE.param-spec      "%LIRE.pfx;param-spec"               >
<!ENTITY % LIRE.param           "%LIRE.pfx;param"                    >
<!ENTITY % LIRE.filter-spec     "%LIRE.pfx;filter-spec"              >
<!ENTITY % LIRE.report-calc-spec "%LIRE.pfx;report-calc-spec"        >
<!ENTITY % LIRE.extension       "%LIRE.pfx;extension"                >

<!--                    
    Report Spec element.

    Root element of a report specification. It contains descriptive
    elements about the report specification (title, description). 
    It contains the display elements that will be in the generated  
    report (display-spec).
    It contains specification for the parameters that can be used 
    to customize the report generated from this specification (param-spec).
    Finally, it contains elements to specify a filter expression which 
    can be used to select a subset of the records (filter-spec) and
    the expression to build the report (report-calc-spec). 

    Attributes of report-spec:
        superservice: the name of the superservice for which this 
                      report is available : i.e. email, www, dns, 
                      etc.
        schema:       the DLF schema used by the report. This defaults
                      to the superservice's schema, but can be one of its
                      derived or extended schema.
        id:           An unique identifier for the report 
                      specification
                                                                   -->
<!ELEMENT %LIRE.report-spec;
                        (%LIRE.title;, %LIRE.description;,
                         (%LIRE.param-spec;)?, %LIRE.display-spec;,
                        (%LIRE.filter-spec;)?, 
                        (%LIRE.report-calc-spec;|%LIRE.extension;))    
                                                                     >
<!ATTLIST %LIRE.report-spec;
             id             ID                              #REQUIRED
             superservice   %superservice.type;             #REQUIRED
             schema         NMTOKEN                         #IMPLIED
             charttype      (%chart.type;)                  #IMPLIED
             %LIRE.xmlns.attr;                                       >

<!--                    
    Global Filter Spec element.

    Root element of a filter specification. It contains descriptive
    elements about the filter specification (title, description). 
    It contains the display elements that will be used when that filter is 
    used in a generated report (display-spec).
    It contains specification for the parameters that can be used 
    to customize the filter generated from this specification (param-spec).
    Finally, it contains element to specify the filter expression which 
    can be used to select a subset of the records (filter-spec).

    Attributes of global-filter-spec:
        superservice: the name of the superservice for which this 
                      filter is available : i.e. email, www, dns, 
                      etc.
        schema:       the DLF schema used by the report. This defaults
                      to the superservice's schema, but can be one of its
                      derived or extended schema.
        id:           An unique identifier for the filter 
                      specification
                                                                   -->
<!ELEMENT %LIRE.global-filter-spec;
                        (%LIRE.title;, %LIRE.description;,
                         (%LIRE.param-spec;)?, %LIRE.display-spec;,
                        (%LIRE.filter-spec;))    
                                                                     >

<!ATTLIST %LIRE.global-filter-spec;
             id             ID                              #REQUIRED
             superservice   %superservice.type;             #REQUIRED
             schema         NMTOKEN                         #IMPLIED
             %LIRE.xmlns.attr;                                       >

<!--
    Display-spec element.

    This element contains the descriptive element that will appear 
    in the generated report.

    It contains one title and one or more description. If there is
    more than one description, they should have different value for
    the target-user attribute. 

    This element has no attribute.
                                                                   -->
<!ELEMENT %LIRE.display-spec; (%LIRE.title;, (%LIRE.description;)*)  >

<!--
    Param-spec element.

    This element contains the parameters than can be customized in
    this report specification.

    This element doesn't have any attribute.
                                                                   -->
<!ELEMENT %LIRE.param-spec; (%LIRE.param;)+                          >

<!--
    Param element.

    This element contains the specification for a parameter than
    can be used to customize this report.

    This element can contains a description element which can be
    used to explain the parameter's purpose.

    It is an error to define a parameter with the same name than
    one of the superservice's field.

    Attributes of param:
        name:       the name of the attribute.
        type:       the data type of the attribute.
        default:    the default value of the attribute.
                                                                   -->
<!ELEMENT %LIRE.param; (%LIRE.description;)?                         >
<!ATTLIST  %LIRE.param;
             name       ID                                 #REQUIRED 
             type       (%lire.types;)                     #REQUIRED
             default    CDATA                              #IMPLIED  >

<!ENTITY % LIRE.eq      "%LIRE.pfx;eq"                               >
<!ENTITY % LIRE.ne      "%LIRE.pfx;ne"                               >
<!ENTITY % LIRE.gt      "%LIRE.pfx;gt"                               >
<!ENTITY % LIRE.ge      "%LIRE.pfx;ge"                               >
<!ENTITY % LIRE.lt      "%LIRE.pfx;lt"                               >
<!ENTITY % LIRE.le      "%LIRE.pfx;le"                               >
<!ENTITY % LIRE.and     "%LIRE.pfx;and"                              >
<!ENTITY % LIRE.or      "%LIRE.pfx;or"                               >
<!ENTITY % LIRE.not     "%LIRE.pfx;not"                              >
<!ENTITY % LIRE.match   "%LIRE.pfx;match"                            >
<!ENTITY % LIRE.value   "%LIRE.pfx;value"                            >

<!ENTITY % expr "%LIRE.eq; | %LIRE.ne; | 
                 %LIRE.gt; | %LIRE.lt; | %LIRE.ge; | %LIRE.le; | 
                 %LIRE.and; | %LIRE.or; | %LIRE.not; | 
                 %LIRE.match; | %LIRE.value;"                        >



<!--
    Filter-spec element.

    This element is used to select the subset of the records that
    will be used to generate the report. If this element is missing,
    all records will be used to generate the report.

    The content of this element are expression element which defines
    an expression which will evaluate to true or false for each
    record. The subset used for to generate the report are all records
    for which the expression evaluates to true.

    The value used to evaluate the expressions are either literal,
    value of parameter or value of one of the field of the record.
    Parameter and field starts with a $ followed by the name of the
    parameter or field. All other values are interpreted as literals.

    This element doesn't have any attribute.
                                                                   -->

<!ELEMENT %LIRE.filter-spec; (%expr;)                                >

<!--
    Value element.

    This expression element to false if the 'value' attribute is 
    undefined, the empty string or 0. It evaluate to true otherwise.

    Attribute of value:
        value:          The value that should be evaluated for a 
                        boolean context.
                                                                   -->
<!ELEMENT %LIRE.value;  EMPTY                                        >
<!ATTLIST %LIRE.value;
             value      CDATA                              #REQUIRED >

<!ELEMENT %LIRE.eq;     EMPTY                                        >
<!ATTLIST %LIRE.eq;
             arg1       CDATA                              #REQUIRED   
             arg2       CDATA                              #REQUIRED >

<!ELEMENT %LIRE.ne;     EMPTY                                        >
<!ATTLIST %LIRE.ne;
             arg1       CDATA                              #REQUIRED   
             arg2       CDATA                              #REQUIRED >

<!ELEMENT %LIRE.gt;     EMPTY                                        >
<!ATTLIST %LIRE.gt;
             arg1       CDATA                              #REQUIRED   
             arg2       CDATA                              #REQUIRED >

<!ELEMENT %LIRE.ge;     EMPTY                                        >
<!ATTLIST %LIRE.ge;
             arg1       CDATA                              #REQUIRED   
             arg2       CDATA                              #REQUIRED >

<!ELEMENT %LIRE.lt;     EMPTY                                        >
<!ATTLIST %LIRE.lt;
             arg1       CDATA                              #REQUIRED   
             arg2       CDATA                              #REQUIRED >

<!ELEMENT %LIRE.le;     EMPTY                                        >
<!ATTLIST %LIRE.le;
             arg1       CDATA                              #REQUIRED   
             arg2       CDATA                              #REQUIRED >

<!--
    Match element.

    The match expression element tries to match a POSIX 1003.2
    extended regular expression to a value and return true if there is
    a match and false otherwise.

    Attributes of match:
        value:          The value which should matched.
        re:             A POSIX 1003.2 extended regular expression.
        case-sensitive: Is the regex sensitive to case. Defaults to true.
                                                                   -->
<!ELEMENT %LIRE.match;  EMPTY                                        >
<!ATTLIST %LIRE.match;
             value          CDATA                          #REQUIRED   
             re             CDATA                          #REQUIRED 
             case-sensitive (%bool.type;)                  'true'    >

<!ELEMENT %LIRE.not;    (%expr;)                                     >
<!ELEMENT %LIRE.and;    (%expr;)+                                    >
<!ELEMENT %LIRE.or;     (%expr;)+                                    >


<!--
    This parameter entity may be used by extensions to define
    additional attributes that can be used to parametrize the 
    extension.
                                                                   -->
<!ENTITY % LIRE.extension.optional.attr ""                           >
<!--
    Extension element.

    The extension element is used to signal that the report will
    be generated by a use-extension that uses the Lire Extension API.

    Attribute of extension:
        name:           The name of the extension.
                                                                   -->
<!ELEMENT %LIRE.extension; EMPTY                                     >
<!ATTLIST %LIRE.extension;
             name       NMTOKEN                            #REQUIRED 
             %LIRE.extension.optional.attr;                          >

<!ENTITY % LIRE.timegroup   "%LIRE.pfx;timegroup"                    >
<!ENTITY % LIRE.group       "%LIRE.pfx;group"                        >
<!ENTITY % LIRE.rangegroup  "%LIRE.pfx;rangegroup"                   >
<!ENTITY % LIRE.timeslot    "%LIRE.pfx;timeslot"                     >
<!ENTITY % LIRE.summary     "%LIRE.pfx;summary"                      >
<!ENTITY % LIRE.field       "%LIRE.pfx;field"                        >
<!ENTITY % LIRE.sum         "%LIRE.pfx;sum"                          >
<!ENTITY % LIRE.avg         "%LIRE.pfx;avg"                          >
<!ENTITY % LIRE.min         "%LIRE.pfx;min"                          >
<!ENTITY % LIRE.max         "%LIRE.pfx;max"                          >
<!ENTITY % LIRE.count       "%LIRE.pfx;count"                        >
<!ENTITY % LIRE.records     "%LIRE.pfx;records"                      >

<!-- Empty group operator                                          -->
<!ENTITY % LIRE.empty-ops   "%LIRE.sum; | %LIRE.avg; | %LIRE.count; |
                             %LIRE.min; | %LIRE.max; | 
                             %LIRE.records;"                         >

<!-- Group operations that are also aggregators                    -->
<!ENTITY % LIRE.nestable-aggr
                            "%LIRE.group; | %LIRE.timegroup; | 
                             %LIRE.timeslot; | %LIRE.rangegroup;"    >

<!-- Group operations                                              -->
<!ENTITY % LIRE.group-ops   "%LIRE.empty-ops;| %LIRE.nestable-aggr;" >

<!-- Containers for group operations                               -->
<!ENTITY % LIRE.aggregator  "%LIRE.nestable-aggr; | %LIRE.summary;"  >

<!--
    Report-calc-spec element.

    This element describes the computation needs to generate the
    report. 

    It contains one aggregator element.
                                                                   -->
<!ELEMENT %LIRE.report-calc-spec; (%LIRE.aggregator;)                >

<!--
    Summary element.

    The group element generates a report where statistics are computed 
    over all the input records. This can be used to generate simple
    overview reports.

    This element has no attributes.

                                                                   -->
<!ELEMENT %LIRE.summary;          (%LIRE.group-ops;)+                >

<!--
    Group element.

    The group element generates a report where records are grouped
    by some field values and aggregate statistics are computed on
    those group of records.

    It contains the field that should be used for grouping and 
    the statistics that should be computed.

    The sort order in the report is controlled by the 'sort' 
    attribute. 

    Attributes of group:
        name:   the name for the group. this is only mandatory for 
                nested group. The value of the group in a subgroup is
                the number of records that are part of the group.
        sort:   whitespace delimited list of fields name that should
                used to sort the records. Field names can be prefixed
                by - to specify reverse sort order, otherwise
                ascending sort order is used. The name can also 
                refer to the name attribute of the statistics 
                element.
        limit:  limit the number of records that will be in the 
                generated report. It can be either a positive integer
                or the name of a user supplied param. 

                                                                   -->
<!ELEMENT %LIRE.group;      ((%LIRE.field;)+, (%LIRE.group-ops;)+)   >
<!ATTLIST %LIRE.group;
             sort       NMTOKENS                           #IMPLIED  
             name       ID                                 #IMPLIED
             limit      CDATA                              #IMPLIED  >

<!--
    Timegroup element.

    The timegroup element generates a report where records are grouped
    by time range (hour, day, etc.). Statistics are then computed
    on these records grouped by period.

    Attribute of timegroup:
        field:  the name of the field which is used to group records. 
                This should be a field which is of one of the time
                types (timestamp, date, time). It defaults to the 
                default 'timestamp' field if unspecified.
        period: This is the timeperiod over which records should be 
                grouped. Valid period looks like (hour, day, 1h, 30m,
                etc). It can also be the name of a user supplied param. 
                
                                                                   -->
<!ELEMENT %LIRE.timegroup;  (%LIRE.group-ops;)+                      >
<!ATTLIST %LIRE.timegroup;
             field      NMTOKEN                            #IMPLIED
             period     CDATA                             #REQUIRED  >

<!--
    Timeslot element.

    The timeslot element generates a report where records are grouped 
    according to a cyclic unit of time. The duration unit used won't
    fall over to the next higher unit. For example, this means that
    using a unit of 1d will generate a report where the stats will be
    by day of the week, 8h will generate a report by third of day, 
    etc. The statistics are then computed over the records in the same
    timeslot.

    Attribute of timegroup:
        field:  the name of the field which is used to group records. 
                This should be a field which is of one of the time
                types (timestamp, date, time). It defaults to the 
                default 'timestamp' field if unspecified.
         unit:  This is the cyclic unit of time in which units the 
                records are aggregated. It can be any duration value.
                (hour, day, 1h, 30m, etc). 
                It can also be the name of a user supplied param. 
                
                                                                   -->
<!ELEMENT %LIRE.timeslot;  (%LIRE.group-ops;)+                       >
<!ATTLIST %LIRE.timeslot;
             field      NMTOKEN                            #IMPLIED
             unit       CDATA                             #REQUIRED  >

<!--
    Rangegroup element.

    The rangegroup element generates a report where records are grouped
    into distinct class delimited by a range. This element can be used
    to aggregates continuous numeric values like duration or bytes.
    Statistics are then computed on these records grouped in
    range class.

    Attribute of timegroup:
        field:  the name of the field which is used to group records. 
                This should be a field which is of a continuous numeric
                type (bytes, duration, int, number). Time types aggregation
                should use the timegroup element or timeslot.
  range-start:  The starting index of the first class. Defaults to 0. This 
                won't be used a the lower limit of the class. It is only 
                used to specify relatively at which values the classes 
                delimitation start. For example, if the range-start is 1,
                and the range-size is 5, a class ranging -4 to 0 will be 
                created if values are in that range. It can be supplied in
                any continuous unit (i.e 10k, 5m, etc.)
                This can also be the name of a user supplied param. 
   range-size:  This is the size of class. It can be supplied in
                any continuous unit (i.e 10k, 5m, etc.)
                It can also be the name of a user supplied param. 
    min-value:  All value lower then this boundary value will be 
                considered to be equal to this value. If this parameter
                isn't set, the ranges won't be bounded on the left side.
    max-value:  All value greater then this boundary value will be 
                considered to be equal to this value. If this parameter
                isn't set, the ranges won't be bounded on the right side.
    size-scale: The rate at which the size scale from one class to 
                another. If it is different then 1, this will create 
                a logarithmic distribution. For example, setting this to 
                2, each successive class will be twice larger then the
                precedent : 0-9, 10-29, 30-69, etc.
                                                                   -->
<!ELEMENT %LIRE.rangegroup;  (%LIRE.group-ops;)+                     >
<!ATTLIST %LIRE.rangegroup;
             field          NMTOKEN                       #REQUIRED
             range-start    CDATA                         #IMPLIED
             range-size     CDATA                         #REQUIRED 
             min-value      CDATA                         #IMPLIED   
             max-value      CDATA                         #IMPLIED 
             size-scale     CDATA                         #IMPLIED   >

<!--
    Field element.

    This element specify a field which should be use to group 
    records for computing the statistics.

    Attribute of field:
        name:   the field name.
                                                                   -->
<!ELEMENT %LIRE.field;  EMPTY                                        >
<!ATTLIST %LIRE.field;
             name       NMTOKEN                            #REQUIRED >

<!--
    Sum element.

    The sum element sums the value of a field in the group.

    Attribute of sum:
        name:   name for the statistics.
        field:  the field that should be summed.
                                                                   -->
<!ELEMENT %LIRE.sum;    EMPTY                                        >
<!ATTLIST %LIRE.sum;
             name       ID                                 #REQUIRED 
             field      NMTOKEN                            #REQUIRED >

<!--
    Avg element.

    The avg element calculate average of all value of a field in the group. 
    The average will be computed either on the number of records if the
    by-field attribute is left empty, or by the number of different values 
    that there are in the 'by-fields'

    Attribute of avg:
        name:   name for the statistics.
        field:  the field that should be averaged. If left unspecified the
                number of record will be counted.
        by-fields: the fields that will be used to dermine the count over
                   which the average is computed. 
                                                                   -->
<!ELEMENT %LIRE.avg;    EMPTY                                        >
<!ATTLIST %LIRE.avg;
             name       ID                                 #REQUIRED 
             field      NMTOKEN                            #IMPLIED 
             by-fields  NMTOKENS                           #IMPLIED  >

<!--
    Max element.

    The max element calculates the maximum value for a field in 
    all the group's records.

    Attribute of max:
        name:   name for the statistics.
        field:  the field for which the maximum value should found.
                                                                   -->
<!ELEMENT %LIRE.max;    EMPTY                                        >
<!ATTLIST %LIRE.max;
             name       ID                                 #REQUIRED 
             field      NMTOKEN                            #REQUIRED >

<!--
    Min element.

    The min element calculates the minimum value for a field in 
    all the group's records.

    Attribute of min:
        name:   name for the statistics.
        field:  the field for which the minimum value should found.
                                                                   -->
<!ELEMENT %LIRE.min;    EMPTY                                        >
<!ATTLIST %LIRE.min;
             name       ID                                 #REQUIRED 
             field      NMTOKEN                            #REQUIRED >

<!--
    Count element.

    The count element counts the number of records in the group if the 
    'fields' attribute is left empty. Otherwise, it will count the
    number of different values in the fields specified.

    Attribute of count:
        name:   name for the statistics.
        fields: Which fields to count. If unspecified all records in the 
                group are counted. If not, only different fields' value will
                be counted.
                                                                   -->
<!ELEMENT %LIRE.count;  EMPTY                                        >
<!ATTLIST %LIRE.count;
             name       ID                                 #REQUIRED 
             fields     NMTOKENS                           #IMPLIED  >

<!--
    Records element.

    The records element will put the content of selected fields in
    the report. This can be used in reports that shows events matching
    certain criteria.

    Attribute of records:
        fields:  the record's fields that should be included in the 
                 report.
                                                                   -->
<!ELEMENT %LIRE.records; 
                        EMPTY                                        >
<!ATTLIST %LIRE.records;
             fields      NMTOKENS                          #REQUIRED >
