v3.1.2: Provide guidance on null in XML.

[handrews]

Fixes:

• Formalize how to express null value in xml #3959

There really isn't a native null type in XML, as both elements and attributes that are empty have an empty string value.

We also need to leave the behavior implementation-defined for compatibility.

However, attaching the xsi:nil=true attribute to an empty element is the closest thing to a null element.

Attributes are harder, and the best I can come up with is letting null behave the same as an omitted attribute for the purpose of serialization. This means that for round-tripping, whether a missing attribute is parsed into a null property or as an omitted property depends on whether the schema allows null.

This attribute behavior is a bit weird, but I can't come up with anything else that has a hope of round-tripping propery, and we can't outright forbid null in a patch release. If PR #4592 is accepted, we could forbid type: [..., "null"] or type: "null" with xml: {nodeType: "attribute"} and leave the behavior with the deprecated xml: {attribute: true} unchanged.

So I guess the question here is whether the attribute guidance is more confusing than helpful. The fact that we got asked about it suggests that we ought to say something, though.

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[miqui]

@handrews > we could forbid type: [..., "null"] or type: "null" with xml: {nodeType: "attribute"} and leave the behavior with the deprecated xml: {attribute: true} unchanged.

This seems like reasonable constraint.

[ralfhandl]

+1, just a doubt on punctuation

[lornajane]

Thanks, this is a good addition

[lornajane]

@handrews Will you create the same change for 3.2? Can we link the PRs together when you do?

[handrews]

@lornajane removing JSON examples was just 3.2, although I would not object to removing them in 3.1.2 if folks want.

I was thinking of adding this to PR #4592 as otherwise it will be a mess of git conflicts. Alternatively, we could wait for #4592 to merge and then I'll port this (and other XML-related 3.1.2 changes). I was going to do one big 3.1.2->3.2 sync PR with individual commits (like I did last time around for the final sync PRs), but I can do this one separately if needed.