Façade-X Mappings

The starting point is the idea that Facade-X should not modify the lexical form of data values. Previously, we mapped JSON numerals to xsd:decimal (see also SPARQL-Anything/sparql.anything#620)

However, JSON numerals and xsd:decimal lexical forms are not the same set: JSON allows exponents (1.5e3) and xsd:decimal does not. Keeping the source text, therefore, produces ill-typed literals, so the mappings need a shared rule for when to keep a value's surface form and when to rewrite it as the canonical form. Cases of mismatches between format specifications and XSD datatypes may arise. We should discuss this issue more generally and then make a decision that can guide future mappings.

We review first what SPARQL Anything does, then discuss potential solutions.

SPARQL Anything types every JSON number as xsd:decimal and copies the numeral from the source as the lexical form. From tests/json/2-features:

The last two exponent rows are ill-typed literals. The lexical space of xsd:decimal is (\+|-)?([0-9]+(\.[0-9]*)?|\.[0-9]+), with no exponent notation (XSD 1.1 Part 2, §3.3.3.1). A SPARQL engine cannot compute a value for them, so numeric comparisons and arithmetic on them fail. The behaviour is also inconsistent with itself: 3.0 keeps its surface form, but -0 is normalised to 0.

JSON and XSD agree on the values but not on the numerals:

• Values. Every JSON number has the form d × 10^e with finitely many digits, so it is in the value space of xsd:decimal: numbers of the form i / 10^n (§3.3.3). xsd:decimal can represent every JSON number exactly.
• Numerals. The JSON number grammar (RFC 8259 §6) allows an exponent, which the xsd:decimal lexical space does not. Conversely, XSD allows forms JSON forbids (+1, .5, 5., 007), but those don't matter here. Every JSON numeral without an exponent is a valid xsd:decimal lexical form; every numeral with an exponent is not.
• Why not xsd:double. The xsd:double lexical space accepts exponent notation, but its value space is m × 2^e with |m| < 2^53 (§3.3.5). 2E-4 and 12345678901234567890 have no exact double value, so switching to xsd:double would lose information.

• Every JSON number is typed xsd:decimal.
• If the numeral has no exponent, its source text is kept as the lexical form (3.0 → "3.0", -0 → "-0").
• If the numeral has an exponent, the lexical form is the canonical xsd:decimal representation of its value (1.5e3 → "1500", 2E-4 → "0.0002").

Every literal produced is well-typed and exactly equal in value to the JSON number. The surface form is kept wherever XSD allows it.

All other numbers are unchanged. The expected output of tests/json/2-features needs updating to match, and SPARQL Anything needs a fix.

Façade-X aims to represent the source as it is, which argues for keeping the surface form of values. In RDF, though, a typed literal ties the surface form to a datatype's lexical space, and source grammars rarely match XSD lexical spaces exactly. Surface form also matters beyond values: "3.0"^^xsd:decimal and "3"^^xsd:decimal are equal values but different RDF terms, so sameTerm, DISTINCT and joins on literals depend on the lexical form.

This will come up in every mapping whose source format has typed values: YAML (numbers, booleans, dates), spreadsheets (numbers stored as doubles, dates as serial numbers), and possibly XML if schema-aware typing is considered. CSV and plain XML avoid it only because all their values are strings.

Options for a principle shared by all mappings:

1. Keep the surface form when it is valid for the target datatype; otherwise use the canonical form. This is the current draft. It is well-typed, but some surface forms are lost, and a reader cannot tell which values were rewritten.
2. Always use the canonical form. Deterministic, but loses the surface form everywhere (3.0 → 3).
3. Always keep the surface form, with a datatype whose lexical space accepts it. Use the XSD datatype when the source form is in its lexical space; otherwise use a datatype that accepts the source grammar.
4. Keep the surface form, even if ill-typed. This is the current SPARQL Anything behaviour, and not something a specification should require.

The source text of every value is its lexical form, and no value is rewritten. The datatype is chosen so that the literal is well-typed. In the case of JSON numerals, we first map to xsd:decimal (design choice) and then verify conformance with the surface form:

• when the source form is in the lexical space of the natural XSD datatype, that datatype is used (42 → "42"^^xsd:decimal, 3.0 → "3.0"^^xsd:decimal, -0 → "-0"^^xsd:decimal);
• otherwise, a datatype whose lexical space is the source grammar is used (1.5e3 → "1.5e3"^^D): xsd:double in the example.
• Mapping specifications should describe the decision process explicitly.
• If no XSD datatype is found that can match the surface form, the source is probably malformed, and the system should fall back to xsd:string.

If agreed, this becomes a common principle in the format mappings page: "The lexical form of a value is its source form. The datatype is the natural XML Schema datatype for the value when the source form is in its lexical space; otherwise it is a datatype whose lexical space accepts the source form, as defined by the mapping." The JSON draft and tests/json/2-features would then be updated accordingly. Opinions welcome.