<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="documentationTransformation_v1.1.xsl"?>
<schemaDocumentation xmlns="http://services.natureserve.org/docs/schemas/biodiversityDataFlow/1"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:schemaLocation="http://services.natureserve.org/docs/schemas/biodiversityDataFlow/1
                                        http://services.natureserve.org/docs/schemas/biodiversityDataFlow/1/">

    <!--
    ____________________________
    How to edit this document - that is, until a Database can be designed to hold this content.

    1) Mostly cut and paste and use previous examples
    2) Use the pipe "|" character to separate parts of the xpath expression. The XSL will correctly turn these into forward slashes.
    3) If you use the forward slash directly, it will be printed as-is.
    4) VALIDATE! This document has a schema, and if you violate, you have to fix it!

    REASON FOR USING THE PIPE IN XPATH: The xpath can get really long, and in a table output, it may need to be word-wrapped.
       In order to enhance the "human-readable" feature of the output, we put weak line breaks where the slashes are like this:
         /root<wbr/>/child<wbr/>/lowerLevel
       But as you can see, that is very difficult to maintain. Therefore, please enter the same value like this:
         /root|child|lowerLevel
       ... which is a lot easier to read and maintain. If you start the whole line with a pipe, that's OK too:
         |root|child|lowerLevel

    NO! THE PIPE TRICK DOES NOT WORK ANYWHERE EXCEPT IN THE XPATH ELEMENT.

    REASON FOR USING <![CDATA[ ... ]]> elements: If you want to hard-code some HTML, you have to put them inside these
       elements. That is because this document will not validate without doing that, and the XSLT will preserve the HTML
       so that it will render as HTML in the final output document.

    REASON FOR ESCAPING THE ampersand AND less-than SYMBOLS: if you don't escape them, they will never appear...
       &amp; &lt;

    -->
    <schemaDocumentationHeader>
        <schemaHtmlHeadTitle>Species Search Result Schema version 1.1</schemaHtmlHeadTitle>
        <schemaDescription>
            <![CDATA[This document is an easy-to-read (html) representation of the NatureServe Species Search Result Schema
            version 1.1. This schema describes the basic search result containers returned by simple REST queries. Most of
            the queries that accept specific search parameters will return summarized or very simple basic information about
            the resulting records. These are contained within the Species Search Result containers.<br/>
			<br/>
			The root element of responses is 'speciesSearchReport'.<br/>
			<br/>
			<b>Primary intent of this schema:</b> To describe a basic container for a series of query results as well as supply
            simplified data elements for quick result review purposes.
            ]]>
        </schemaDescription>
        <descriptionAddenda>
            This is not the normative representation of the draft standard.
            In the case of any conflict between the two representations, definitions
            and values in XML schema take precedence.
        </descriptionAddenda>
        <schemaStatusDetails>
            <schemaStatus>Final 1.0 Release</schemaStatus>
            <schemaStatus>For use in production systems for general query purposes.</schemaStatus>
        </schemaStatusDetails>
        <schemaSubmissionDetails>
            <submittedBy>NatureServe</submittedBy>
            <submissionDate>2008-09-17</submissionDate>
        </schemaSubmissionDetails>
        <changeLogDetails>
            <changeNote changeDate="2008-09-17">Update documentation to new standard.  Final version 1.1.</changeNote>
            <changeNote changeDate="2007-12-28">All elements and attributes covered.  Xpath checked.  Final version 1.0.</changeNote>
            <changeNote changeDate="2007-06-21">Created document</changeNote>
        </changeLogDetails>
        <!--
        <schemaReviewQuestions>
            <dataQuestionDetails>
                <dataQuestion questionDate="2006-12-26">If a user executes a search that returns 100 results, is the content expressed in this schema likely to be suitable for a cursory list of results?</dataQuestion>
                <dataQuestion questionDate="2006-12-26">Is there too much data for a cursory list? Do you have specific suggestions as to content?</dataQuestion>
            </dataQuestionDetails>
        </schemaReviewQuestions>
        <schemaGeneralNoteDetails>
            <schemaGeneralNote>If an optional attribute or element is not present in an instance document, that means that either the data is not being released, or the value is unknown.</schemaGeneralNote>
        </schemaGeneralNoteDetails>
        -->
    </schemaDocumentationHeader>
    <schemaDocumentationDetails>
        <documentationHtmlWeakLineBreak><![CDATA[<wbr/>]]></documentationHtmlWeakLineBreak>
        <documentationColumnHeadings>
            <dataElementName>Data Element</dataElementName>
            <dataElementDescription>Description</dataElementDescription>
            <nonDescriptiveNotes>Notes</nonDescriptiveNotes>
            <xpath><![CDATA[XPath to Schema Element or Attribute Name<br/>(Attributes <wbr/>preceded by <wbr/>"@" character)]]></xpath>
        </documentationColumnHeadings>
        <documentationDetails>
            <documentationGroup name="Basic Structure">
                <documentationItem>
                  <dataElementName>Species Search Report</dataElementName>
                  <dataElementDescription>
                      Contains the entire result, including the search conditions.
                  </dataElementDescription>
                  <nonDescriptiveNotes/>
                  <xpath>/speciesSearchReport</xpath>
                </documentationItem>
                <documentationItem>
                  <dataElementName>Schema Version</dataElementName>
                  <dataElementDescription>
                      Attribute of the root element containing the schema version number for this document.
                  </dataElementDescription>
                  <nonDescriptiveNotes>E.g. "1.0"</nonDescriptiveNotes>
                  <xpath>/speciesSearchReport@schemaVersion</xpath>
                </documentationItem>
                <documentationItem>
                  <dataElementName>Search Conditions</dataElementName>
                  <dataElementDescription>
                      Container for the search conditions.
                  </dataElementDescription>
                  <nonDescriptiveNotes/>
                  <xpath>/speciesSearchReport|conditions</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Species Result List</dataElementName>
                    <dataElementDescription>
                        Contains all of the query responses.
                    </dataElementDescription>
                    <nonDescriptiveNotes/>
                    <xpath>/speciesSearchReport|speciesSearchResultList</xpath>
                </documentationItem>
            </documentationGroup>
            <documentationGroup name="Search Conditions">
                <documentationItem>
                  <dataElementName>match</dataElementName>
                  <dataElementDescription>
                      Contains the search condition requiring a match
                  </dataElementDescription>
                  <nonDescriptiveNotes/>
                  <xpath>/speciesSearchReport|conditions|match</xpath>
                </documentationItem>
                <documentationItem>
                  <dataElementName>searchTerm</dataElementName>
                  <dataElementDescription>
                      This is the single or primary search term used in this query result.
                  </dataElementDescription>
                  <nonDescriptiveNotes/>
                  <xpath>/speciesSearchReport|conditions|match|searchTerm</xpath>
                </documentationItem>
            </documentationGroup>
            <documentationGroup name="Species Result">
                <documentationItem>
                    <dataElementName>Species Result</dataElementName>
                    <dataElementDescription>
                        Contains an individual response.
                        More than one response may be returned if the search string was ambiguous.
                    </dataElementDescription>
                    <nonDescriptiveNotes/>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Species Result UID</dataElementName>
                    <dataElementDescription>
                        This is the attribute with that result's UID value that can be used in a subsequent
                        call to get more detailed information about that result
                    </dataElementDescription>
                    <nonDescriptiveNotes>
                        Attribute
                    </nonDescriptiveNotes>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|@uid</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Global Species Uid</dataElementName>
                    <dataElementDescription>
                        This is the UID for the related global species.
                    </dataElementDescription>
                    <nonDescriptiveNotes/>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|globalSpeciesUid</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>NatureServe Explorer URI</dataElementName>
                    <dataElementDescription>
                        This is the URI for the NatureServe Explorer record related to this search result.
                    </dataElementDescription>
                    <nonDescriptiveNotes>
                        Note that this is generally a constructed URI based upon the global UID value and may not
                        refer to a retreivable records on NatureServe Explorer.
                    </nonDescriptiveNotes>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|natureServeExplorerURI</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Jurisdiction Nation Name</dataElementName>
                    <dataElementDescription>
                        If this result record is for species information at the National level or more local level, it will
                        include an element for the nation.
                    </dataElementDescription>
                    <nonDescriptiveNotes/>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|jurisdictionNationName</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Jurisdiction Nation Code</dataElementName>
                    <dataElementDescription>
                        Contains the 2-letter ISO abbreviation
                    </dataElementDescription>
                    <nonDescriptiveNotes>
                        Attribute
                    </nonDescriptiveNotes>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|jurisdictionNationName|@code</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Jurisdiction Subnation Name</dataElementName>
                    <dataElementDescription>
                        If this result record is for species information at the Subnational level or more local level, it will
                        include an element for the subnation.
                    </dataElementDescription>
                    <nonDescriptiveNotes/>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|jurisdictionSubnationName</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Jurisdiction Subnation Code</dataElementName>
                    <dataElementDescription>
                        Contains the 2-letter abbreviation.
                    </dataElementDescription>
                    <nonDescriptiveNotes>
                        Attribute
                    </nonDescriptiveNotes>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|jurisdictionSubnationName|@code</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Jurisdiction Scientific Name</dataElementName>
                    <dataElementDescription>
                        This is a simple unformatted scientific name for the result record. It is applicable to the record at
                        the search level (i.e., if this is a subnational level species record, the scientific name will be
                        the one used by the jurisdiction subnation, which is not necessarily the same name used at the global
                        or national level).
                    </dataElementDescription>
                    <nonDescriptiveNotes/>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|jurisdictionScientificName</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Jurisdiction Primary Common Name</dataElementName>
                    <dataElementDescription>
                        Optional primary common name for the lowest level jurisdiction specified. If no jurisdiction is specified,
                        this is the global primary common name.
                    </dataElementDescription>
                    <nonDescriptiveNotes/>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|commonName</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Jurisdiction Primary Common Name Language Code</dataElementName>
                    <dataElementDescription>
                        This is the code for the language of the common name.
                    </dataElementDescription>
                    <nonDescriptiveNotes>
                        Attribute, always "en"
                    </nonDescriptiveNotes>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|commonName|@language</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Jurisdiction Taxonomic Comments</dataElementName>
                    <dataElementDescription>
                        Optional taxonomic and classification comments for this species record. It is applicable to
                        the record at the search level (i.e., if this is a subnational level species record, the comments
                        will be related to that record).
                    </dataElementDescription>
                    <nonDescriptiveNotes/>
                    <xpath>/speciesSearchReport|speciesSearchResultList|speciesSearchResult|taxonomicComments</xpath>
                </documentationItem>
                <documentationItem>
                    <dataElementName>Last Observed Date Text</dataElementName>
                    <dataElementDescription>
                        Optionally the text recorded for the last observation date of this species occurrence, if any.
                    </dataElementDescription>
                    <nonDescriptiveNotes/>
                    <xpath>/speciesOccurrenceSearchReport|speciesOccurrenceSearchResultList|speciesOccurrenceSearchResult|lastObservedDateText</xpath>
                </documentationItem>
            </documentationGroup>
            </documentationDetails>
        </schemaDocumentationDetails>
    </schemaDocumentation>
    