RESO Enums To Lookups Transition

This document explains the differences you will need to handle between how we used to feed out our data to how we will feed out the data once this change goes live.
Summary of Changes
On March 8, 2022 at 8pm MT, we will have an hour maintenance window during which we will release the following changes to our production data and metadata. Once the system comes back up the following changes will be live on all new records returned from the system. 
NOTE: We will not backfill older records immediately and it will take time to do that.  If for some reason you need to pull older data after the release, your system will need to be able to handle receiving the data both ways.
It is not necessary to re-pull old data for this release. For older data, you should continue to use the values you have in your local data.  If they change you will receive an update in the API during normal replication.
The changes that will impact the broadest set of consumers:
Changing Multiple value strings to Arrays in the output.
Renaming the expanded Rooms and UnitTypes in the data and in the expand requests.
Searching by StandardStatus & PropertyType no longer requires Enums prefix notation.
 The other changes pertain mostly to metadata and will only be relevant if your system has need to consume and stay up to date with that information:
New Lookup Resource.
Metadata has different types for fields that were enumerated.
Metadata no longer contains enumerations.  Obtain lookups through the Lookup resource.
Testing Before The Release
All of this code is live today on the demo server.  You should be able to use your existing token to query the demo server to test out the new code prior to the release.  If your token is not working in demo or you do not yet have a token, please reach out to [email protected] for further assistance.
The endpoint for the demo server is https://api-demo.mlsgrid.com/v2​
You can use all the same replication queries you would normally use but keep in mind that the data set on demo is limited and very stale. 
Tip 1: You may want to configure the top value to a smaller value (in the demo environment ONLY) in order to simulate the kind of request volume you might process in a live environment where there is significantly more data to process.
Tip 2: When done testing, don't forget to set your top value back to normal before executing against production or else your requests will be very inefficient and could result in poor performance. 
​
Change
Resources
Affects
Description
​StringList to Array of Strings​
ALL
Data
Previously, fields that were multiple value fields were returned in the data as comma separated string lists. These will now be returned in the data as an array of strings.
​Rooms and UnitTypes​
Property
Metadata, Data
We are changing PropertyRooms and PropertyUnitTypes in expand to match the variable names expected by RESO which are Rooms and UnitTypes
​New Lookups Resource​
Lookup
Replication, Metadata, Data
There will be a new resource requiring replication.  The resource will contain all of the lookup values for an mls which were previously contained in the enumerations section of the metadata. 
Search By Value
ALL
Replication
We allow you to search enumerated fields by value now instead of by Enum code.
​Metadata Type on Enumerated Fields​
ALL
Metadata
The type value in the metadata for fields that were enumerated used to contain a link to the enums section of the metadata but will now be a String with an annotation indicating the name of the Lookup that applies to that field.
​Enumerations in Lookup Resource​
ALL
Metadata
The enumerations will no longer be enumerated within the metadata returned by the api service.  to obtain the lookups for a given field, the lookup resource must be replicated into your local system and accessed through your local copy of the lookup data.
StringList to Array of Strings
RESO expects fields defined as type 'String List, Multi' to be returned as an array of strings.  We are changing all fields that previously output as a comma separated string of multiple string values to be an array of multiple string values.  
OLD example field output: 
"Appliances": "Washer Dryer Hookup,Dishwasher,Oven,Refrigerator",
NEW example field output
"Appliances": [
                "Washer Dryer Hookup",
                "Dishwasher",
                "Oven",
                "Refrigerator"
            ],
Fields Changing To Arrays
Not every mls contains all of these fields.  If any of these fields is mapped in their metadata, it will change to be an array of strings.
Property
AccessibilityFeatures
Appliances
ArchitecturalStyle
AssociationAmenities
AssociationFeeIncludes
Basement
BodyType
BuildingFeatures
BusinessType
BuyerAgentDesignation
BuyerFinancing
CoBuyerAgentDesignation
CoListAgentDesignation
CommonWalls
CommunityFeatures
ConstructionMaterials
Cooling
CurrentFinancing
CurrentUse
DevelopmentStatus
Media
Permission
Rooms
RoomFeatures
Member
SyndicateTo
Office
SyndicateTo
Rooms and UnitTypes
We initially implemented our expand for Rooms and UnitTypes to be named the same as the name of the RESO collection.  However, RESO expects these collections to be named differently within the Property data on expand and to point to those collections in the nav links.  This is how the requests and data will change:
Expand Requests
OLD Expand Request: 
https://api-demo.mlsgrid.com/v2/Property?$expand=PropertyRooms,PropertyUnitTypes,Media&$filter=OriginatingSystemName eq 'actris'
NEW Expand Request: 
https://api-demo.mlsgrid.com/v2/Property?$expand=Rooms,UnitTypes,Media&$filter=OriginatingSystemName eq 'actris'
Rooms
OLD Expanded Data: 
"PropertyRooms": [
        {
            "RoomDimensions": "13X14",
            "RoomType": "Bedroom 1",
            "RoomFeatures": "Full Bath",
            "RoomKey": "RTC1733786Group_1"
        },
        {
            "RoomDimensions": "12X11",
            "RoomType": "Bedroom 2",
            "RoomKey": "RTC1733786Group_2"
        }
    ],
NEW Expanded Data: 
"Rooms": [
        {
            "RoomDimensions": "13X14",
            "RoomType": "Bedroom 1",
            "RoomFeatures": "Full Bath",
            "RoomKey": "RTC1733786Group_1"
        },
        {
            "RoomDimensions": "12X11",
            "RoomType": "Bedroom 2",
            "RoomKey": "RTC1733786Group_2"
        }        
    ],
UnitTypes
OLD Expanded Data: 
"PropertyUnitTypes": [
                {
                    "UnitTypeActualRent": 1,
                    "UnitTypeType": "Unit 1",
                    "UnitTypeBathsTotal": 1,
                    "UnitTypeBedsTotal": 2,
                    "UnitTypeKey": "RTC2405117Group_1"
                },
                {
                    "UnitTypeActualRent": 1,
                    "UnitTypeType": "Unit 2",
                    "UnitTypeBathsTotal": 1,
                    "UnitTypeBedsTotal": 2,
                    "UnitTypeKey": "RTC2405117Group_2"
                }
            ]
NEW Expanded Data: 
"UnitTypes": [
                {
                    "UnitTypeActualRent": 1,
                    "UnitTypeType": "Unit 1",
                    "UnitTypeBathsTotal": 1,
                    "UnitTypeBedsTotal": 2,
                    "UnitTypeKey": "RTC2405117Group_1"
                },
                {
                    "UnitTypeActualRent": 1,
                    "UnitTypeType": "Unit 2",
                    "UnitTypeBathsTotal": 1,
                    "UnitTypeBedsTotal": 2,
                    "UnitTypeKey": "RTC2405117Group_2"
                }
            ]
Metadata
OLD Metadata Nav Links: 
<NavigationProperty Name="PropertyRooms" Type="Collection(com.mlsgrid.metadata.PropertyRooms)" />
<NavigationProperty Name="PropertyUnitTypes" Type="Collection(com.mlsgrid.metadata.PropertyUnitTypes)" />
NEW Metadata Nav Links: 
<NavigationProperty Name="Rooms" Type="Collection(org.reso.metadata.PropertyRooms)"/>
<NavigationProperty Name="UnitTypes" Type="Collection(org.reso.metadata.PropertyUnitTypes)"/>
Search By Value
Because enumerations are being replaced by Lookups, we will now allow searching by the Lookup value instead of requiring the old Enums prefix notation. The old way of querying will continue to work but new requests should move to using the new way. This applies to the PropertyType and StandardStatus query filters.
OLD Query by StandardStatus Request:
https://api-demo.mlsgrid.com/v2/Property?$filter=StandardStatus eq Enums.StandardStatus'ActiveUnderContract' and OriginatingSystemName eq 'actris'
NEW Query by StandardStatus Request:
https://api-demo.mlsgrid.com/v2/Property?$filter=StandardStatus eq 'Active Under Contract' and OriginatingSystemName eq 'actris'
New Lookups Resource
There will be a new resource requiring replication.  The resource will contain all of the lookup values for an mls which were previously contained in the enumerations section of the metadata. 
We recommend using the following queries to replicate and keep your Lookup data up to date:
Initial Data Import Request
https://api.mlsgrid.com/v2/Lookup?$filter=OriginatingSystemName eq ‘actris’ and MlgCanView eq true
Regular Replication Requests
https://api.mlsgrid.com/v2/Lookup?$filter=OriginatingSystemName eq ‘actris’ and ModificationTimestamp gt [GREATEST ModificationTimestamp FROM YOUR DATABASE FOR THIS RESOURCE]
Replicate from this resource the same way you would replicate from any of the resources using the Greatest ModificationTimestamp from the records you've received so far when querying for the latest changes. 
Please do not pull from this resource more frequently than once a day as this resource will not likely change more than once a day. Pulling this resource with the same frequency as the rest of the resources may result in interruption of service for inefficient usage practices.
If you receive an update to MlgCanView: false on any of your lookup records, you should remove it from the list of possible values for that LookupName for the OriginatingSystemName on the record.
Searchable Fields
The following fields will be searchable for the Lookup resource:
Searchable Lookup Field
Description
​OriginatingSystemName​
This field is a required search field on every request in version 2.0 of the API. This field is the MLS Grid name for the Originating System.
ModificationTimestamp
The timestamp that the record was last modified by the MLS Grid.
LookupName
The name of the Lookup you want to get the records for.
​MlgCanView​
Whether or not the record is still being used by the OriginatingSystem.
LookupKey
The mls prefixed key - primary identifier of the lookup.
Example Lookup Record
The LookupKey is the primary identifier for this resource. Each record indicates that a lookup exists and is being used or not used by a particular mls depending on the value of the MlgCanView flag. The ModificationTimestamp will update whenever the Lookup record has changed.
{
    "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb678f24b9e68b94c1734e')",
    "LookupKey": "ACT61bb678f24b9e68b94c1734e",
    "LookupName": "AreaUnits",
    "LookupValue": "Square Meters",
    "ModificationTimestamp": "2021-12-16T16:21:35.529Z",
    "OriginatingSystemName": "actris",
    "StandardLookupValue": "Square Meters",
    "MlgCanView": true
}
Metadata Type on Enumerated Fields
Fields that have been enumerated used to have the enumerations included as part of the metadata returned by the API service.  After this change, all enumerations will be returned using the new Lookup resource. The following is an example of both a single and multiple value field before and after the change:
OLD Metadata:
<Property Name="BodyType" Type="Collection(Enums.BodyType)" MaxLength="1024"/>
...
<Property Name="StandardStatus" Type="Enums.StandardStatus" MaxLength="25"/>
...
<EnumType Name="BodyType" UnderlyingType="Edm.Int64">
    <Member Name="DoubleWide" Value="1">
        <Annotation Term="RESO.OData.Metadata.StandardName" String="Double Wide"/>
    </Member>
    <Member Name="SingleWide" Value="2">
        <Annotation Term="RESO.OData.Metadata.StandardName" String="Single Wide"/>
    </Member>
    <Member Name="TripleWide" Value="3">
        <Annotation Term="RESO.OData.Metadata.StandardName" String="Triple Wide"/>
    </Member>
</EnumType>
...
<EnumType Name="StandardStatus" UnderlyingType="Edm.Int64">
    <Member Name="Active" Value="1"/>
    <Member Name="ActiveUnderContract" Value="2">
        <Annotation Term="RESO.OData.Metadata.StandardName" String="Active Under Contract"/>
    </Member>
    <Member Name="Canceled" Value="3"/>
    <Member Name="Closed" Value="4"/>
    <Member Name="ComingSoon" Value="5">
        <Annotation Term="RESO.OData.Metadata.StandardName" String="Coming Soon"/>
    </Member>
    <Member Name="Delete" Value="6"/>
    <Member Name="Expired" Value="7"/>
    <Member Name="Hold" Value="8"/>
    <Member Name="Incomplete" Value="9"/>
    <Member Name="Pending" Value="10"/>
    <Member Name="Withdrawn" Value="11"/>
</EnumType>
NEW Metadata: 
<Property Name="BodyType" Type="Collection(Edm.String)">
    <Annotation Term="MLS.OData.Metadata.LookupName" String="BodyType"/>
</Property>
...
<Property Name="StandardStatus" Type="Edm.String">
    <Annotation Term="MLS.OData.Metadata.LookupName" String="StandardStatus"/>
</Property>
Enumerations in Lookup Resource
In order to get the enumerations after this release you will have to query for them in the Lookup resource. For most normal usage, you should receive them by performing normal replication and will then retrieve them from your local data store.  
However, if you ever have need to query for a Lookup directly for troubleshooting purposes, here is an example of the same two lookups but queried from the Lookup resource individually.
BodyType
https://api-demo.mlsgrid.com/v2/Lookup?$filter=LookupName eq 'BodyType' and OriginatingSystemName eq 'mfrmls'
​
{
    "@odata.context": "https://api-demo.mlsgrid.com/v2/$metadata#Lookup",
    "value": [
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb678f24b9e68b94c1768e')",
            "LookupKey": "MFR61bb678f24b9e68b94c1768e",
            "LookupName": "BodyType",
            "LookupValue": "Double Wide",
            "ModificationTimestamp": "2021-12-16T16:21:35.843Z",
            "OriginatingSystemName": "mfrmls",
            "StandardLookupValue": "Double Wide",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb679024b9e68b94c178dd')",
            "LookupKey": "MFR61bb679024b9e68b94c178dd",
            "LookupName": "BodyType",
            "LookupValue": "Single Wide",
            "ModificationTimestamp": "2021-12-16T16:21:36.083Z",
            "OriginatingSystemName": "mfrmls",
            "StandardLookupValue": "Single Wide",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('MFR61bb679024b9e68b94c179c3')",
            "LookupKey": "MFR61bb679024b9e68b94c179c3",
            "LookupName": "BodyType",
            "LookupValue": "Triple Wide",
            "ModificationTimestamp": "2021-12-16T16:21:36.163Z",
            "OriginatingSystemName": "mfrmls",
            "StandardLookupValue": "Triple Wide",
            "MlgCanView": true
        }
    ]
} 
StandardStatus
https://api-demo.mlsgrid.com/v2/Lookup?$filter=LookupName eq 'StandardStatus' and OriginatingSystemName eq 'actris'
​
{
    "@odata.context": "https://api-demo.mlsgrid.com/v2/$metadata#Lookup",
    "value": [
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679024b9e68b94c17bf8')",
            "LookupKey": "ACT61bb679024b9e68b94c17bf8",
            "LookupName": "StandardStatus",
            "LookupValue": "Canceled",
            "ModificationTimestamp": "2021-12-16T16:21:36.393Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Canceled",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c180c1')",
            "LookupKey": "ACT61bb679124b9e68b94c180c1",
            "LookupName": "StandardStatus",
            "LookupValue": "Expired",
            "ModificationTimestamp": "2021-12-16T16:21:37.056Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Expired",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c181b8')",
            "LookupKey": "ACT61bb679124b9e68b94c181b8",
            "LookupName": "StandardStatus",
            "LookupValue": "Delete",
            "ModificationTimestamp": "2021-12-16T16:21:37.135Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Delete",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c181bf')",
            "LookupKey": "ACT61bb679124b9e68b94c181bf",
            "LookupName": "StandardStatus",
            "LookupValue": "Withdrawn",
            "ModificationTimestamp": "2021-12-16T16:21:37.135Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Withdrawn",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c18331')",
            "LookupKey": "ACT61bb679124b9e68b94c18331",
            "LookupName": "StandardStatus",
            "LookupValue": "Pending",
            "ModificationTimestamp": "2021-12-16T16:21:37.286Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Pending",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c1869e')",
            "LookupKey": "ACT61bb679124b9e68b94c1869e",
            "LookupName": "StandardStatus",
            "LookupValue": "Incomplete",
            "ModificationTimestamp": "2021-12-16T16:21:37.588Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Incomplete",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c187ef')",
            "LookupKey": "ACT61bb679124b9e68b94c187ef",
            "LookupName": "StandardStatus",
            "LookupValue": "Active",
            "ModificationTimestamp": "2021-12-16T16:21:37.738Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Active",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679124b9e68b94c18a63')",
            "LookupKey": "ACT61bb679124b9e68b94c18a63",
            "LookupName": "StandardStatus",
            "LookupValue": "Coming Soon",
            "ModificationTimestamp": "2021-12-16T16:21:37.965Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Coming Soon",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679224b9e68b94c18c1d')",
            "LookupKey": "ACT61bb679224b9e68b94c18c1d",
            "LookupName": "StandardStatus",
            "LookupValue": "Active Under Contract",
            "ModificationTimestamp": "2021-12-16T16:21:38.122Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Active Under Contract",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679924b9e68b94c1c8c1')",
            "LookupKey": "ACT61bb679924b9e68b94c1c8c1",
            "LookupName": "StandardStatus",
            "LookupValue": "Hold",
            "ModificationTimestamp": "2021-12-16T16:21:45.259Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Hold",
            "MlgCanView": true
        },
        {
            "@odata.id": "https://api-demo.mlsgrid.com/v2/Lookup('ACT61bb679924b9e68b94c1ca2d')",
            "LookupKey": "ACT61bb679924b9e68b94c1ca2d",
            "LookupName": "StandardStatus",
            "LookupValue": "Closed",
            "ModificationTimestamp": "2021-12-16T16:21:45.412Z",
            "OriginatingSystemName": "actris",
            "StandardLookupValue": "Closed",
            "MlgCanView": true
        }
    ]
}  
​
Releases - Previous
Upcoming Northstar Field Name Changes
Last modified 4mo ago
Copy link
Outline
Summary of Changes
Testing Before The Release
StringList to Array of Strings
Fields Changing To Arrays
Rooms and UnitTypes
Search By Value
New Lookups Resource
Metadata Type on Enumerated Fields
Enumerations in Lookup Resource