fix(schema): apply additive JSON Schema semantics to $ref sibling getters

[aqeelat]

Summary

Following the discussion in #2919 with @handrews and @baywet, this PR is now documentation-only.

Changes

Adds XML documentation to OpenApiSchemaReference clarifying that convenience getters return authored sibling keyword values from Reference before falling back to resolved Target values. These getters are object-model conveniences and do not represent JSON Schema evaluation semantics.

Rationale

The reference-first getter behavior (Reference.X ?? Target?.X) was an explicit design decision (#2903). Per #2919:

• Assertion keywords alongside $ref are additive in JSON Schema evaluation, not overrides
• The library does not perform validation — splitting getter behavior per keyword type creates setter/getter asymmetry and keyword-specific edge cases
• The safest direction is to keep consistent reference-first getters and document the contract explicitly

Consumers that need precise JSON Schema semantics should inspect both Reference and Target, or use a JSON Schema validator.

Fixes #2919

[handrews]

I'm not entirely sure the additionalProperties and unevaluatedProperties behaviors are correct. Both of those have behavior that is highly dependent on their exact schema location. In particular, additionalProperties can only be evaluated in terms of its immediate adjacent keywords in the same schema object. And for unevaluatedProperties, the behavior of placing in in the $ref source vs target is very different. Based purely on the comments (I haven't had time to try to understand the code- this is not an ecosystem with which I am familiar) this also seems to treat both as booleans, when either could also be a non-trivial schema of some sort.

[baywet]

Thank you for making the changes!

[Copilot]

Pull request overview

Documentation-only update to clarify OpenApiSchemaReference’s contract when accessing JSON Schema keywords alongside $ref, aligning with the discussion in #2919 and preserving the existing “reference-first, then target” convenience getter behavior.

Changes:

• Add XML documentation to OpenApiSchemaReference explaining that convenience getters return sibling keyword values authored on Reference before falling back to resolved Target values.
• Clarify that these getters are object-model conveniences and not JSON Schema evaluation semantics.