Fix nullExamples

[jgarciadelanoceda]

Fixes #3801.
As previously the null was being always serialized and also keep compatibility with not nullable references

As the integer/double could be always have the nullableReference because the objects where int?,double? for old versions seems fine.
I also tought about the object case, that for projects that do not have the nullable references enabled seems OK to me to have that case and also for the case of strings.. I do not really know if I should also place an specific case for arrays

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.92%. Comparing base (8ad6682) to head (357931c).
⚠️ Report is 29 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3803      +/-   ##
==========================================
- Coverage   94.93%   94.92%   -0.01%     
==========================================
  Files         111      111              
  Lines        3886     3885       -1     
  Branches      784      783       -1     
==========================================
- Hits         3689     3688       -1     
  Misses        197      197              

Flag	Coverage Δ
Linux	94.92% <100.00%> (-0.01%)	⬇️
Windows	94.92% <100.00%> (-0.01%)	⬇️
macOS	94.92% <100.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jgarciadelanoceda]

@martincostello could you review this?, I think that there is an extra property that is the format that is right now no neccesary but I did at the first implementation needed(I could remove it by the wat)

[martincostello]

could you review this?

I see all issues, PRs and comments in this repo - I get to stuff when it fits into my day and my TODO/priority list 😃

[martincostello]

FYI I'm going to be away next week, so even if this PR is approved/merged today, any new version won't ship until after I'm back as this is already the third attempt at resolving the underlying issue and I don't want a fourth attempt looming while I'm away 😄

[martincostello]

Could we add an integration test for this too?

[martincostello]

Once there's some user feedback that this looks right (just to avoid too many releases trying to fix this bug) then can look at merging.

Seems reasonable to me.

[pinkfloydx33]

@martincostello

I think it's reasonable. If a user puts null as the example:

• they likely did it on purpose
• presumably didn't mean the string "null"
  • If they did, there's (hopefully) billions of other words they can put there instead

(Anecdotally I once had a boss whose last name was "Null", so it's not totally unheard of outside of programming contexts.... but I'd personally avoid using common programming language terms in the example texts)

The only downside is that it does allow you to put null on a clearly non-nullable schema. That could also creep in when changing something to non-nullable later as its easy to accidently miss the example. Both of these would leave you with a slightly incorrect specification... But perhaps those are such just giant edge cases that it doesn't matter and/or are not worth the complexity against guarding.

I'd be A-OK if it was merged in this state.

---

That said, I still don't quite understand why checking for .HasFlag(JsonSchemaType.Null) as a guard to prevent null for non-nullable values presented any issues.

IOW why doesn't the following address all cases?

- if (string.Equals(exampleString, "null"))
+ if (string.Equals(exampleString, "null") && type is { } value && value.HasFlag(JsonSchemaType.Null))

Someone mentioned NRT and various options during schema-generation that you'd have to account for. But wouldn't all of those have been handled properly during GenerateSchemaForType /GenerateSchemaForMember, leaving the schema with the appropriate type/null-flag based on project configuration / compiler options / etc. before being processed by the XmlComment-related filters?

Or am I overlooking something about that? I'm genuinely curious at this point.

But like I said above, I'd be fine if the PR was merged as-is given the edge-case nature of what we're discussing.

[martincostello]

It's mainly that anecdotally IIRC we get users who don't use NRTs, but then we get users either side of the fence who complain that the nullability is wrong ("it's not optional so it shouldn't be nullable", "strings are technically reference types so it should be nullable", ...).

If we can, I'd rather avoid that can of worms by just making it "null means null".