Floating point numbers in the Presentation API

[zimeon]

IIIF Presentation API v3 has just one instance of "floating point":

• duration "MUST be a positive floating point number."

IIIF Presentation API v4 draft data model has many instances of "floating point", including:

• duration "MUST be a positive floating point number."
• far "MUST be a non-negative floating point number"
• viewHeight "MUST be a positive floating point number"
• x, y, z "MUST be a number (floating point or integer)."

I think the v3 and draft v4 specifications could be clearer about what is and isn't allowed for "floating point number". The current text has led to what I think is an erroneous suggestion in the Simplest Manifest - Video cookbook recipe:

The value of the duration property must be a floating point number. If the duration value you have is an integer, it therefore needs to be written with at least a decimal point and a trailing zero: 1985.0 rather than 1985.

Neither JSON nor JSON-LD make a distinction between 1985.0 and 1985, nor does our validator (and also 1.985E3 is valid). The set of floating point numbers includes the integers and adding a trailing .0 is meaningless in JSON (though it is meaningful in various programming languages). The current text in v4 draft for x, y and z that must be "a number (floating point or integer)" I think adds to the confusion by suggesting that integers are somehow not included in floating point numbers.

Plain JSON

https://datatracker.ietf.org/doc/html/rfc8259#section-6

A number is represented in base 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part. Leading zeros are not allowed.

A fraction part is a decimal point followed by one or more digits.

An exponent part begins with the letter E in uppercase or lowercase, which may be followed by a plus or minus sign. The E and optional sign are followed by one or more digits

JSON does not distinguish between integers and floating point numbers in terms of syntax. The number 123 may equally well be written 123, 123.0 or 1.23E2.

JSON-LD

https://www.w3.org/TR/json-ld11/#terms-imported-from-other-specifications

In the JSON serialization, a number is similar to that used in most programming languages, except that the octal and hexadecimal formats are not used and that leading zeros are not allowed. In the internal representation, a number is equivalent to either a long or double, depending on if the number has a non-zero fractional part (see [WEBIDL]).

https://w3c.github.io/json-ld-bp/#native-values

When possible, property values SHOULD use native JSON datatypes such as numbers (integer, decimal and floating point) and booleans (true and false).

https://www.w3.org/TR/json-ld11/#conversion-of-native-data-types

Can verify this in the JSON-LD playground:

{
  "@context": {
    "ex": "http://ex.org/term/",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "ex:d": { "@type": "xsd:double" },
    "ex:e": { "@type": "xsd:double" },
    "ex:f": { "@type": "xsd:double" }
  },
  "@id": "http://ex.org/1",
  "ex:a": 123,
  "ex:b": 123.0,
  "ex:c": 1.23E2,
  "ex:d": 123,
  "ex:e": 123.0,
  "ex:f": 1.23E2
}

produces the following n-quads:

<http://ex.org/1> <http://ex.org/term/a> "123"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://ex.org/1> <http://ex.org/term/b> "123"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://ex.org/1> <http://ex.org/term/c> "123"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://ex.org/1> <http://ex.org/term/d> "1.23E2"^^<http://www.w3.org/2001/XMLSchema#double> .
<http://ex.org/1> <http://ex.org/term/e> "1.23E2"^^<http://www.w3.org/2001/XMLSchema#double> .
<http://ex.org/1> <http://ex.org/term/f> "1.23E2"^^<http://www.w3.org/2001/XMLSchema#double> .

(It seems that the automatic processing of numbers is so built into the playground that attempting to get a link to the above example doesn't work properly -- all the numbers come out as 123!)

What do we learn from this?

• The form of the number as JSON-LD input does not affect the number and its type obtained after processing
• The IIIF context could be used to specify type information for numeric properties (e.g. https://iiif.io/api/presentation/3/context.json maps duration to http://www.ebu.ch/metadata/ontologies/ebucore/ebucore#duration but does not specify @type)

Presentation validator and Theseus viewer

Taking an shortened version of the cookbook recipe Begin playback at a specific point - Time-based media and testing with the Presentation API Validator it seems that duration may be either a integer, a decimal, or a floating point representation. All of the following validate correctly and also work fine in the Theseus viewer:

Integer

• https://github.com/zimeon/iiif-number-tests/blob/main/v3-duration-integer.json has "duration": 1801
• in Theseus: https://theseusviewer.org/?iiif-content=https://raw.githubusercontent.com/zimeon/iiif-number-tests/refs/heads/main/v3-duration-integer.json)

Decimal

• https://github.com/zimeon/iiif-number-tests/blob/main/v3-duration-decimal.json has "duration": 1801.055
• in Theseus: https://theseusviewer.org/?iiif-content=https://raw.githubusercontent.com/zimeon/iiif-number-tests/refs/heads/main/v3-duration-decimal.json)

Float

• https://github.com/zimeon/iiif-number-tests/blob/main/v3-duration-float.json has "duration": 1.801055E3
• in Theseus: https://theseusviewer.org/?iiif-content=https://raw.githubusercontent.com/zimeon/iiif-number-tests/refs/heads/main/v3-duration-float.json)

Prior discussions in API repo

I do not find a discussion of the issue of exactly what "MUST be floating point" is intended to mean in the specification, nor or any JSON or JSON-LD ramifications. Related:

• Specify the valid values for size pct:n #1240 "Specify the valid values for size pct:n" -- suggests that floating point is intended to include integer values
• Quoted integers/floats should still not be allowed #1252 "Quoted integers/floats should still not be allowed" -- agreed that JSON numbers must be used, not allowing coercion for quoted numbers
• Can context be modified to generate unquoted integers/floats from RDF? #1291 "Can context be modified to generate unquoted integers/floats from RDF?" - concluded not possible
• Consider advice/formatting of floating points in Image API spec #1468 "Consider advice/formatting of floating points in Image API spec" -- about the specifics of decimal representation for Image API which resulted in the canonicalization description https://iiif.io/api/image/3.0/#47-floating-point-values. Although I am in part responsible for this is note that "floating point" (e.g. 1.23E2) is not actually allowed and this should say simply "decimal values". However, this is about URI syntax and not JSON-LD representation.
• Minor contradiction regarding the Rotation parameter in Image API 3.0 #2311 "Minor contradiction regarding the Rotation parameter in Image API 3.0)" - does not really touch on representation of the values, just description of requirements

Proposals

• Consider an explanation of what is allowed when a value "MUST be a floating point number" (or maybe use "JSON number" instead?)
• Avoid saying "MUST be a number (floating point or integer)."
• Consider typing in the @context
• Fix cookbook recipes to avoid implying that a trailing .0 decimal must be added to values that "MUST be a floating point number"