Clarify schema constraint compatibility guidance

[hdamker]

What type of PR is this?

• documentation

What this PR does / why we need it:

Adds concise API Design Guide guidance for classifying the compatibility impact when adding or tightening schema constraints on an already published API.

The new text keeps the existing schema-constraint requirements intact, while clarifying that the compatibility impact is assessed against the previous public API contract.

Which issue(s) this PR fixes:

Fixes #657

Does this PR introduce a breaking change?

• Yes
• No

Special notes for reviewers:

The added guidance is intentionally compact and example-light. Concrete examples belong in the linked issue discussion; the Design Guide text states the general rule.

Changelog input

 release-note
Clarified compatibility guidance for adding or tightening schema constraints on already published APIs.

Additional documentation

This section can be blank.

docs

[PedroDiez]

LGTM

[PedroDiez]

Suggested change

When adding or tightening schema constraints such as `maxLength`, `maxItems`, `minimum`, or `maximum` on an already published API, the compatibility impact MUST be assessed against the previous public API contract. The change can be treated as backward-compatible when it only makes an already intended or domain-limited constraint machine-readable and does not restrict well-behaving clients; if it newly rejects previously valid requests, narrows responses clients could validly receive, or requires new client behavior such as pagination, it is a breaking change. The API change should clearly communicate what changed, why it changed, and why well-behaving clients are not restricted when the change is classified as a clarification.

When adding or tightening schema constraints such as `maxLength`, `maxItems`, `minimum`, or `maximum` on an already published API, the compatibility impact MUST be assessed against the previous public API contract. The change can be treated as backward-compatible when it only makes an already intended or domain-limited constraint machine-readable and does not restrict well-behaving clients; if it newly rejects previously valid requests, narrows the responses that clients could validly receive, or requires new client behavior such as pagination, it is a breaking change. The API change should clearly communicate what changed, why it changed, and why well-behaving clients are not restricted when the change is classified as a clarification.

[PedroDiez]

minor editorial suggestion

[eric-murray]

The API change should clearly communicate ...

Do you mean the API release notes? Is it planned to update the release notes template to include a section for such changes and their assessment?

The current release notes typically only include the title of each relevant PR, which does not always capture the full implications of what has changed. Whilst that might be documented in the PR itself, I suspect few API consumers go looking at the details of each PR.

I understand the requirement to communicate such changes, but feel the current wording allows different ways for that to be achieved, some of which will be more effective than others. I think explicitly mandating that be documented in the release notes is the way to go.