Keep null, missing, empty, and default states distinct in JSON exports

Treat an object member as two signals: whether the key is present and, if present, which JSON value it carries. The distinction is structural before it is semantic. A consumer can use omission to mean “not supplied,” null to mean “explicitly no value,” an empty string to mean “a supplied string with no characters,” and an empty array to mean “a supplied collection with no members.” The field owner must define the meaning that fits the contract.

The source dates shown in this guide identify documentation checks on 22 October 2026, not original publication dates. This guide intentionally stays at the serialization boundary. It does not decide whether a domain label such as “unknown” or “not applicable” is consistent across a dataset; use the owner’s field dictionary for that separate question.

A useful contract names allowed presence, allowed JSON types, empty-value behavior, default ownership, and the action for an invalid combination. Do not put a default in a schema and assume that every validator or importer materializes it. If a consumer wants a materialized value, record the transformation as an explicit step and preserve whether it came from the source or the defaulting process.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": ["string", "null"] },
    "items": { "type": "array" }
  },
  "required": ["status"],
  "additionalProperties": false
}

This synthetic schema requires the status member but permits either a string or null. It does not make an omitted member equal to null, and it does not decide whether an empty string means anything useful. JSON Schema validation supplies structural evidence; the field owner still supplies the semantic contract JSON Schema, 22 Oct 2026 (opens in a new tab).

Build fixtures that differ by one state at a time. Run them through the producer serializer, transport, parser, validation, and any database or spreadsheet adapter. Compare key presence as well as the decoded value. A serializer that omits nulls may appear harmless until a consumer uses omission to mean “leave the previous value unchanged.”

Evidence to record

• The exact input object and whether each member was present.
• The serialized bytes or approved redacted representation.
• The validator result and schema version.
• Any defaulting transformation, including who applied it.
• The consumer action for every accepted and rejected state.

The JSON Schema annotations guide explicitly treats default as metadata about an intended value, not a validation-time fill operation. A passing validation result therefore does not prove that the consumer will see a populated field JSON Schema, 22 Oct 2026 (opens in a new tab).

An export can be correct as a snapshot and still be wrong as an update document. If a pipeline uses JSON Merge Patch, an explicit null is not merely a nullable value: it requests removal of the target member. RFC 7396 also cautions that the format is a poor fit for objects that need explicit null values. Record whether the artifact is a snapshot, a replacement, or a patch before interpreting null.

RFC 7396 says null in a merge patch removes the named member and notes the format is not suitable when explicit null values must be represented. Keep patch semantics out of a snapshot schema description, or consumers will apply the wrong state transition Internet Engineering Task Force, 22 Oct 2026 (opens in a new tab).

If the owner can describe the collection and its handling authority, the next step may be the appraisal route. That route is a request for review, not automatic acceptance, a quote, a buyer match, a legal opinion, or a license. A synthetic object matrix is enough to expose state collapse; do not send private records merely to test whether null survived serialization.

Takeaways

• Treat key presence and value as separate contract dimensions.
• Distinguish null, empty string, empty collection, empty object, and omission.
• Treat default as an explicit transformation owned by a named side.
• Test snapshot and patch documents under their actual semantics.
• Keep wire-state findings separate from domain missingness labels.