fix: Specify how a numeric string's leading and trailing zeros render

[leongdl]

What

Adds §7.5 Numeric strings, which says what an <intstring>/<floatstring> renders as, and one conformance fixture that pins it for range elements.

The rule, in one line: leading zeros go, trailing zeros stay.

- name: Weight
  type: FLOAT
  range: ['2.50', '03.500', '0.50']   # -> 2.50   3.500   0.50

- name: Frame
  type: INT
  range: ['02', '003']                # -> 2      3

Why the spec needs to say this

<intstring> and <floatstring> are defined only as "a string whose value is the string representation of" a number. That says what the element denotes; it does not say what it renders as. Implementations read it both ways, and two already-landed fixtures pull in opposite directions:

Fixture	Asserts	Reading
base/jobs/2.3--int-param-intstring-default-resolves	COUNT:7 from INT default: '007'	text is not preserved
EXPR/jobs/expr1.3.4--float-passthrough	PARAM:3.500 from FLOAT default: "3.500"	text is preserved

Both are right, and the reason is that the two kinds of zero are not the same thing:

• Leading zeros are redundant to the value. '02' and '2' ask for the same thing, and forwarding the text invokes a renderer with --frame 02.
• Trailing zeros are not redundant to the request. A fixed number of decimal places is something renderers commonly require, and the string form is the only way a Template can ask for one — a <float> literal cannot, because 2.50 and 2.5 are the same literal after parsing.

This came out of review on openjd-model-for-python#342, which normalized range elements to the number they denote and so dropped the trailing zeros. openjd-model-for-python#345 reverts that half; this PR is the spec statement behind it.

base/jobs/3.4.1.2--float-range-floatstring-elements-normalized in #179 states the fully-normalizing reading for a FLOAT range element. Its own comment flagged that it and expr1.3.4--float-passthrough could not both be right and that a ruling was needed. This is the ruling, and 3.4.1.2 is the one that moves — see the note on #179 below.

Rulings added in review

Review asked for a specific choice on the two cases §7.5 first left unspecified, rather than leaving a reader to infer one. Both follow the split the section already makes, so they landed inside the existing two rules rather than as exceptions:

Case	Ruling	Rule it joins
Exponent notation	'1E+2' renders 1E+2, keeping the case of its marker and the sign inside it	2, with decimal places
Leading +	'+2.50' renders 2.50	1, with redundant leading zeros

§7.5 went from 36 lines to 24 in the process. Only the sign of a zero is still open, and that is now one sentence rather than a bulleted list.

The fixture

base/jobs/7.5--numeric-string-zeros-in-range-elements.test.yaml, covering INT and FLOAT range elements in one template. '0.50' is in there because its leading zero is not redundant, it is the whole integer part, so an implementation that strips leading zeros by text has to leave one digit behind. Header trimmed from 34 comment lines to 10; every other fixture in that directory has at most 4.

Two details worth flagging for reviewers.

The assertions bracket each value (W[2.50]) rather than delimiting with a colon. The runner matches expected output as a substring, so an assertion of W:2.5 is satisfied by a line reading W:2.50. The closing bracket is what makes the forbidden entries forbid anything. base/jobs/3.4.1.2 in #179 has exactly that defect and reports a pass against either behaviour.

The exponent elements are spelled with a dot ('2.50E+2', not '1E+2') because the runner re-dumps the template through PyYAML, whose YAML 1.1 resolver needs a dot before an exponent and so leaves 1E+2 unquoted. A YAML 1.2 parser then reads that plain scalar as a number, i.e. a <float> literal, which makes no request about rendering at all. Measured: openjd-rs renders 100.0 for an unquoted 1E+2 and 2.50E+2 for the quoted form. Asserting on '1E+2' here would have tested scalar resolution rather than §7.5.

Verification

Measured against both implementations at their current mainline, after the rulings above:

Implementation	Scope	Result
openjd-rs d67bfb8	full 2023-09/*	1178 passed, 1 failed
openjd-model 0.11.9 + openjd-cli 0.7.7	2023-09/base/*	656 passed, 1 failed

In both, the single failure is this fixture and nothing else, and in both it fails on the leading + alone: they render W[+4.25] where §7.5 now requires W[4.25]. Every other element passes, including both exponent elements, so the exponent ruling ratifies what both already ship on this surface and only the + ruling needs code.

The Python full suite was not run to completion: it wedges on an unrelated EXPR range-cap fixture (a LIST[INT] range supplied beyond the list cap) that ran for minutes without finishing. Nothing to do with this change, but it is why the Python row is scoped to base.

Per-element, both surfaces:

Source	Surface	openjd-rs	Python	§7.5
'2.50'	FLOAT range	2.50	2.50	2.50
'03.500'	FLOAT range	3.500	3.500	3.500
'0.50'	FLOAT range	0.50	0.50	0.50
'2.50E+2'	FLOAT range	2.50E+2	2.50E+2	2.50E+2
'1.0e-3'	FLOAT range	1.0e-3	1.0e-3	1.0e-3
'+4.25'	FLOAT range	+4.25	+4.25	4.25
'02', '003', '+7'	INT range	2, 3, 7	2, 3, 7	same
'+2.50'	FLOAT default	+2.50	2.50	2.50
'03.500'	FLOAT default	03.500	3.500	3.500
'2.50E+2'	FLOAT default	2.50E+2	250	2.50E+2
'1.0e-3'	FLOAT default	1.0e-3	0.0010	1.0e-3
'+7'	INT default	7	7	7

The fixture pins the range rows only. The default rows are unpinned by any fixture and are filed against the implementations rather than widened into this PR: openjd-rs applies no §7.5 rule 1 at all on that surface (coerce_from_str, create_job/parameters.rs), and Python renders it with str(Decimal(...)) semantics, which keep significant digits but not the written notation.

CI will fail until both implementations release

Both conformance workflows install released versions (pip install openjd-cli, cargo install openjd-cli), so this fixture fails there until the + fix ships in each. Released Python 0.11.6 additionally predates openjd-model-for-python#345 and fails on the leading-zero side too.

One unrelated failure appears in the Python job on Windows, 3.4--path-parameter. It fails on mainline too, so it is a pre-existing baseline failure and not a regression from this PR.

Also left out

The sign of a zero. Both implementations render zero's sign away but differ on whether the decimal places survive it, so §7.5 says the case is unspecified rather than guessing.

Related

• openjd-model-for-python#345 — the implementation of this rule, and the revert of the trailing-zero normalization.
• openjd-model-for-python#342 — where the normalization came from, and the review comment that prompted the ruling.
• fix(model)!: keep the decimal places of a floatstring range element openjd-rs#354 — the same rule in openjd-rs, including the Float64::with_str guard that was dropping the decimal places of any zero.
• test: Add conformance fixtures for every coercible 2023-09 field #179 — carries 3.4.1.1 and 3.4.1.2. 3.4.1.1 (INT) agrees with §7.5 as written. 3.4.1.2 asserts W:2.5 from '02.50' and needs to become W:2.50, with a terminator so substring matching cannot hide it. Flagging rather than editing that branch from here.

[leongdl]

Pending fixing openjd py and rs.