Technical Article

PDF Number Grammar vs JSON: NaN, Infinity and null in Delphi

"value":-.25 is what a JSON writer produces when it copies a perfectly legal PDF number token as is, and a strict RFC 8259 parser gives up at the point right after the minus sign. Its neighbours +1.5 and 007.5 from the same PDF array fail the same way. Turning PDF numbers into JSON means re-spelling each token digit by digit, writing null for NaN and Infinity, and keeping the regional decimal comma out of the output

Four spellings PDF accepts and JSON rejects

The two grammars disagree on four small details. ISO 32000-1 §7.3.3 lets a number start with a plus sign, omit the integer part (.5), end on a bare point (4.) and carry leading zeros (007.5). RFC 8259 §6 allows none of that. A JSON number has an optional minus, an integer part that is either 0 or starts with a digit from 1 to 9, and at least one digit after any decimal point. Producers are entitled to the PDF forms, and generators that print numbers with their own formatting code, along with files someone fixed by hand in a text editor, use them

The collision gets sharper in a library that respects the source text. PDF Library for Delphi (PDFlibPas) keeps the exact characters it parsed for every real number, so a calibrated colour value saves back unchanged instead of being rounded to the default four decimals; the reasoning is in preserving parsed PDF decimal precision. The tokeniser already patches .5 into 0.5 and 4. into 4.0 while reading, and integers are rebuilt from their value, so +3 comes back as 3. Three spellings still reach the writer verbatim: a signed leading point (-.25), an explicit plus on a real (+1.5) and leading zeros (007.5)

A writer that pastes those stored characters straight into JSON produces a file that looks fine in an editor. The trouble starts on the way back in. SetObjectJSON returns 0, and LastErrorCode reports PDFLIB_ERROR_OBJECT_JSON_INVALID, which is 105

PDFlibPas GetObjectJSON rewrites the PDF number tokens RFC 8259 rejects digit for digit: -.25 becomes -0.25, +1.5 loses the plus, 007.5 drops its leading zeros, and fractional digits like 1.250000 survive, because formatting from the stored Double would add binary noise
Appending the exact parsed text would let the export succeed while a strict reader stops with Invalid JSON number and error 105, so the writer re-spells each token instead

The round trip below is the quickest way to see what GetObjectJSON actually emits. Each number arrives wrapped as {"type":"number","value":...}, and the three awkward tokens come out as -0.25, 1.5 and 7.5

uses
  System.SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  JSON: AnsiString;
begin
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('legacy-drawing.pdf', '') = 0 then
      raise Exception.Create('load failed');

    // Object 12 is an array written as [-.25 +1.5 007.5]
    JSON := Lib.GetObjectJSON(12, 0);
    if JSON = '' then
      raise Exception.CreateFmt('export failed, error %d',
        [Lib.LastErrorCode]);
    // Each element reads {"type":"number","value":-0.25} and so on

    // SetObjectJSON returns 1 on success; pass 0 for Options
    if Lib.SetObjectJSON(12, JSON, 0) = 0 then
      raise Exception.CreateFmt('round trip rejected, error %d',
        [Lib.LastErrorCode]);

    Lib.SaveToFile('legacy-drawing-roundtrip.pdf');
  finally
    Lib.Free;
  end;
end;

Re-spelling the token instead of recomputing it

GetObjectJSON edits the stored characters rather than formatting the parsed Double. It reads an optional sign, collects the digits on either side of a single decimal point, and then makes only the changes JSON insists on: the plus goes, leading zeros are stripped down to one, an empty integer part becomes 0, a bare trailing point is dropped, and a minus is put back in front. A token that contains any other character, or no digits at all, is formatted from its parsed value with ten decimals instead, and that path writes null when the value is not finite

PDFlibPas GetObjectJSON reads the sign, collects digits around a single decimal point and applies only the edits JSON demands, while any other character or an empty digit run falls back to PLJSONNumber, which writes null for NaN and Infinity instead of a number
Re-spelling beats recomputing: the tokeniser already patched .5 and 4. on the way in, so the writer keeps every surviving digit and the round trip recreates exactly the same value
  • -.25 becomes -0.25, and +.5 becomes 0.5
  • +1.5 becomes 1.5
  • 007.5 becomes 7.5, while 0.75 stays as it is
  • 4. becomes 4 if such a token ever reaches the writer
  • 2.22221 and 1.250000 keep every fractional digit, trailing zeros included

Formatting from the Double would have been a one-liner, and it would have been wrong in two ways. The document's default output precision is four decimals, so 2.22221 would lose a digit. Raising the precision does not rescue it either: 0.1 has no exact binary form, and a 17-significant-digit conversion prints 0.10000000000000001. Keeping the original digits means SetObjectJSON and ImportObjectJSON, which hand each JSON number back to the PDF tokeniser, rebuild exactly the value the file declared

That promise covers the value. The bytes are another matter. After a re-import, -.25 is stored and saved as -0.25; both spellings are equal under §7.3.3, yet a byte-level diff flags the change. On a document whose byte ranges are covered by a signature, we would not run objects through an export and import cycle at all unless the plan is to sign again afterwards

What does null mean in GetDocumentJSON output?

GetDocumentJSON writes null for any number that is NaN or infinite, because RFC 8259 §6 has no syntax for either. Infinity is easier to produce than it sounds. The PDF tokeniser accumulates digits by repeated multiplication into a Double, which tops out near 1.8 × 10308, so an integer literal a little over 300 digits long turns into +Inf during parsing. Ordinary producers never write such a literal; fuzzed and hostile files do, which is why a 400-digit integer belongs in the same test corpus as the cases in hardening a Pascal PDF parser against malicious files

The finiteness check has to come first. GetDocumentJSON prints integral values below MaxInt as integers and everything else with Pascal's Str(D:0:6), which is fine for 1.25 and fatal for +Inf, because Str then writes the text +Inf and no JSON consumer will parse that. The six-decimal formatting also marks what the document JSON is for. It is an overview of the whole file. When you need the exact digits of one object, ask GetObjectJSON for that object

The null is deliberately lossy, and it shares its spelling with something else. A PDF null object also comes out as null in the document JSON, so a consumer cannot tell 'the file said null' from 'the file said a number too large for a Double' by looking at that one value. GetObjectJSON keeps them apart: the PDF null object is written as {"type":"null"}, and a number keeps its "type":"number" wrapper. Code that reads document JSON should accept null anywhere a number can appear, log the object number, and treat the file as suspect instead of substituting 0

Why can a single NaN abort an SVG or JSON export?

A number formatter that scales its input and calls Round hits Round(NaN), and on Win32, where Delphi leaves the x87 invalid-operation exception unmasked, that raises EInvalidOp. The exception fires after the writer has already emitted part of its output. One degenerate measurement, a 0/0 inside a metric or a NaN passed in by a caller, leaves a truncated file on disk

PLDoubleToStr in PDFlibExtra, the invariant formatter the library uses for content streams, SVG, XML, CSV and most of its JSON, returns 0 for NaN. Its integer branch clamps the scaled value to ±9.2 × 1018 just like the fractional branch, so Infinity also comes out as a finite literal. In a content stream that is the right call. An operand slot must hold a number, and a viewer that meets +Inf in the middle of a path has nothing sensible to draw

In a report, zero is the wrong call, and we feel strongly about this one: 0 is a perfectly plausible deskew angle or pixel error, so writing it for 'no answer' corrupts the data without anyone noticing. Report writers use PLJSONNumber(Value, Decimals) from the same unit instead, which writes null for NaN or Infinity and invariant digits otherwise. GetSimilarImageDeduplicationReportJSON, GetAnnotationHitsJSON and the barcode, deskew, structured text and PDF/VCR reports all go through it, so a non-finite deskew angle reaches the consumer as null

PDFlibPas stops NaN and Infinity three ways: AddPageMatrix, ScalePage and RedactRegion reject non-finite arguments up front, PLDoubleToStr writes 0 for content-stream slots, and PLJSONNumber writes null in reports, where zero would read as a plausible measurement, so Round(NaN) never gets the chance to raise EInvalidOp mid-export
Zero is the right answer for a content stream and the wrong answer for a report, so the report writers hand every Double to PLJSONNumber and let null say the value was present but unrepresentable

The same function is public, so your own JSON alongside the library's can follow the same rule. The sketch below builds a small skew record; the shape of the record is ours, the formatting call is the library's

uses
  SysUtils, PDFlibTypes, PDFlibExtra;

// Your own report writer, using the library's number rule
function SkewReportJSON(Page: Integer; Angle, Confidence: Double): string;
var
  B: PLStringBuilder;
begin
  B := PLStringBuilder.Create(128);
  try
    // Turn every Double into text first; PLJSONNumber writes null
    // for NaN or Infinity and always uses a decimal point
    B.Append('{"page":').Append(Page)
     .Append(',"angle":').Append(string(PLJSONNumber(Angle, 4)))
     .Append(',"confidence":').Append(string(PLJSONNumber(Confidence, 4)))
     .Append('}');
    // Never B.Append(Angle): on Delphi that overload follows the user locale
    Result := B.ToString;
  finally
    B.Free;
  end;
end;

Where the user locale sneaks into JSON

Any formatter that consults regional settings can put a comma where JSON needs a point. PLFloatToStr in PDFlibExtra is a thin wrapper over FloatToStr, and that is exactly what it does. Write a field such as maxAcceptedMeanError with it on a German or French desktop and you get "maxAcceptedMeanError":1,5. A JSON parser reads that as the value 1 followed by a stray token. That field reports the worst accepted pixel error from perceptual image deduplication, and GetSimilarImageDeduplicationReportJSON writes it through PLJSONNumber(Stats.MaxAcceptedMeanError, 6), so the separator stays a point whatever the machine is set to

The second route is quieter. On Delphi, PLStringBuilder is a plain alias of System.SysUtils.TStringBuilder, whose Append(Double) overload formats through the user locale. Free Pascal builds use a small Unicode builder class from PDFlibTypes instead, because the FPC runtime's own TStringBuilder is ANSI-only. Compile the same source with both and the Delphi build can disagree with the FPC build. A test that only runs on Free Pascal, or only on an en-US machine, will not see the comma

The test below reproduces a comma desktop inside the process and feeds the report to a strict parser. Pick an input that really contains near-duplicate images; with no matches the mean error is 0, and a value with no fractional part hides the separator problem

uses
  System.SysUtils, System.JSON, PDFlibrary;

var
  Lib: TPDFlib;
  Report: WideString;
  Parsed: TJSONValue;
begin
  // Make this process behave like a German or French desktop
  FormatSettings.DecimalSeparator := ',';
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('scanned-batch.pdf', '') = 0 then
      raise Exception.Create('load failed');
    // Dry run with thresholds 2, 2, 4: the document is not modified
    Lib.GetSimilarImageDeduplicationReportJSON(2, 2, 4, Report);
    Parsed := TJSONObject.ParseJSONValue(Report);
    // This nil check is yours to add, not part of the library
    if Parsed = nil then
      raise Exception.Create('report is not valid JSON on a comma locale');
    Parsed.Free;
  finally
    Lib.Free;
  end;
end;

Three inputs worth keeping in the test suite

Number handling in JSON is cheap to break and cheap to guard. One page carrying -.25, +1.5 and 007.5 covers the grammar gap; check that GetObjectJSON output parses and that SetObjectJSON returns 1. One object holding a 400-digit integer covers overflow; the document JSON should show null at that position. One report produced with DecimalSeparator set to a comma covers the locale. Run each through a strict parser rather than reading the output by eye, because 1,5 and 1.5 are easy to miss in a long line of JSON

Object JSON, document JSON and the analysis reports share these number rules across Delphi, C++Builder and Free Pascal builds. The PDF Library for Delphi product page lists the editions and the rest of the object-level and reporting API