Data Dictionary Forward Compatibility and Certification

[robtlar]

This is a request for information from the Certification Workgroup.

It has been clarified that not all changes to the Data Dictionary are forward-compatible. Breaking changes, such as changing an existing field’s data type, are not forward-compatible. However, changes such as an enumeration addition may be forward-compatible.

Examples of changes made by the data dictionary workgroup:

• Field and Enumeration Additions
• Field and Enumeration Deprecations
• Field and Enumeration value changes
• Field Data type changes
• Field Length Changes
• Definition Changes
• Synonym Changes
• Changes to Structure (e.g., collections vs shapes)
• Shape Additions

Please guide the Data Dictionary workgroup on what types of changes will pass as forward compatible and which should not be implemented before testing for the given version.

The Data Dictionary Workgroup discussion can be found at:
https://reso.atlassian.net/wiki/spaces/DDGDF/pages/9725968461/Forward+Compatibility
Please post any information you have to that thread.

Thank you

[darnjo]

See https://transport.reso.org/versioning

…

On Sat, Oct 5, 2024, 08:26 robtlar ***@***.***> wrote: This is a request for information from the Certification Workgroup. It has been clarified that not all changes to the Data Dictionary are forward-compatible. Breaking changes, such as changing an existing field’s data type, are not forward-compatible. However, changes such as an enumeration addition may be forward-compatible. Examples of changes made by the data dictionary workgroup: - Field and Enumeration Additions - Field and Enumeration Deprecations - Field and Enumeration value changes - Field Data type changes - Field Length Changes - Definition Changes - Synonym Changes - Changes to Structure (e.g., collections vs shapes) - Shape Additions Please guide the Data Dictionary workgroup on what types of changes will pass as forward compatible and which should not be implemented before testing for the given version. The Data Dictionary Workgroup discussion can be found at: https://reso.atlassian.net/wiki/spaces/DDGDF/pages/9725968461/Forward+Compatibility Please post any information you have to that thread. Thank you — Reply to this email directly, view it on GitHub <#149>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAECWPTVDSDRIZIVLTA5P4TZ2AAMDAVCNFSM6AAAAABPNN4BGKVHI2DSMVQWIX3LMV43ERDJONRXK43TNFXW4OZXGI3TSOJSGY> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[robtlar]

Thank you. Ironically, the versioning page from Transport doesn't have any versioning information. How are updates to this page tracked?

[darnjo]

Changes and versions to all pages in this repository are automatically handled by GitHub. We don't use SemVer in these cases, just on specifications.

…

On Sat, Oct 5, 2024, 08:42 robtlar ***@***.***> wrote: Thank you. Ironically, the versioning page from Transport doesn't have any versioning information. How are updates to this page tracked? — Reply to this email directly, view it on GitHub <#149 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAECWPW3V65ECG6RR5M65I3Z2ACHHAVCNFSM6AAAAABPNN4BGKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTAOBVGMZDINA> . You are receiving this because you commented.Message ID: ***@***.*** com>

[robtlar]

Is there a way to follow a page or get notifications about changes to the page?

[robtlar]

Using the provided versioning information, here are my interpretations. Please verify.

MAJOR changes are not forward-compatible
MINOR changes and patches are forward-compatible

Field and Enumeration Additions - MINOR (forward-compatible)
Field and Enumeration Deprecations - MINOR (forward-compatible)
Field and Enumeration value changes - MINOR (forward-compatible, as long as the old value is not disallowed)
Field Data type changes - MAJOR (not forward compatible)
Field Length Changes - PATCH (forward-compatible)
Definition Changes - PATCH (forward-compatible)
Synonym Changes - Additions may be MAJOR and can affect non-standard names.

We may need more details or clarification on these.
Changes to Structure (e.g., collections vs shapes). For this one I was thinking about our recent change to "shape".
Shape Additions - for this, examples are the recent addition of the waterfront collection. I'm assuming it would depend on the details within the new shape. e.g. synonyms, etc.
Please advise.

Second question - when we have changes in the DD WG and it's not clear if the change is MAJOR, MINOR, or Patch, should we have staff do the research or send it to the Certification WG?

Thanks

[darnjo]

You can watch the entire repo and specific issues or discussions but not a single page, unfortunately. You could watch the repo and set up an alert for "versioning" in your email client. Informational pages don't change often. We can make sure to tag you when making changes to this page though. We tend not to use the term "forward compatible" in Transport or Certification since it can be a bit misleading and dependent on the context and how a given system handles those changes. Not all systems are set up to handle additions and deprecations, so it's more of a system design concept than something we can guarantee at the API level. Instead we think in terms of "breaking" or "incompatible" changes to the API, meaning we know changes will break clients. This is in line with how SemVer approaches changes as well. Collections are not a data type unto themselves. They have a type associated with them - a collection of Media Resource items is different from a collection of FeedRule shapes. A breaking (major) change in this case would be a) either changing a field so that it's not a collection anymore, or b) changing its underlying type. Say the Media Resource was no longer used and became a Media Shape instead. Beyond that, adding or deprecating fields or enumerations within those resources or shapes would fall under a minor change unless the deprecation is forced. But, these changes could still break systems or clients if they're not equipped to deal with them. So, it's hard to say they're "forward compatible" without further information. If there are questions about a particular change being incompatible or not, you can make a post to this discussion forum, or email ***@***.*** As a side note, given the disclaimers above about forward compatibility, the classifications shown in the previous comment look accurate. I would always qualify "forward compatible" with "if your system is equipped to handle it." And even then there may be some edge cases where further qualification is needed.

…

On Sat, Oct 5, 2024, 09:13 robtlar ***@***.***> wrote: Using the provided versioning information, here are my interpretations. Please verify. MAJOR changes are not forward-compatible MINOR changes and patches are forward-compatible Field and Enumeration Additions - MINOR (forward-compatible) Field and Enumeration Deprecations - MINOR (forward-compatible) Field and Enumeration value changes - MINOR (forward-compatible, as long as the old value is not disallowed) Field Data type changes - MAJOR (not forward compatible) Field Length Changes - PATCH (forward-compatible) Definition Changes - PATCH (forward-compatible) Synonym Changes - Additions may be MAJOR and can affect non-standard names. We may need more details or clarification on these. Changes to Structure (e.g., collections vs shapes). For this one I was thinking about our recent change to "shape". Shape Additions - for this, examples are the recent addition of the waterfront collection. I'm assuming it would depend on the details within the new shape. e.g. synonyms, etc. Please advise. Second question - when we have changes in the DD WG and it's not clear if the change is MAJOR, MINOR, or Patch, should we have staff do the research or send it to the Certification WG? Thanks — Reply to this email directly, view it on GitHub <#149 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAECWPRZTILR5ONHLOY56V3Z2AFZ7AVCNFSM6AAAAABPNN4BGKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTAOBVGM2DEMQ> . You are receiving this because you commented.Message ID: ***@***.*** com>