[OmarAlJarrah]

Summary

format: date-time-local and format: time-local each hoisted a Scalar over string that kept the format as its encoding, although the IR has a primitive for each: datetime, a date and time without offset, and time. format: time is RFC 3339's full-time, which carries an offset, and it lowered to time. The doc on time said only "a time of day without date", and the emitter design types time as a local time (LocalTime, the Go runtime's TimeOfDay), so the offset had nowhere to go.

dtl: {type: string, format: date-time-local}
tl:  {type: string, format: time-local}
t:   {type: string, format: time}

Property	main	This branch
dtl	Scalar over string, Encoding.Name: date-time-local	t/prim/datetime
tl	Scalar over string, Encoding.Name: time-local	t/prim/time
t	t/prim/time	Scalar over string, Encoding.Name: time

• time is documented as holding no offset, as datetime does beside datetime_offset (ir/types.go, and a new docs/ir/primitives.md#offsets, which states each time kind in RFC 3339's terms).
• The format table maps time-local to time and date-time-local to datetime, and has no time row, so time keeps its format on a hoisted Scalar the way any format without a primitive does (docs/compilers/openapi.md#string-formats).
• The value judges follow the kinds. time now admits an RFC 3339 partial-time, where before it admitted a full-time. datetime had no judge: it admitted no value, and a literal compared with it read as an overlap. It now admits a local date-time. A value written under these formats is therefore judged by the grammar its format names:
  • {type: string, format: time-local, enum: ["15:04:05", "16:04:05"]} gets ValueType: time, where main kept the format verbatim under Unmodeled with an info.
  • Under allOf, a broader declaration's default: "2024-01-01T00:00:00" is adopted beside format: date-time-local, and "2024-01-01T00:00:00Z" is refused. main refused both.
  • A leap second in a local form is admitted at any minute, since an offset could place UTC's 23:59 at any local minute. With an offset, it is still admitted only where the time in UTC is 23:59.
• Under allOf, the Scalar that format: time now lowers to is still judged by RFC 3339's full-time grammar, so the fold judges it as main did while time was the kind, but for the two cases "allOf under format: time" below names.

Design

The alternative was a time_offset kind beside datetime_offset. It was weighed and not taken, and docs/ir/primitives.md#offsets records why, next to the chosen design:

• Only one spelling. JSON Schema's time is the only way to write a time of day with an offset in any format the IR is designed against. TypeSpec's plainTime, Protobuf's google.type.TimeOfDay and Erlang/OTP's calendar:time() hold no offset, and Smithy, GraphQL and Swagger 2.0 have no time of day at all.
• Premise: specs write values with no offset under time. I tested this on a local corpus of about 1,800 real-world OpenAPI documents with grep -rnE -A4 'format"?\s*:\s*"?time"?\s*,?\s*$' <corpus>. Each value written next to format: time (enum members and a default) has no offset. A kind promising an offset would make a target refuse those values.
• What the Scalar gives instead. It keeps the format as written and leaves the reading to the target's type table, where a {string, "time"} row can make the choice.

date-time-local and time-local reached no kind before, and format: time reached the wrong one, so this is a fix. The golden spec writes none of the three formats: jq '[.. | objects | select(has("format")) | .format | strings] | map(select(. == "time" or . == "time-local" or . == "date-time-local")) | length' returns 0 at cloudflare/api-schemas@319dc756.

What reads these kinds

Each place that reads time or datetime, and what it does now:

• merge.Admits and literalAgainst. Changed as described above.
• spelling.Relate. It reads the table. datetime now refines string and is disjoint from every other format but binary, which overlaps each of them, and relationRoots in its test no longer lists it. So under allOf, format: date-time redeclared as format: date-time-local now draws an openapi/conflicting-redeclaration warning (incompatible types), as uuid against date-time does, where main reported an info overlap against the hoisted Scalar. No string is a date-time both with and without an offset.
• schema.enumValueType. It goes through Admits. datetime can now be an Enum.ValueType, which puts it in the same position as date, time and uuid: it has no Go constant form, which docs/emitters: a closed enum whose value type has no Go constant has no lowering #1202 tracks.
• An enum declaring format: time. It now keeps the format verbatim under Unmodeled with an info, as an email enum does. Before, members carrying an offset gave it ValueType: time.
• allOf under format: time. merge holds the grammar of time, RFC 3339's full-time, the one format the table pairs with no kind that it can still judge (admitsFormat). Wherever the fold's judge reads a kind, it reads a Scalar hoisted for time as a string format of its own. That Scalar sits within string, overlaps binary, and is disjoint from every other kind and from an enum none of whose members it admits, and it admits a value its grammar admits. So, as on main, a full-time default beside it is adopted, a const that is one narrows the field, and time against date-time is an openapi/conflicting-redeclaration warning. time against time-local is now that warning too, where main reported an info overlap, since no string is both. A const narrows the Scalar only where the node says nothing but its base, the format and bounds. A description, example or extension written beside format: time lands on that node, so with one the pair stays an overlap, and both declarations are kept and reported. main narrowed that case, since it put the description on the property beside a bare time. Narrowing it again needs the merge to build a node that adopts the broader side's detail, which openapi: an allOf narrowing between two enums or two lists is resolved by branch order #1042 tracks. docs/compilers/openapi.md#allof-redeclared-property states each verdict.
• Census. PrimKind "datetime" comes out of testdata/unwitnessed.golden.txt, since scalar-format now sets it.
• Emitter design. The Go and Kotlin rows for time (TimeOfDay, LocalTime) already read it as offset-free, and datetime already has rows. No {string, "time"} row exists, so a target falls back to string with the unmapped-encoding info, per docs/emitters/contract/type-table.md.
• Docs. I grepped docs/ for time and datetime statements: git grep -nE 'PrimTime|PrimDatetime|`time`|`datetime`' -- docs. The one that assumed the old set was the list of string-spelled kinds in primitives.md, which now includes datetime.

A default that its own format refuses, such as {format: time-local, default: "10:15:30Z"}, is kept with no diagnostic. main behaves the same for every format ({format: uuid, default: "hello"}), and #643 tracks it.

Test plan

• I compiled the spec above, plus enums and allOf defaults under each format, with morphic compile --verify on main and on this branch. The table and bullets above are what that run printed. Exit code was 0 on both.
• Each piece of the fix was planted back and went red, each time in the test named here:
  • datetime admitting nothing: TestAdmits_JudgesEachKindExactly.
  • time judged as a date-time: TestAdmits_JudgesEachKindExactly.
  • A local leap second checked against UTC: TestAdmits_JudgesEachKindExactly.
  • A local clock accepting any tail: TestAdmits_JudgesEachKindExactly and TestFold_AnInadmissibleValueIsKeptNotAdopted.
  • The datetime overlap restored in literalAgainst: TestTypeJudge_RelateArms, through the two rows this PR adds. Without them, nothing went red.
  • The time-local or date-time-local row removed, or a time row restored: TestFormatTable_EveryStringRowLowersToItsPrimitive and the scalar-format conformance case.
• Corpus differential, main against this branch, over every spec in the corpus above that writes one of the three formats, rerun after merging feat(ir)!: type the secrecy and stability a document states #1229 with the same result. Exit codes and error diagnostics are identical. The other diagnostics are identical except one info at an enum under format: time, which now gives the generic reason for keeping the format verbatim; both versions keep it. In each spec, the primitives reached and the format scalars hoisted move as the table above says (counted per spec, not diffed node by node).
• The allOf judge for time is pinned by merge.TestAdmitsFormat_JudgesTimeAsAFullTime, merge.TestAdmitsFormat_SharesNoStringWithAKind, merge.TestRelateKinds_ReadsAHeldFormatAsAStringFormat, merge.TestKindOf_TheFirstEncodingDecidesTheFormat, new rows in merge.TestTypeJudge_RelateArms and merge.TestTypeJudge_AdmitsPerNode, and schema.TestAllOf_ATimeIsJudgedByItsGrammar, which compiles each case in both branch orders. I planted 31 defects in it: in the grammar, in which Encoding counts as a format, in each relation formatAgainst returns, in the literal and enum verdicts, and in which detail blocks a narrowing. Each went red in one of those tests, and a clean control passed.
• The same branch compiled before and after the allOf judge change gives identical IR and diagnostics on all 2,201 specs I swept (every file in the corpus above with an openapi, swagger or asyncapi key, plus testdata/), and on the golden spec at cloudflare/api-schemas@f37e206d. Run on my 22 probe specs for these cases, the same instrument flags the five whose verdicts the change moves, and no other. The harness oracles, order invariance among them, pass on those specs.
• go test ./compilers/openapi/e2e -run TestConformance -update changed only scalar-format.golden.json, by the three properties. go test ./cmd/morphic-census -update removed only the datetime line.
• The gate passes on CI.

Breaking

IRVersion moves from 0.27.0 to 0.28.0, with no change of shape. The generations row says what meaning changed. A consumer pinned to 0.27.0 refuses the document. If it read the new document anyway, it would see:

• values with no offset where it expected time to carry one;
• format: time arriving as a Scalar with Encoding.Name: time;
• no time-local or date-time-local encodings where it used to find them.

#1229 took 0.27.0 first, so this branch merged main and takes 0.28.0. #1269, #1333, #1340 and #1361 also move IRVersion; whichever of these merges after another takes the next free version.

Closes #869
Closes #1353