Spec clarification requests: escape sequences, duplicate capabilities, and PATH defaults

[crowecawcaw]

While developing conformance tests for the OpenJD specification, I identified several areas where the spec is unclear or only implies behavior without explicitly stating it. Clarification would help ensure consistent implementations across different libraries.

Areas Needing Clarification

1. Format String Escape Sequences (Section 7.3)

Current state: The spec defines format strings with {{ ValueReference }} syntax but does not specify how to include literal brace characters in a format string.

Question: Should there be an escape mechanism (e.g., {{{{ → {{) to allow literal double-braces in format strings? If so, what is the syntax?

Impact: Without this, users cannot include literal {{ or }} in format string values.

2. Duplicate Capability Names in Host Requirements (Section 3.3)

Current state: The spec does not explicitly state whether duplicate capability names are allowed in the amounts or attributes arrays.

Example:

hostRequirements:
  amounts:
    - name: "amount.worker.vcpu"
      min: 4
    - name: "amount.worker.vcpu"  # Duplicate - allowed?
      min: 8

Question: Should implementations reject duplicate capability names? The semantic ambiguity suggests they should be forbidden, but this isn't stated.

Suggested clarification: Add a constraint like "No two elements in the amounts/attributes array may have the same value for the name property."

3. PATH Parameter Default Values (Section 2.2)

Current state: The default property for <JobPathParameterDefinition> references <JobParameterStringValue>, which allows "Any" characters with no path-specific constraints.

Question: Are absolute paths allowed as defaults? The current spec implies yes (since any string is valid), but the openjd-model library rejects them. If absolute paths should be forbidden, this constraint should be explicit.

4. Descending Range Expression Behavior (Section 3.4.1.1.1)

Current state: The spec defines <Range> = x-y mathematically as {x} ∪ { x+m: m∈ℤ⁺, x+m ≤ y }. This means that 5-1 produces [5] (only the start value), but this edge case behavior may not be obvious to implementers.

Suggestion: Add an example in the table showing descending range behavior:

<IntRangeExpr>	List of values
"5-1"	[5]

This would make the mathematical definition's implications explicit. Or clarify that the this range is invalid.