Validation rules, add/edit, and SET

[bryanburgers]

While working on a few Add/Edit projects, I've been familiarizing myself with the existing validation rules spec. My goal is to use the validation rules spec to provide a good user experience for agents — especially, give agents immediate feedback on validation and provide lookup winnowing.

As part of this, I keep coming across the same question and I would love to hear some MLS and MLS Provider thoughts and context on the SET part of the spec.

For reference, here's some places to find validation rules information:

• RESO Validation Expressions on GitHub
• Original Proposal (PDF)
• Notes from the May 2023 transport meeting
• Data Dictionary 1.7 Rules Resource
• 2018 Review of Validation in RETS 1.8
• 2018 Rules Discussion

In these resources, the importance of data mutation (especially via SET) is implied.

Key questions:

• Do MLSes and MLS providers intend to communicate rules with the SET action?
• If so, what do you expect clients to do with SET rules?

If the Rules Resource is viewed through the lens of a communication mechanism between the server (MLS provider, on behalf of the MLS) and the client (and Add/Edit application), the Rules Resource is communicating what the server intends to do with the information provided. In that context, I understand what most of the actions are communicating:

• An ACCEPT rule is communicating to the client that if the client sends a value such that the expression doesn't evaluate to true, the server will not apply the change.
• A REJECT rule is communicating largely the same: if the client sends a value such that the expression does evaluate to true, the server will not apply the change.
• A SET_REQUIRED rule is communicating that if the client does not send a value for the field, the server will not apply the change.
• The SET_PICKLIST and RESTRICT_PICKLIST are a little less to the point, but I think they can reasonably be interpreted as communicating that if the client sends a value that is not included in the new calculated list of lookup items, the server will not apply the change.

On the other hand, the SET rule is ambiguous about what the server is communicating. If a server includes a SET rule, what exactly is the server trying to communicate to the client? I can see several different options of what is trying to be communicated, and I'm curious if there's consensus on this?

Does a SET rule communicate from the server to the client:

1. Please don't send any value for this field, the server will fill in a value. This rule is informing you what value the server will fill in.
2. Don't send any value for this field; it is a calculated field. If you do send anything, the server will not apply the change.
3. If the value the client sends for this field does not exactly match the result of the expression, the server will not apply the change.
4. Please calculate this value on the client and send us the result. The server will accept whatever you send, but please send the right value. The server has great trust in you, client.

As an example, let's assume a client receives a SET rule on the field OnMarketDate that looks like:

IIF(MlsStatus != "Draft" .AND. LAST MlsStatus = "Draft", .TODAY., OnMarketDate)

The intention of this SET rule makes sense: when a listing transitions from a status of Draft to any other status, the OnMarketDate should be set to the current date. In all other circumstances, don't change the OnMarketDate.

What's not clear is what a client that sees this rule should send

1. Nothing. The server will apply the rule. If you send anything, the server will ignore it and handle the OnMarketDate itself anyway.
2. Nothing. The server will apply the rule. If you send anything, the server will not apply this change.
3. "OnMarketDate": "2023-05-09". If it doesn't, the server will not apply this change.
4. "OnMarketDate": "2023-05-09". The server won't actually verify this though. (Hopefully the client and the server are in the same timezone and have synchronized clocks.)

As an MLSes or an MLS Provider, in the context of Add/Edit, what are you communicating when you send a SET rule in the Rules Resource?

[darnjo]

Thanks for posting.

Here are some examples of real world rules that require set behavior (mutation):

1. If Status changes to closed, Close Date is required

This is an example of SET_REQUIRED.

2. Clear Proposed Date when Status changes from Pending to Active

This would be a SET operation on the Proposed Date (clear it).

3. If ListPrice will change, set OriginalListPrice to current Price before making the change

This is similar to (2).

4. If Seller Concessions is True, Display and Require Concessions Amount

This uses SET_DISPLAY and SET_REQUIRED.

[bryanburgers]

Right. So let's take Example 2. In an add/edit environment, the client must now craft an HTTP PATCH request to update the record on the server.

Does that patch request body contain

{
  "MlsStatus": "Active",
  "ProposedDate": null
}

telling the server to clear proposed date?

Does the patch request body contain

{
  "MlsStatus": "Active"
}

telling the server that the status changed, and the server will clear the proposed date?

If the patch request body contains

{
  "MlsStatus": "Active",
  "ProposedDate": "1985-04-21"
}

does the server blindly accept this patch and use the proposed date given? Accept this patch but clear the proposed date? Reject this patch?

I understand how the rule makes sense in the system as a whole; what I need to know as only one small part of the system is what is the client's responsibility in an add/edit system with respect to SET rules.

[darnjo]

The server would never accept the input without performing validation as well.

Ideally the server and client would also run the same ruleset for parity. Not a hard requirement but makes things easier.

The idea is that the server provides a list of instructions that lets the client make correct decisions for how to respond as the user is making changes to the state of the record. Some of these rules may be conditional, as shown above, and may trigger other conditional requirements or mutations as well.

So, for (2) the client would know to clear proposed date in the current record if the status changes from Pending to Active, and if the server received an update for that record with its status changed from Pending to Active, the request would fail if proposed date was still present in the payload. The rules act as somewhat of a state machine in this case.