[Rets-dev] Search responses and StandardNames

Tue Feb 20 16:07:06 CST 2007

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