Implementation guidance: representing blank/empty values in JSON-LD

[mrgarth]

Cheat Sheet for Developers

JSON Representation	JSON-LD Interpretation	Best Use Case
Omitted Key	Property does not exist.	Preferred. The cleanest, standard way to represent missing data.
"property": null	Property does not exist.	Preferred replacement for missing data if the keys must remain in your JSON payload structure.
"property": ""	An actual string literal of length zero.	Genuinely empty text fields only. Never use for numbers, dates, or IRIs.
"property": []	An empty collection (0 nodes/values).	Multi-valued relations where an explicit "zero count" needs to be communicated.

Choosing omission or empty string - cardinality requirements

When validating against schema requirements (like SHACL or JSON Schema), the choice between omitting a key or providing an empty string ("") directly impacts cardinality constraints:

• Strict Cardinality (e.g., "Exactly 1"): If a property is required—such as hasLegalName for an Organization—omitting it (or setting it to null) means no data is generated for that field, resulting in a validation violation. However, providing an empty string ("") creates a valid literal node of zero length, which structurally passes validation.
• No Cardinality Constraints (Optional): If a property is optional—such as hasComment for an IndicatorReport—omitting the property entirely generates no graph data, which will not trigger a validation violation.

Passing "" can pass SHACL validation for fields like hasLegalName, but it should be read carefully. It means “we have a legal name, and it is the empty string”. It is not equivalent to “no legal name provided” (null/omit). Using "" to dodge cardinality violations is technically valid but can hide data-quality problems.

While passing an empty string ("") technically passes structural cardinality checks for required fields, it may still fail semantic validation downstream if a system importing the data requires a specific data format (like non-empty strings). The Common Impact Data Standard v3.2 doesn't require literal string values like hasLegalName or hasName be any minimum length.

Explanation

The W3C standard representation for empty/missing values is a null, or omission of the relevant property from the object or instance.

If a property cannot be omitted entirely from a JSON-LD impact data capsule (for example, due to database or payload template constraints), the official way to indicate a missing or absent value in JSON-LD is null.

The W3C JSON-LD 1.1 Specification states:

"A map entry in the body of a JSON-LD document whose value is null has the same meaning as if the map entry was not defined."

When a JSON-LD parser processes the payload, any keys paired with null are entirely stripped out, meaning they do not generate any triples or edges in the final graph. This rule applies identically to both datatype properties (literals) and object properties.

Why "" and [] aren't one-size-fits-all representations for blank/empty literals and/or IRIs

1. The Risk of Empty Strings ("") for Literals

In JSON-LD, an empty string "" is not parsed as a missing value; it is a valid literal value of length zero.

• Type Coercion Failure: If the property has been given a data type in the @context (such as xsd:integer, xsd:double, or xsd:dateTime), passing "" will cause a parsing or validation error. An empty string is not a valid lexical form for a number or a timestamp.
• When to use it: Only use "" if the property is explicitly a text string and a blank value is semantically meaningful data. This is often the case in impact report data, where a blank value may be semantically meaningful compared to "no data provided". The deliberate acceptance of blanks helps avoid a soup of arbitrary "blank identifiers" like "-" "n/a" "na" and so on.

2. The Nuance of Empty Arrays ([]) for Object Properties

An empty array [] explicitly declares a collection containing zero items.

• The Behavior: During JSON-LD expansion, an empty array is dropped from the output unless it's explicitly tied to a container type like @set or @list (which are rarely or never used in the Common Impact Data Standard).
• When to use it: While [] safely resolves to "no relationships" for object properties, omitting the property is a more efficient, and recommended, pattern.