[Rets-dev] Search responses and StandardNames

Tue Feb 20 22:16:52 CST 2007

Well, my point is that the specification does not define it so it leaves it
open to interpretation.  I also point out that MRIS' server passed
compliance and it returns Standard Names when StandardNames=1 in all three
output formats.  My point about consistency was merely to state that if we
get passed StandardNames=1 and a Format of STANDARD-XML, at least all the
output columns are consistent with all three output formats (the output
column set does not change between output formats - the word Format implies
structure and not the names of columns that are output).

I do see your point, but we need to clarify it one way or the other in the
specification.

So, let's see what all the Server Vendors say that they do and we can go
from there.

Now, what are we expecting to see when we get StandardNames=0 and
Format=STANDARD-XML - I believe that most Server Vendors in this case would
output the System Columns in some XML format and provide a DTD to support
this output format (and yes, you guessed it, that is what the MRIS server
does).  We felt it important that our users should be able to get either
System data or Standard Names data based on what they requested with the
StandardNames parameter.

I do think that this is a very reasonable interpretation of the
specification.  If it is not interpreted this way, there is actually no way
for server vendors to output a System Name XML document.  Which, in my
opinion, is a problem.

So, personally, I think that both input and output should be driven by the
StandardNames argument and if the specification is changed, that is what it
should change to.

Regards,
Sergio Del Rio
Templates 4 Business Inc.

-----Original Message-----
From: Paul Stusiak [mailto:pstusiak at falcontechnologies.com] 
Sent: February 20, 2007 3:11 PM
To: Sergio.Del.Rio at t4bi.com
Cc: 'Scott Gifford'; rets-dev at rets.org
Subject: Re: [Rets-dev] Search responses and StandardNames

Well, by golly, you appear to be correct. My comments around 4 and 5 are 
based on direct quotes from Bruce Toback. The points of 4 and 5 were 
intended to be included in the specification 1.7 or 1.8. I guess Bruce 
never got to them or he changed his mind and didn't tell me.

Given that you can form the select based on StandardNames=1 it may be 
possible to interpret the COMPACT result with a select as requesting 
only those field names and by inference, that the COMPACT result set 
should have the <COLUMNS> field names be what you selected. However, the 
StandardName=1 definition, Section 7.4.7 of RETS 1.7 is pretty clear - 
StandardNames=1 only refers to the field names passed on the request not 
on the response. It is completely silent on the field names used in the 
COMPACT formats response.

Since I got an earful from Bruce, I'm just passing it along. He was very 
adamant and clear that the two things - Format and StandardNames were 
not related.

Your interpretation appears to be inferring meaning to an ambiguous 
section - what is the field name values returned by the COMPACT and 
COMPACT-DECODED formats. Given that several other references inside the 
RETS document refer to using the two COMPACT formats with metadata, I 
think that a strong case can be made for the interpretation given here.

While your point on consistency is interesting, as I pointed out above, 
the description of StandardNames does not support this point. The server 
does not return completely different data sets based on StandardNames - 
it determines the select, class, resource and query names as per 7.4.7.

Perhaps you could agree that it may be possible to ask for the following 
information as a client:
Query=((ListPrice=100000),(DistanceFromBeach=1000)) StandardNames=0, 
Format=Standard-XML
where DistanceFromBeach does not appear in the Standard-XML and expect 
that it might be useful. After all, a request like
Select=ListingStatus, 
Query((ListPrice=100000),(DistanceFromBeach=1000)), StandardNames=1, 
Format=COMPACT
will return data that was not part of the query.

I don't quite follow your final comment. It is not consistent with 
section 7.4.7.

I think that, by extending your reasoning, it would be possible to argue 
that the COMPACT or COMPACT-DECODED format could return <COLUMNS> using 
both StandardNames and SystemNames. I suspect that this is not really 
what was intended here, although it is consistent with your comment that 
the COMPACT formats are silent on the field names.

Perhaps a poll of the vendors might shed some light on this. I think 
I'll start a new thread for that.

I should also clarify one of the points - that of the one-to-one 
correspondence of the StandardNames and Standard-XML. In October 2003, 
there was a long thread in RETS-DEV on this topic. The outcome was that 
the relationship was not one-to-one. Each of the Standard-XML elements 
were present in the StandardNames document but there may not be a 
corresponding element in the Standard-XML for every StandardName. This 
means that points 4 and 5 should use the retsdatadictionary200408.pdf as 
the reference and not Standard-XML.

Paul

Sergio Del Rio wrote:
> I would have to disagree with (4) and (5) below.  I guess it is an
> interpretation issue with the specification though.  It seems quite
> reasonable to me that if you query with StandardNames=1 the you could, and
> perhaps should, get ONLY the names that are defined in the Standard Names
> DTD as output whether you are asking for XML or you are asking for
> COMPACT/COMPACT-DECODED.
>
> The specification does not explicitly state anywhere that you MUST or MUST
> NOT send back System names or Standard Names when COMPACT or
COMPACT-DECODED
> are specified.  It is ambiguous on this point.  Therefore, I would say
that
> what comes back is dependent on the server implementation.  Some servers
> will return Standard Names ONLY (such as ours) when you ask for
> StandardNames as that was the interpretation.  Others may return System
> names when you query for COMPACT/COMPACT-DECODED and set StandardNames=1.
>
> For consistency, to me, it seems more reasonable to expect the data set
that
> is returned to be 100% consistent when a user sets StandardNames=1 and it
> should not be dependent on what format is being asked for.  If a server
> returns completely different data sets simply based on the setting of
> StandardNames, then it is not returning the same data set when XML is the
> requested output data format.
>
> Regards,
> Sergio Del Rio
> Templates 4 Business Inc.
>
> -----Original Message-----
> From: rets-dev-bounces at rets.org [mailto:rets-dev-bounces at rets.org] On
Behalf
> Of Paul Stusiak
> Sent: February 20, 2007 1:32 PM
> To: Scott Gifford
> Cc: rets-dev at rets.org
> Subject: Re: [Rets-dev] Search responses and StandardNames
>
> Not exactly. This tripped me up at first as well.
>
> The StandardNames request argument indicates what the field names used 
> by the query are. It does not make any statement about the result set.
>
> If it is set to '1' then the standard names are used.
>
> The Format request argument determines what the return set looks like.
>
> If you select COMPACT or COMPACT-DECODED, you will get back system names.
>
> So a system with some metadata like
>
> StandardName
> SearchType=Property
> Class=RES
> FieldName=ListPrice
>
> SystemName
> SearchType=Property
> Class=MLS_RES
> FieldName=PropertyListingPrice
>
> may refer to exactly the same field in the underlying repository (if it 
> isn't a Relational Database, I'd love to hear about it)
>
> So the two http requests
>
> SearchType=Property, Class=RES, Query=(ListPrice=100000), 
> Format=COMPACT, StandardNames=1
> and
> SearchType=Property, Class=MLS_RES, Query=(PropertyListingPrice=100000), 
> Format=COMPACT, StandardNames=0
> must return the same response set.
>
> There should be a one-to-one correspondence between the list of 
> StandardNames and the elements in the Standard-XML DTD.
>
> This example is a little contrived of course.
>
> The combinations are:
>
> 1. StandardNames=0, Format=COMPACT
> Query using SystemNames, as defined within the metadata. Response using 
> SystemNames with encoded lookup lists. Use the metadata to translate the 
> lookup lists into human readable form.
>
> 2. StandardNames=0, Format=COMPACT-DECODED
> Query using SystemNames, as defined within the metadata. Response using 
> SystemNames with decoded lookup lists. Lookup lists are in their human 
> readable form.
>
> 3. StandardName=0, Format=Standard-XML
> Query using SystemNames, as defined within the metadata. Response using 
> the Standard-XML DTD with decoded lookup lists. Lookup lists are in 
> their human readable form.
>
> 4. StandardNames=1, Format=COMPACT.
> Query using StandardNames as defined in the Standard-XML which should 
> match the retsdatadictionary200408.pdf (assuming that you are using the 
> DTD with the same version). Mismatches between the pdf and the dtd are 
> errors in the RETS Standard. Resolution is usually by posting first to 
> the dev list where the ambiguity may be resolved by consensus followed 
> by a Change Proposal to get the ambiguity removed from the standard. 
> Response using SystemNames with encoded lookup lists. Use the metadata 
> to translate the lookup lists into human readable form.
>
> 5. StandardNames=1, Format=COMPACT-DECODED.
> Query using StandardNames as defined in the Standard-XML. Response using 
> SystemNames with decoded lookup lists. Lookup lists are in their human 
> readable form.
>
> 6. StandardNames=1, Format=Standard-XML
> Query using StandardNames as defined in the Standard-XML. Response using 
> the Standard-XML DTD with decoded lookup lists. Lookup lists are in 
> their human readable form. The Format may have a dtd version attached to 
> it as described in the specifications. The current version of the DTD is 
> 1.7. The previous version is 1.5. Version 1.0.1 is deprecated.
>
> 7. Error condition.
> The client specified StandardNames and used SystemNames in the query or 
> vice versa. While you may choose to implement a permissive server and 
> map the mismatch on the server, it is perfectly reasonable to respond 
> with a reply code of 20200, the Unknown Query Field reply.
>
> 8. Extension format - XML documents using field names not present in 
> Standard-XML.
> RETS 1.x does not have explicit support for representing the SystemNames 
> as a DTD. Therefore, field names that are not mapped to a Standard-XML 
> element cannot be returned to the client in XML format. Given that this 
> is not ideal, there was some discussion around adding an explicit way to 
> represent this in the standard several years ago, but nothing happened. 
> Some servers support a non-standard extension to provide their 
> site-specific SystemNames using a DTD and delivering an XML document as 
> the response. This can be challenging because the system names change 
> "frequently" and this implies that the DTD will need to be changed. I 
> use frequently in quotation marks because, for many locations, the data 
> set changes in small ways several times per year. New fields are added, 
> data types may be corrected or other changes will occur that could 
> render the previous DTD obsolete or at the least, somewhat different 
> from the complete set. The obvious format name is System-XML.
>
> It is possible that there are some ambiguities in the specification so 
> please point any out that you find.
>
> As a point of interest, why does the client want RETS 1.5 rather than 
> RETS 1.7. RETS 1.7 underwent a much more rigorous review than 1.5 and 
> hopefully resolved ambiguities present in the 1.5 specification. It is 
> also the most current of the 1.x family of specifications.
>
> Paul
>
> Scott Gifford wrote:
>   
>> Hello,
>>
>> At a customer's request, I'm adding RETS 1.5 support to some existing
>> property search software.  I'm not 100% clear on which names are used
>> in the search results, and I wanted to confirm my understanding:
>>
>>   1. If StandardNames is 1 and Format is COMPACT or COMPACT-DECODED,
>>      DMQL2 parameter names query use standard names, and results use
>>      standard names
>>
>>   2. If StandardNames is 0 and Format is COMPACT or COMPACT-DECODED,
>>      DMQL2 parameter names use system names, and results use system
>>      names.
>>
>>   3. If StandardNames is 1 and Format is STANDARD-XML, DMQL2 parameter
>>      names use standard names, and results use system names, nested
>>      inside various levels of XML as described in the DTD.
>>
>>   4. If StandardNames is 0 and Format is STANDARD-XML, DMQL2 parameter
>>      names use system names, and results use system names, nested
>>      inside various levels of XML as described in the DTD.
>>
>>   5. The default for Format is STANDARD-XML, and the default for
>>      StandardNames is 0, so by default Case 4 above is used.
>>
>> Is this correct?  In particular, case 4 seems strange, since the query
>> is using system names while the results come back with standard names.
>>
>> Also, if there are fields that are not standard fields, it seems they
>> are accessible using COMPACT format by setting StandardNames to 0, but
>> impossible to access in XML format.  Is that right?
>>
>> ----Scott.
>> _______________________________________________
>> Rets-dev mailing list
>> Rets-dev at rets.org
>> http://lists.rets.org/mailman/listinfo/rets-dev
>>
>>
>>   
>>     
> _______________________________________________
> Rets-dev mailing list
> Rets-dev at rets.org
> http://lists.rets.org/mailman/listinfo/rets-dev
>
>
>
>   