Skip to content

Latest commit

 

History

History
105 lines (72 loc) · 6.71 KB

versioning.md

File metadata and controls

105 lines (72 loc) · 6.71 KB
Raw

RESO Versioning

RESO uses Semantic Versioning (SemVer) in its specifications, which outlines the following:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when making incompatible API changes
  • MINOR version when adding functionality in a backward compatible manner
  • PATCH version when making backward compatible bug fixes

For Data Dictionary specifications, only major and minor versions are used formally (e.g. 1.7 or 2.0). RESO tracks patch-level changes for each revision of the Data Dictionary internally.

Transport includes the patch level in its specifications (e.g. Web API Core 2.0.0) but only uses major and minor versions in practice.

API Changes and RESO Standards

Whether something is a "breaking change" depends on the lens through which it's viewed.

Removing something from a RESO specification, either in the Data Dictionary or Transport workgroups, means RESO won't test for it anymore. However, providers don't have to remove that item from their APIs unless expressly forbidden, such as disallowed synonyms in the Data Dictionary.

Similarly, adding tests where they didn't exist before could "break" an API since they might require changes to the current implementation to meet the standard.

This document focuses primarily on how RESO standards and certification use versioning rather than how systems version their APIs, though there is some overlap.

Major Changes

Major changes are also known as "breaking changes" and MUST NOT be implemented until the version of the specification they apply to.

Data Dictionary

The following changes are incompatible with current versions of the specification:

  • A standard field has a type change.
  • A disallowed synonym is added for a resource, field, or lookup (enumeration).
  • An enumerated field is closed, meaning items outside of that enumeration will fail during testing.

Examples of type changes are things like a field that's currently a string becoming a number or enumeration. Unlike minor changes, future type changes cannot be adopted until that version of the Data Dictionary without breaking clients.

Disallowed synonyms are considered MAJOR because RESO is forcing providers to remove items from their APIs that may currently be in use and will therefore break clients. This is different from just deprecating a data element from the standard, since providers can still use it in those cases.

Closing an enumeration is a forced deprecation on any of the items not currently defined, as providers must remove them from their system and map to the standard values.

If there's at least one major change in a given Data Dictionary version, the specification will increment its MAJOR version.

Transport

Major changes in Transport consist of disallowing previously standard behavior or making significant changes to existing functionality.

For example, RESO Common Format currently requires a @reso.context variable. If the Transport Workgroup were to change this to something else and force deprecation, or change the type of this value from string to a nested object, it would constitute a MAJOR version.

Another example: RESO is planning to deprecate OData multi-select enumerations in the future. If any are found on a RESO Web API server during testing at that point, certification will fail.

Similar to the Data Dictionary, functionality may be added to or removed from Transport specifications without causing breaking changes since providers can choose to keep their APIs the same. However, any forced deprecations or changes to data types or potential type mappings count as MAJOR.

Minor Changes

Minor changes preserve compatibility with current Data Dictionary and Transport specifications. These are usually additions or deprecations.

Data Dictionary

  • Data elements such as resources, fields, or lookups (enumerations) are added to or removed from the specification.
  • Existing data elements are renamed, as long as the old ones aren't disallowed.
  • There are changes to classifications of PropertyType and PropertySubType groupings.

When items are added or removed from the specification, providers don't have to make changes on their current systems to reflect those changes.

In some cases, it's possible that adding something to a future version of the Data Dictionary will cause a current local data element to fail in certification. However, if the provider has both the standard and local value, they will pass testing in those cases. This is also true when something is renamed in the Data Dictionary.

RESO does not validate related PropertyType and PropertySubType usage currently, but plans to do so in the future with warnings beginning in version 2.1. These classifications are used enough in practice that they should be made in a future version rather than as a patch to the current one.

Transport

Minor changes in transport usually mean adding something to the API specifications, such as a new kind of query or server-driven paging. Clients don't have to support those queries or new kinds of paging unless we force deprecation of the prior standard, which is uncommon. With RESO Common Format, the versioning is handled by Data Dictionary versioning rules outside of the @reso.context variable.

Patches

Patches are backwards compatible bug fixes. This usually means corrections to terms or wording in a specification, and includes changes to certain columns in the Data Dictionary reference sheets.

Data Dictionary

Patches include changes to any of the following columns in the Data Dictionary specification:

  • BEDES
  • Definition
  • DisplayName
  • FrenchCanadianDisplayName
  • FrenchCanadianLookupValue
  • Groups
  • LegacyLookupId
  • LegacyLookupName
  • LegacyRecordId
  • LookupId
  • LookupName
  • LookupNameId
  • Payloads
  • RecordId
  • SpanishDisplayName
  • SpanishLookupValue
  • SugMaxLength
  • SugMaxPrecision
  • WikiPageId
  • WikiPageTitle
  • WikiPageUrl

Suggested max precision and length are considered patches since they're suggestions and will not result in failure during certification. If the attributes used by the provider differ from the suggested values, they will receive an informational message.

At the API level, changing length, scale, or precision is a breaking change and providers should inform end users when doing so.

Transport

Patch-level changes in Transport are things like clarification of the specification, adding new examples or references, updating links, or fixing spelling and grammar.

Any changes to current testing rules are not patches and will be considered major or minor revisions.

Questions? Please contact RESO.