RCP 87 - RETS 1.7.2 Errata Document

Synopsis

Several errata have been discovered in the 1.7.2 document and RCPs. They have been collected into an errata document to assist users in implementing the 1.7.2 standard correctly.

This document incorporates the critical errata.

Rationale

Several problems that may be major or critical have been identified within the 1.7.2 standard and may impede interoperability between client and server and between server systems.

Proposal

The document "RETS 1.7.2 Errata 2010-04" contains the known major and critical errata to the 1.7.2 standard. Adoption of this document is recommended to assist developers in implementing 1.7.2.

The document is provided in-line for convenience.

Introduction

In general, the specification document body text represents the correct information. This is not true in all cases. This document describes several problems with the 1.7.2 document.

Erratum 1

Table 11-40, Validation External refers to a Field called ValidationExternalName. This is correct. Table 11-42, Validation External Type refers to a Field called ValidationExternalName. This is correct. The example in B.18, ValidationExternalType has a field tag of ValidationExternal. This is not correct. It should be replaced by ValidationExternalName.

Reported by Paul Stusiak

Reported by Libor Viktorin

Reported by Phillip Paulson

Erratum 2

Table 11-12, METADATA-TABLE the 'Date' data type is RETSDATE. There is no RETSDATE defined in 'Section 2.3, Atoms and Primitives'. The correct value for any reference to this atom is full-date.Using the atom full-date matches the format from the 1.5 specification document.

Table 13-4 also has a reference to RETSDATE. This should readfull-date.

Reported by Paul Stusiak

Reported by Joshua Vosper

Reported by Mark Klein

Reported by Troy Davisson

Erratum 3

Table 11-12, METADATA-TABLE the 'DateTime' data type is full-date.The correct value for this data type is RETSDATETIME. Using the atom full-date matches the format of the Time RCP. This is different from the 1.5 specification document.

Reported by Mark Klein

Reported by Troy Davisson

Erratum 4

In section 11.4.8, Table 11-34 Validation LookupType refers to a tagPARENTFIELDS that is not defined in the document or the DTD. By inference, the correct information is PARENTFIELD1 andPARENTFIELD2, described in Table 11-32 of section 11.4.7 previous section.

Reported by Libor Viktorin

Erratum 5

In section 3.3, the term RETS-Version describes the version as a three element value of the form "<major>.<minor>.<release>" and discusses it in terms of RFC 2616. RFC2616 only has a two element version described. The intent is to make sure that the version is treated numerically instead of alphabetically when comparing versions.

The relevant section of RFC 2616 is section 3.1

HTTP uses a "<major>.<minor>" numbering scheme to indicate versions

of the protocol. The protocol versioning policy is intended to allow

the sender to indicate the format of a message and its capacity for

understanding further HTTP communication, rather than the features

obtained via that communication. No change is made to the version

number for the addition of message components which do not affect

communication behavior or which only add to extensible field values.

The <minor> number is incremented when the changes made to the

protocol add features which do not change the general message parsing

algorithm, but which may add to the message semantics and imply

additional capabilities of the sender. The <major> number is

incremented when the format of a message within the protocol is

changed. See RFC 2145 [36] for a fuller explanation.

The version of an HTTP message is indicated by an HTTP-Version field

in the first line of the message.

HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT

Note that the major and minor numbers MUST be treated as separate

integers and that each MAY be incremented higher than a single digit.

Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is

lower than HTTP/12.3. Leading zeros MUST be ignored by recipients

and MUST NOT be sent.

The meaning of this is that the version should have the following BNF representation:

RETS-Version = 1*DIGIT "." 1*DIGIT "." 1*DIGIT

While in general, this should be a sufficient definition, the use of theRETS-Version as a maker for versioning metadata may require additional digits to correctly represent the version of metadata. Specifically, implementers should be permissive in the use ofRETS-Version and should accept values where there are more than a single digit for the release or minor positions.

Reported by Mark Klein

Erratum 6

In the specification document, on page 11-19 in 'Table 11-21 Metadata Content: Lookup' the field names include 'Version' and 'Date'. This is incorrect. The document values should be changed to LookupTypeVersion and LookupTypeDate.

The 1.7.2 DTD set has the correct values, 'LookupTypeVersion' and 'LookupTypeDate'.

Reported by Ryan Bonham

Erratum 7

The METADATA BNF does not allow for empty fields. This contradicts the descriptions next to the BNF, that often states that the field is optional and the DTD that states that they are not required. Common practice also has implementations that permit empty fields. The BNF is incorrect and the BNF for metadata should be revised to allow for NULL values. People implementing RETS systems should be aware that many server systems may permit empty fields.

Reported by Ryan Bonham

Erratum 8

The Foreign Key Metadata element has an inconsistency in the 1.7.2. The tag label for the metadata content is referenced in three places.

METADATA-FOREIGN_KEYS is specified on page 11-9 of Section 11.2.3

METADATA-FOREIGN_KEYS is specified in the RETS 1.7.2 DTD on page 6 in line 273

METADATA-FOREIGNKEYS is specified on page B-2 of Appendix B-2

It is also referenced in Table 11-12, Metadata Content, Field ForeignKeyName in the Description column as METADATA-FOREIGNKEYS.

The correct use is METADATA-FOREIGN_KEYS.

Reported by Mark Klein.

Erratum 9

The BNF definition of RETS-Response has a missing character '['. It should read

RETS-response::=body-start-line

response

[rets-status]

[body-end-line]

Reported by Gary Little

Erratum 10

The text of Section 3.5, reply codes is confusing. In 1.7.2, it reads

Applicable reply-codes can be found under specific transactions.

A revised version of this sentence is

reply-codes are specific to a transaction. Please refer to the applicable transaction for the meaning of the reply-code or refer to Appendix C of this document for a consolidated list.

Reported by Gary Little

Erratum 11

The last sentence of the first paragraph of Section 3.8 should read

If the server supports one of the compression methods accepted by the client, it can include a Content-Encodingheader in its response indicating the compression method it has chosen.

Reported by Gary Little

Erratum 12

In Table 11.6 of the METADATA-RESOURCE section, the KeyField is currently defined as a RETSID. This should be replaced byRETSNAME to make it consistent with the later reference to SystemName in Table 11-12.

Reported by Mark Klein

Erratum 13

The multipart example on page 43 under section 5.11.1 General Construction and again under 5.11.2 contains a very minor formatting error.

In a multipart response, all boundaries need to appear as "CRLF--boundary" which means that every boundary will have a CRLF in front of it.

Every HTTP response needs to contain a blank line between the HTTP header and HTTP body. As a result, the first boundary needs to be 2 blank lines away from the HTTP headers. On servers that don't send the "2" CRLF's, RETS clients miss the first boundary and discard it (since they treat it as the preamble) and start processing at the 2nd boundary for the 2nd photo. As the document is right now, the example is sharing the blank line between the HTTP and boundary divider.

The work around on the client-side (unless the developer thinks that putting in this "hack" is too dirty): automatically pad the HTTP body with CRLF's since everything before the first boundary and everything after the last boundary is ignored by default. If the server already has this correctly, the extra line breaks are ignored anyway. If the server doesn't have this correctly, the padding makes the response good automatically.

Reported by Troy Davisson

Erratum 14

Table 11-12 has a field named ModTimeStamp. The description is incorrect. It currently reads

When true, indicates that changes to this field update the class’sModTimeStamp field.

There is no ModTimeStamp field in the Class metadata. It should read

When true, indicates that changes to this field will cause the Class header Datefield and the Class body TableDate field to have the value of the date and time of the change.

Reported by Joshua Vosper

Erratum 15

The improvements to LookupMulti require the change proposal LookupMulti Quoting Rule, adopted at the December 2008 meeting in Scottsdale, Arizona.

Reported by Matt McGuire

Reported by Ryan Bonham

Erratum 16

Section 13.1 requires revision to "... if a particular field for some record is undefined or is suppressed for authorization reasons, the value MUST be represented by two delimiters with no intervening space unless the restricted indicator is set. In that case, the value MUST be represented by the restricted indicator."

Reported by Ryan Bonham

Erratum 17

Section 3.10 describes the calculation of the User Authorization digest. This description conflicts with the definition described in Section 3.4. Specifically, section 3.10 defines the calculation as HEX while section 3.4 defines the product of section 3.10 as LHEX. Since this is based on the digest authentication scheme of RFC 2617 which uses LHEX, it is suggested that section 3.10 be changed to refer to LHEX rather than HEX. Thus, the product term should read:

ua-digest-response::= LHEX(MD5( LHEX(a1):RETS-Request-ID:session-id:version-info))

Reported by Rob Overman

Erratum 18

The example in Section B.8, METADATA-OBJECT includes a field called StandardName. This field is not described in the definition for METADATA-OBJECT in Table 11.19 and should be removed from the example.

Reported by Sergio Del Rio

Erratum 19

The definition of MIMEType for METADATA-OBJECT in Table 11.19 implies that only a single mime type may be expressed for a specific object type. This is not how RFC 2616 and RFC 2045 describe the Accept parameter. It should be possible for a single ObjectType to have more than one mime-type, for example, a Photo may have image/jpg and image/gif as mime-types. The correct Content Type for this field should read "A comma separated list of MIME type/subtype per 2045". The correct Description for this field should read "The mime-type/subtypes of the object type. This is the collection of object media encodings available for the objects on this system. Objects may have one or more mime-type of those listed in this field. This list is the mime-types that can be passed by the client in the "Accept" parameter in the GetObject transaction. All objects can return a mime-type of text/xml as an error code/error reply when a fault occurs in the GetObject transaction."

Reported by Paul Stusiak

Clarification 1

The Compliance Workgroup requested that a note be added to Figure 11.1 Metadata Structure. This note should identify that the box labels are not the header tag values used in a GetMetadata request. The suggested working is "The names of the metadata provided in the figure are not indicative of the header tag values that should be used in a GetMetadata transaction Request or Response. For the proper metadata-id value please refer to the RETS 1.7.2 DTD."

Reported by the Compliance Workgroup

Impact

Compatibility

This change proposal is only compatible with the 1.7.2 standards document