The proposal does not require that clients make use of the information, nor does it require that servers make it available. However, a client that makes use of the information may be able to provide a richer data set to the user or optimize fetches from the server.

A new metadata type called ForeignKeys needs to be added to the specification Chapter 11 section 4. The following is the description of METADATA-FOREIGNKEYS and its purpose:

Foreign Keys allows the operator of a particular server to advertise its supported parent child relationships. The Foreign Keys metadata starts with a <METADATA-FOREIGNKEYS> tag with Version and Date attributes. This is followed by a <COLUMNS> section, which contains the name of the fields as defined in Table 1 followed by the <DATA> section, which contains the actual field information. The Foreign Keys metadata has the following format:

<METADATA-FOREIGNKEYS Version="foreignkey-version" Date="foreignkey-date"> <COLUMNS>foreignkey-field * (•foreignkey -field) •</COLUMNS> <DATA> foreignkey -data*(• foreignkey-data) •</DATA> </METADATA-FOREIGNKEYS>

foreignkey-version ::= 1*2DIGITS.1*2DIGITS.1*5DIGITS

This is the version of the ForeignKeys metadata. The convention used is a "<major>.<minor>.<release>" numbering scheme. Every time any element of the ForeignKey metadata changes the version number MUST be incremented.

foreignkey-date ::= DATE The latest change date of the ForeignKey metadata.

foreignkey-field ::= <Field Name from Table 1> foreignkey-data ::= <valid value as defined in Table 1>

An example ForeignKey section follows:

GetMetadata request: Type:  METADATA-FOREIGNKEYS Compact Reply: <METADATA-FOREIGNKEYS Version="1.00.000000" Date="Wed, 23 Jan 2002 12:37:38 GMT"> <COLUMNS>PARENT_RESOURCE_ID•PARENT_CLASS_ID•PARENT_SYSTEMNAME• CHILD_RESOURCE_ID•CHILD_CLASS_ID•CHILD_SYSTEMNAME•</COLUMNS> <DATA>Property•RES•MLSNUM•TAX•TAX•MLSNUM•</DATA> <DATA>Property•RES•MLSNUM•History•History•MLSNUM•</DATA> <DATA>Property•RES•MLSNUM•OpenHouse•OpenHouse•MLSNUM•</DATA> <DATA>Property•RES•ListingAgentID•Agent•Agent•AgentID•</DATA> <DATA>Property•RES•COListingAgentID•Agent•Agent•AgentID•</DATA> <DATA>Property•RES•SellingAgentID•Agent•Agent•AgentID•</DATA> <DATA>Property•RES•COSellingAgentID•Agent•Agent•AgentID•</DATA> <DATA>Property•RES•ListingOfficeID•Office•Office•OfficeID•</DATA> <DATA>Property•RES•SellingOfficeID•Office•Office•OfficeID•</DATA> </METADATA-FOREIGNKEYS>

Field Name	Content Type	Description
Foreign_Key_ID	1*32ALPHANUM	A Unique ID that represents the foreign key combination.
Parent_Resource_ID	1*32ALPHANUM	The ResourceID (Table 11-2) of the resource that for which this field functions as a foreign key . The name given MUST appear in the METADATA-RESOURCE table
Parent_Class_ID	1*32ALPHANUM	The name of the resource class for which this field functions as a foreign key. This name MUST appear in the RESOURCE-CLASS table for the given Parent_Resource_ID
Parent_SystemName	1*32ALPHANUM	The SystemName of the field in the given resource class that should be searched for the value given in the this field. This name must appear as a SystemName in the METADATA-TABLE section of the metadata for the Parent_Class_ID, and the named item must have its Searchable attribute set to TRUE.
Child_Resource_ID	1*32ALPHANUM	The ResourceID (Table 11-2) of the resource that for which this field functions as a foreign key . The name given MUST appear in the METADATA-RESOURCE table.
Child_Class_ID	1*32ALPHANUM	The name of the resource class for which this field functions as a foreign key. This name MUST appear in the RESOURCE-CLASS table for the given Child_Resource_ID.
Child_SystemName	1*32ALPHANUM	The SystemName of the field in the given resource class that should be searched for the value given in this field. This name must appear as a SystemName in the METADATA-TABLE section of the metadata for the Child_Class_ID, and the named item must have its Searchable attribute set to TRUE.

If the server does not transmit values for all six  of these fields, the client MUST operate as if it had received none of them.

Each combination of the seven fields MUST be unique.

The nesting of Foreign Keys MUST be such that recursive searches are NOT REQUIRED to obtain data for Well Known Fields as defined in the RETS DTD.  However, nesting of foreign Keys is allowed ecept in these cases.

3.2 Implementation Notes

When displaying data from a particular resource, a client MAY use the child resource information in the metadata to retrieve and display related records from other resources. It does so by creating a search on the specified resource and resource class using a simple equal-to query. There is no restriction on the content of this query, however, so the server should not anticipate any particular sequence of operations when it supplies child resource metadata.

This is not meant to replace the lookup metadata in 11.4.2 or lookuptype metadata in 11.4.3. The purpose of the new metadata is to advertise the foreign key relationships between the major tables of a system.

6.1 Agent Listings

The RETS Client (client) request data from the server for the property listing and needs to have UP TO DATE Agent information as part of the property data. The client retrieves the new Foreign Key metadata to lookup up the RETS Well Known Resource and Class Name for Agent and gets the field name that links to the Well Known Residential Resource and Class name field. The following record is retrieved from the metadata:

<DATA>Property•RES•ListingAgentID•Agent•Agent•AgentID•</DATA>

The client proceeds to download all agent records modified TODAY+ once per hour and all Property Records modified TODAY+ once per hour

Because of the knowledge the client has obtained from the Foreign Key metadata it can bring up a listing and have all the Agent information instead of just a few fields normally listed in the flat record

OR

Because the CanChildBeParent is TRUE, the client can bring up an Agent and show all property listing this agent has.

This is all accomplished automatically for the client and can easily change should the Metadata version be incremented.

6.2 Property History and Agent Information

The RETS Client (client) request data as needed from the RETS Server. It does not maintain a local copy of the database, however it does maintain the Full Metadata structure.

The following is the data for this example in the Foreign Key metadata.

<DATA>Property•RES•SellingAgentID•Agent•Agent•AgentID•</DATA> <DATA>Property•RES•MLSNUM•History•RES•MLSNUM•</DATA>

The client receives a request from the user to download a particular property record. The server delivers the record to the client.

The client then receives a request from the user to download the History of this property. The client Looks up the History relationships to the property and determines the key field. It then generates the appropriate request to the RETS Server and the server returns the correct data.

Now the user would like to see the Selling Agent for a property. The client Looks up the Agent relationship to the property for SellingAgentID and generates the appropriate request to the server. The server responds with the data.

This is all accomplished automatically for the client and can easily change should the Metadata version be incremented.

6.3 The unknown (Why there should not be limitations on nesting)

Let's say an MLS System wanted to introduce something new to the market that has never been seen before. For the sake of this example let's say it is a Transaction System.

We have a MLS System that has published its Transaction Resource and Class Types.

We have the following foreign key metadata:

<DATA>Property•RES•MLSNUM•TRANSACTION•RES•MLSNUM•</DATA> <DATA>TRANSACTION•RES•TRANSACTION_ID•TRANSACTION•HISTORY•PARENT_TRANSACTION_ID•</DATA> <DATA>TRANSACTION•HISTORY•PARENT_TRANSACTION_ID•TRANSACTION•HISTORY•CHILD_TRANSACTION_ID•</DATA> <DATA>TRANSACTION•HISTORY•NEXT_TRANSACTION_ID•TRANSACTION•HISTORY•CHILD_TRANSACTION_ID•</DATA>

The transaction client has the task of obtaining the transaction history for a particular property. The data structure for the Transaction Database is recursive in nature using nodes to follow paths of transactions. The client will be required to recurse those nodes to their completion to display the complete transaction history. The client is also capable of adding it's own transaction nodes.

This example albeit incomplete demonstrates that given the Foreign Key metadata, a client capable of using this new metadata type and traversing the tree that it represents would be prepared for most future expansions of the RETS Specification. It also opens a whole new world up to RETS. Nesting should not be limited in this proposal except for well known RETS Names.