<?xml version="1.0"?>
<!--
	XML Dump Schema for the Greater New York Region of NA Meeting List XML Access
	
	Version 1.0.9
	
	Changes:
		1.0.9		April 27th, 2008		Added the ability to GZIP the output.
		1.0.8		February 6th, 2008	Switched Root Domain to newyorkna.org.
		1.0.7		December 27th, 2007	Added some "nillable" attributes to a few fields that can be returned as nil.
		1.0.6		September 30th, 2007	Added one more parameter: "include_zip", which allows better mobile functionality.
		1.0.5		September 15th, 2007	Added new capabilities for decimating large searches, and for obtaining the number of results.
		1.0.4		July 23rd, 2007		Added support for format and region check in comments (no version change).
		1.0.4		June 14th, 2007		Corrected an error in these comments (no version change).
		1.0.4		June 2nd, 2007			Corrected an error in these comments (no version change).
		1.0.4		May 17th, 2007			Corrected a typo in these comments (no version change).
		1.0.4		May 14th, 2007			Added the <data_lat> and <data_long> elements.
		1.0.3		May 9th, 2007			Added the <db_version> element.
		1.0.2		May 6th, 2007			Added the <data_location_mapaddress> element.
		1.0.1		March 19th, 2007		Comment changes. Made this information clearer.
		
	This schema document can be found at:
	
		http://www.newyorkna.org/Events_and_Meetings/meetingdatalist.xsd
		
	This file is used to describe the XML returned by the "action=perform_search_xml" command.
	An optimized version (smaller file, without these comments) can be found at:
	
		http://www.newyorkna.org/Events_and_Meetings/meetingdatalist.php
	
	Another schema document can be found at:
	
		http://www.newyorkna.org/Events_and_Meetings/nax_info.xsd
	
	That file is used to describe the XML returned by the "action=get_info_xml" command.
	An optimized version (smaller file, without the comments) can be found at:
	
		http://www.newyorkna.org/Events_and_Meetings/nax_info.php

	and both are used by the XML access file at:
	
		http://www.newyorkna.org/Events_and_Meetings/xml_access.php
		
	In order to access the XML information described by this document, you must
	call the XML access file with the following parameter:
	
		action=perform_search_xml (XML Return Search)
		
	with the following corollary parameters:
	
		If it is a single meeting listing, then you also need to specify this:
			
			meeting_id=[The ID Number of the Meeting]
		
			If meeting_id is specified, only one meeting will be returned.
			If this parameter is specified, no other search criteria will be considered.
	
	You can also do a search that returns XHTML 1.1-compliant code for easy display on a Web page, by specifying
	these parameters:
	
		action=perform_search
		
			If meeting_id is specified, only one meeting (in verbose detail) will be returned.
			If this parameter is specified, no other search criteria will be considered.
			If multiple meetings are specified, then they will be returned in brief format, unless verbose is specified:
			
		verbose
			Set this to "1" to force the output to verbose, or "0" to force brief mode.
			The default behavior (if verbose is not specified) is that multiple meeting searches are in brief mode,
			and single meetings are in verbose mode.
			
		gzip_compress
			Just add this to the request string, and the data will be returned as a GZIP-compressed file.

	The same per-meeting data is returned by either search in XML (verbose is ignored). HTML uses a brief format for
	multiple meetings (which can be overridden by the "verbose" parameter), and a verbose format for single meetings.
		
		MULTIPLE MEETING SEARCH CRITERIA (This applies to both XML and XHTML Dumps):
			all_meetings
				If this is set to any value, then all other criteria are ignored, and all of the
				meetings are returned.
			
			search_string
				This is a search string. It doesn't just have to be a name, and it is used as a
				fairly arbitrary text search. It uses metaphone, which is a "sounds like" match.
				
			weekday_sel
				Look for meetings that occur on this weekday
				Expressed as an integer (1 = Sunday, 7 = Saturday)
				
			new_location_state
				The two-letter abbreviation for the state
				
			new_location_county
				The county name
				
			new_location_town
				The town name
				
			asc_array
				This is a group of integers, separated by commas (Hex %2C), that denote which ASC(s) to search.
				These are the codes given in the "id" attribute of the <data_asc_name> element.
				
			rsc_array
				This is a group of integers, separated by commas (Hex %2C), that denote which RSC(s) to search.
				These are the codes given in the "id" attribute of the <data_asc_name> element.
				
			worldid_specific
				If this is specified, then only the meeting with the given NAWS ID will be returned (this does not
				apply to ASC and RSC NAWS IDs).
			
			format_XX=1
				You can specify a search for a particular format code, by setting this to "1" for the given format.
				Replace "XX" with the two-letter format code. You can have more than one of these specified, as long
				as they reference different formats.
			
			orderby
				This specifies how the returned data will be sorted.
					weekday_sort = The data is sorted by weekday (Sunday first, Saturday last), then by town (Default)
					weekday_sort_1 = The data is sorted by weekday (Sunday first, Saturday last), then by time (Early first)
					town_sort = The data is sorted by town, then by weekday, and then by time.
					
			NOTE: The zip code search is only valid in the United States!
				
				zip_radius
					If this is specified, it is a radius, in miles, to search from a given zip code or longitude/latitude.
					If it is not specified, and a zip code is specified, the search will return only meetings with that zip
					code.
					
				zip_zip
					This is the zip code to be used as the center for the zip code search.
	
				zip_long
				zip_lat
					Alternatively, you can specify a longitude and latitude for the radius. Specify these instead
					of a zip code for a distance search from an arbitrary point. These are specified in degrees.
					
				include_zip
					Normally, specifying a zip and a radius is mutually exclusive of address information. If you specify
					a zip_zip, then any address information is ignored. If "include_zip=1" is specified, then both the
					address AND the zip radius are considered in the search. You have to be careful, because it is quite
					easy to end up with nil searches this way. It is meant for mobile phone use, which will use a system
					in which the zip_zip is used to specify a range, and towns within that range are selected.
				
			any_all
				This is either "AND" or "ANY". It specifies whether or not the criteria will all have to be met,
				or any of them. The default is "AND", which means that each criteria specified narrows the search.
				The exceptions are the asc_array and the rsc_array
				
	If the meeting search is to return multiple meetings, the <meetingdatalist>
	element will contain multiple <meetingdata> elements. If it is a single meeting
	search, then the element will contain only one.
	
		These parameters will allow you to "chop up" the results into sections:
		
			start_index
				This is the index (not ID) that the search results should start at.
		
			number_limit
				This is how many meeting results to return in this section.
				
			Example: If you have 342 meetings returned (This can be counted using the "count_results" action, below),
			you can retun the meetings in 50-meeting "slices":
			
				0-49		start_index=0&number_limit=50
				50-99		start_index=50&number_limit=50
				100-149		start_index=100&number_limit=50
				150-199		start_index=150&number_limit=50
				200-249		start_index=200&number_limit=50
				250-299		start_index=250&number_limit=50
				300-341		start_index=300&number_limit=50 (Remember that we're 0-based)
				
	There is an action that is used simply to find out how many meetings would be returned for a given search.
	
		action=count_results
		
			Specify this, along with the parameters above, and the return will be a (non-XML) simple integer, indicating
			the number of meetings that will be returned by the search.
		
			If this is specified, the start_index and number_limit parameters are ignored.
	
	You can also query the database for statistical information, using a different command. This can be used, for
	example, to fill a "Town" popup menu (via AJAX) in response to a new county or state selection. It can also
	provide statistics for other uses.
	
	Here are the parameters you use for a statistical information search:
	
		action=get_info_xml
			Tell the script to return statistical information.
			
		The following parameters are only valid for a "get_info_xml" search:
				
			info_key
				This is the principal "key" for statistical replies. It can have any of the following five values:
				
					"asc" (also the default, if no "info_key" parameter is passed).
						Returns data, sorted by ASC (Using the IDs in the "id" attribute of the <data_asc_name> elements).
						
					"town"
						Sort the returned data by towns.
						
					"county"
						Sort the returned data by county.
						
					"state"
						Sort the returned data by state.
						
					"zip"
						Sort the returned data by zip code.
						
					"formats"
						If this is specified, all the following parameters are ignored, and a dump of all supported
						format codes is returned.
						
					"regions"
						If this is specified, all the following parameters are ignored, and a dump of all supported
						regions and areas is returned.
						
			info_asc
				This is provided to filter the search to only meetings that occur in the given ASC. The value is the
				one used in the "id" attribute of the <data_asc_name> elements.
				
			info_town
				This is provided to filter the search to only meetings that occur in a given town.
				
			info_county
				This is provided to filter the search to only meetings that occur in a given county.
				
			info_state
				This is provided to filter the search to only meetings that occur in a given state.
				The value is the two-letter code for the state.
				
			info_zip
				This is provided to filter the search to only meetings that occur in a given zip code.
				The value is a 5-digit integer.
				
		Here is an example of how you might populate a "Towns" menu in response to a new County value:
		
			http://www.newyorkna.org/Events_and_Meetings/xml_access.php?action=get_info_xml&info_key=town&info_county=Suffolk&info_state=NY
			
		This would return statistical information for all of the towns within Suffolk County, New York.
		If a town does not contain any meetings, it will not be included in the returned data, so this will
		not return every town in Suffolk County; just those that have N.A. meetings.
		
		For each town returned, it would have the following information:
			
			It would list all the ASCs that have meetings in that town, and how many meetings are in each ASC.
			It would list all of the counties for that town (usually only one), and how many meetings are in each county.
			It would list all of the states for that town (almost always only one), and how many meetings per state.
			It would list all of the zip codes within that town, and how many meetings per zip code.

-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
	targetNamespace="http://www.newyorkna.org"
	elementFormDefault="qualified">
	<!-- Main container. May contain one or more meetings. -->
	<xs:element name="meetingdatalist">
		<xs:complexType>
			<xs:sequence maxOccurs="unbounded">
				<!-- Each meeting is bounded by one of these elements -->
				<xs:element name="meetingdata">
  					<xs:complexType>
						<xs:sequence>
							<!-- These are links to the single meeting reference. -->
							<xs:element name="link">
								<xs:complexType>
									<xs:sequence>
										<!-- This will return XML (Described by this schema) -->
										<xs:element name="xml" type="xs:anyURI"/>
										<!-- This will return detailed HTML -->
										<xs:element name="html" type="xs:anyURI"/>
									</xs:sequence>
								</xs:complexType>
							</xs:element>
							<!-- This is the NAWS Committee Code of this meeting. -->
							<xs:element name="data_world_id" nillable="true" type="xs:integer"/>
							<!-- This is the name of the meeting. -->
							<xs:element name="data_name" type="xs:string"/>
							<!-- This is its duration. -->
							<xs:element name="data_length" type="xs:time"/>
							<!-- These are additional comments on the meeting. -->
							<xs:element name="data_comments" type="xs:string"/>
							<!-- This is the name of the ASC to which the meeting belongs. -->
							<xs:element name="data_asc_name">
								<xs:complexType>
									<xs:simpleContent>
										<xs:extension base="xs:string">
											<!-- The "id" attribute contains the ID used for these searches. -->
											<xs:attribute name="id" type="xs:integer" />
										</xs:extension>
									</xs:simpleContent>
								</xs:complexType>
							</xs:element>
							<!-- If there is a URI to the ASC Web site, it is here. -->
							<xs:element name="data_asc_url" nillable="true" type="xs:anyURI"/>
							<!-- This is the NAWS committee code for the ASC. -->
							<xs:element name="data_asc_world_id" nillable="true" type="xs:integer"/>
							<!-- This is the name of the RSC to which the meeting belongs. -->
							<xs:element name="data_rsc_name">
								<xs:complexType>
									<xs:simpleContent>
										<xs:extension base="xs:string">
											<!-- The "id" attribute contains the ID used for these searches. -->
											<xs:attribute name="id" type="xs:integer" />
										</xs:extension>
									</xs:simpleContent>
								</xs:complexType>
							</xs:element>
							<!-- If there is a URI to the RSC Web site, it is here. -->
							<xs:element name="data_rsc_url" nillable="true" type="xs:anyURI"/>
							<!-- This is the NAWS committee code for the RSC. -->
							<xs:element name="data_rsc_world_id" nillable="true" type="xs:integer"/>
							<!-- This is a basic textual description of the location (Church, School, etc.) -->
							<xs:element name="data_location_text" type="xs:string"/>
							<!-- This is the street address of the meeting place. -->
							<xs:element name="data_location_street_address" type="xs:string"/>
							<!-- This is the neighborhood of the address (i.e. East Village, Harlem, Gordon Heights). -->
							<xs:element name="data_neighborhood" type="xs:string"/>
							<!-- This is the town of the address (NOTE: All NYC boroughs are "New York").. -->
							<xs:element name="data_location_town" type="xs:string"/>
							<!-- This is the county of the address (NOTE: All NYC boroughs are "counties"). -->
							<xs:element name="data_location_county" type="xs:string"/>
							<!-- This is the state for the location. -->
							<xs:element name="data_location_state" type="xs:string"/>
							<!-- This is the zip code for the location. -->
							<xs:element name="data_location_zip" nillable="true" type="xs:integer"/>
							<!-- This is the nation for the location (Currently, only "USA") -->
							<xs:element name="data_location_nation" type="xs:string"/>
							<!-- This is an automatically generated Google Maps URL for the location. -->
							<xs:element name="data_location_mapurl" nillable="true" type="xs:anyURI"/>
							<!-- This is a version of the address that has been conditioned for maps. -->
							<xs:element name="data_location_mapaddress" type="xs:string"/>
							<!-- This is additional location info. (Example: At the Corner of 1st Avenue, and Last St.) -->
							<xs:element name="data_location_info" type="xs:string"/>
							<xs:element name="data_last_modified" type="xs:dateTime"/>
							<xs:element name="data_lat" type="xs:float" nillable="true"/>
							<xs:element name="data_long" type="xs:float" nillable="true"/>
							<!-- The day of the week this meeting gathers. -->
							<xs:element name="data_evt_weekday">
								<xs:complexType>
									<xs:sequence>
										<!-- Expressed as an integer (1 = Sunday, 7 = Saturday) -->
										<xs:element name="number" type="xs:integer"/>
										<!-- Spelled out in English -->
										<xs:element name="name" type="xs:string"/>
									</xs:sequence>
								</xs:complexType>
							</xs:element>
							<!-- The time that the meeting starts -->
							<xs:element name="data_start_time">
								<xs:complexType>
									<xs:sequence>
										<!-- Spelled out (Ex. 7AM, 8:30PM) -->
										<xs:element name="display" type="xs:string"/>
										<!-- Standard XML time format -->
										<xs:element name="time" type="xs:time"/>
									</xs:sequence>
								</xs:complexType>
							</xs:element>
							<!-- This is an arbitrary-length meeting format/restriction list. -->
							<xs:element name="data_format">
								<xs:complexType>
									<xs:sequence maxOccurs="unbounded">
										<!-- Each format is bounded by one of these. -->
										<xs:element name="single_format">
											<xs:complexType>
												<xs:sequence>
													<!-- This is the format code (One or two letters). -->
													<xs:element name="code" type="xs:string"/>
													<!-- This is a textual description of the format. -->
													<xs:element name="description">
														<xs:complexType>
															<xs:sequence>
																<!-- In English -->
																<xs:element name="english" type="xs:string"/>
																<!-- In Spanish -->
																<xs:element name="spanish" type="xs:string"/>
															</xs:sequence>
														</xs:complexType>
													</xs:element>
													<!-- This is a brief description that can be used in place of the format -->
													<xs:element name="othertext">
														<xs:complexType>
															<xs:sequence>
																<!-- In English -->
																<xs:element name="english" type="xs:string"/>
																<!-- In Spanish -->
																<xs:element name="spanish" type="xs:string"/>
															</xs:sequence>
														</xs:complexType>
													</xs:element>
												</xs:sequence>
											</xs:complexType>
										</xs:element>
									</xs:sequence>
								</xs:complexType>
							</xs:element>
						</xs:sequence>
						<!-- The meetingdata element has one attribute, "id", which is the meeting ID. -->
						<xs:attribute name="id" type="xs:integer" />
					</xs:complexType>
				</xs:element>
				<!-- The last one will have this at the end. It is a link to access the same search in HTML. -->
				<xs:element name="htmlsearchlink" type="xs:anyURI" minOccurs="0" maxOccurs="1"/>
				<!-- This is the version of the DB that generated the dump.. -->
				<xs:element name="db_version" type="xs:string" minOccurs="0" maxOccurs="1"/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
</xs:schema>