RESO Endorsements
Endorsements are modular specifications grouped by their transport procotol, for example, the RESO Web API. Specifications use semantic versioning.
Proposals MUST have two verified implementations from separate vendors before they can be adopted.
Please visit our discussion forum if you have any questions or would like to start a proposal. See issues for new specifications.
CHANGE PROPOSALS
| RCP | Name | Version | Status | Status Date |
|---|---|---|---|---|
| RCP-036 | Data Dictionary | 1.7 | RATIFIED | Jan 2021 |
| RCP-037 | Web API Core | 2.0 | RATIFIED | Jan 2021 |
| RCP-038 | Payloads (with IDX Payload) | 1.7 | RATIFIED | Aug 2021 |
| RCP-010 | Web API Add/Edit | 2.0.0 | DRAFT | Apr 2017 |
| RCP-019 | Web API Validation Expressions | 2.0.0 | DRAFT | Apr 2018 |
| RCP-032 | Lookup Resource | 1.7 | DRAFT | Dec 2021 |
| RCP-040 | Data Dictionary | 2.0 | DRAFT | Dec 2021 |
| RCP-039 | Web API Core | 2.1.0 | IN PROGRESS | Apr 2021 |
| RCP-041 | Payloads | 2.0 | IN PROGRESS | Apr 2021 |
RATIFIED
Ratified proposals have been adopted by the workgroups and RESO as an organization. Proposals that require certification testing must have adopted a specification, testing rules, and production-ready testing tools for ratification.
Data Dictionary 1.7
| RCP | RCP-036 |
|---|---|
| Authors | Joshua Darnell (RESO) |
| Status | RATIFIED |
| Date Ratified | January 2021 |
| Dependencies | Web API Core 2.0.0+ |
| Related Links | Specification DD Wiki 1.7 Data Dictionary Spreadsheet |
The Data Dictionary endorsement defines models for use in the RESO domain. These include Resources, Fields, Lookups, and Relationships between Resources.
Web API Core 2.0.0
| RCP | RCP-037 |
|---|---|
| Authors | Joshua Darnell (RESO) |
| Status | RATIFIED |
| Date Ratified | January 2021 |
| Protocol | HTTP |
| Dependencies | OData 4.0 or 4.01 TLS 1.2+ OAuth 2 (Auth Token or Client Credentials) |
| Related Links | Specification |
The Web API Core endorsement defines the primary functionality RESO Web API servers are expected to support in order to provide both replication and live query support.
Payloads 1.7
| RCP | RCP-038 |
|---|---|
| Authors | Joshua Darnell (RESO) |
| Status | RATIFIED |
| Date Ratified | August 2021 |
| Protocol | HTTP |
| Dependencies | Data Dictionary 1.7 Web API Core 2.0.0+ |
| Related Links | Specification |
Defines general payloads data validation and availability testing rules, as well as the IDX Payload Endorsement.
DRAFT
Draft proposals have been approved by the workgroups and organization and are awaiting implementations and community review.
Web API Add/Edit
| RCP | RCP-010 |
|---|---|
| Authors | Sergio Del Rio (T4Bi) Joshua Darnell (RESO) |
| Status | DRAFT |
| Date Approved | April 2017 (original) |
| Dependencies | Data Dictionary 1.7+ Web API 2.0.0+ |
| Related Links | Specification (Draft PR) DD Wiki 1.7 Data Dictionary Spreadsheet |
The Web API Add/Edit endorsement defines how to Create, Update, and Delete data in the RESO Web API.
Web API Validation Expressions
| RCP | RCP-019 |
|---|---|
| Authors | Joshua Darnell (RESO) Paul Stusiak (Falcon Technologies) |
| Status | DRAFT |
| Date Approved | April 2018 |
| Dependencies | Data Dictionary 1.7+ Web API 2.0.0+ Validation Expression grammar |
| Related Links | Specification (Draft PR) DD Wiki 1.7 Data Dictionary Spreadsheet |
Web API Validation Expressions allow for the transport of machine-executable business rules using the RETS 019 Validation Expression grammar.
Lookup Resource
| RCP | RCP-032 |
|---|---|
| Authors | Joshua Darnell (RESO) Ryan Yates (Rapattoni Corporation) Sergio Del Rio (T4Bi) Rob Larson (Larson Consulting) Paul Stusiak (Falcon Technologies) |
| Status | DRAFT |
| Status Date | December 2021 |
| Dependencies | Web API Core 2.0.0+ |
| Related Links | Specification (Draft PR) DD Wiki 1.7 Data Dictionary Spreadsheet |
The Lookup Resource provides a framework to advertise human-friendly display names and use them in payloads. This reduces the amount of interpretation data consumers need to do when using enumerations, and they can display what they get in the payload directly rather than inferring the values from annotations. It also better supports providers who have a large amount of lookup metadata, allowing it to be consumed and updated through incremental updates rather than having to update all metadata each time something changes.
Data Dictionary 2.0
| RCP | RCP-040 |
|---|---|
| Authors | Joshua Darnell (RESO) |
| Status | DRAFT |
| Dependencies | Web API Core 2.0.0+ |
| Related Links | Specification (Draft PR) DD Wiki 1.7 Data Dictionary Spreadsheet |
The Data Dictionary endorsement defines models for use in the RESO domain. These include Resources, Fields, Lookups, and Relationships between Resources.
New in version 2.0
- Added new resources, fields, and enumerations
- Additional validation of resources, fields, and enumerations using a number of heuristics (substring, edit distance, and data-driven matching)
- Data validation against server metadata - if items are found in the payload that are not advertised, providers will ont pass testing
- Updated Data Dictionary reference sheet structure
IN PROGRESS
Proposals that are in progress are ones that have been reviewed by the workgroups and are actively being worked on prior to draft status.
Web API Core 2.1.0
| RCP | RCP-039 |
|---|---|
| Authors | Joshua Darnell (RESO) |
| Status | IN PROGRESS |
| Date Started | April 2022 |
| Protocol | HTTP |
| Dependencies | OData 4.0 or 4.01 TLS 1.2+ OAuth 2 (Auth Token or Client Credentials) |
| Related Links | GitHub Issue |
The Web API Core 2.1.0 endorsement defines the primary functionality RESO Web API servers are expected to have in order to provide both replication and live query support.
New in version 2.1.0
- Support for OData
$expand - Server-Driven Paging (
@odata.nextLink) required for Certification - Support for the Lookup Resource, including string comparison tests for enumerations
Payloads 2.0
| RCP | RCP-041 |
|---|---|
| Authors | Joshua Darnell (RESO) |
| Status | IN PROGRESS |
| Date Started | April 2022 |
| Protocol | HTTP |
| Dependencies | Data Dictionary 1.7 Web API Core 2.0.0+ |
| Related Links | GitHub Issue |
Payloads 2.0 defines general data validation and availability testing rules, as well as the IDX Payload Endorsement.
New in version 2.0
- Support for OData
$expand - Sampling using server-driven paging
- Strict checking of what’s advertised in the metadata vs. what was found in the payload
Related Documents
The following documents may also be helpful:
New Change Proposals
RCP Template
If you would like to suggest a new change proposal, please use the RCP Template in this repository and fill in each section accordingly.
Submission Process
1. Proposal Phase
- Post on GitHub Discussions.
- Request that the topic be added to the appropriate Transport and/or Certification agendas. Ideally, there would be some activity in the GitHub discussion before and after the workgroup meeting.
- Once there’s consensus in the group to move a given item forward, an issue should be created and work on a specification can begin.
- A preliminary specification and set of testing rules should be produced that others could (unambiguously) build software to. An impact assessment should also be included, when applicable.
- After work on the specification is complete, it should be posted for community review at least two weeks before the Transport or Certification meeting it’s to be discussed in.
2. Draft Phase
- Once approved into draft status, a draft PR should be made.
- The proposal will stay in draft status until it has at least two implementations from two separate vendors, at which point there will be a workgroup discussion, including revisiting which existing specifications and versions to add it to, if applicable.
- The implementations should be verified against the proposed testing rules by RESO staff, even if on a development server.
3. Approval and Adoption Phase
- The PR will be taken out of draft status at this point, awaiting final approval.
- There may also be a motion to create Certification tools, and potentially new reports or metrics, at that time. If so, these items need to be added to RESO’s backlog.
- The Transport and Certification groups will decide which specification(s) it should be added to and which version(s) to target; those writing the proposals can make requests in this regard.
- Once the new specification is ready for ratification, related PRs will be merged into their corresponding specifications.
Please contact RESO Development if you have any questions.