A bid deadline is the one field in this dataset where being wrong has a consequence you cannot recover from. So it gets three fields instead of one, and the reason is that 38.8% of federal deadlines do not contain a time.
The problem with one deadline field
SAM.gov exposes a response date. It looks like a timestamp. Put it in a calendar and you get a precise moment — for the 61.0% of notices where that moment is real, and a fiction for the rest.
The three cases, measured
response_due_precision | Share | What it means |
|---|---|---|
instant | 61.0% | A real offset. response_due_utc is a true UTC instant you can convert. |
date_only | 38.8% | "Due on the 25th", no time. response_due_utc is null. |
local_naive | 0.2% | A wall-clock time with no zone. response_due_utc is null. |
Measured on 1,566 notices that carried a deadline at all — deadlines are present on 75.2%.
The midnight-UTC trap
Here is the specific failure. For a date-only deadline, SAM.gov stamps midnight UTC. That is a syntactically perfect timestamp, and it is not a deadline — nobody said the bid is due at 00:00 UTC.
Pass it through and two things go wrong. A bidder in Los Angeles sees 5pm the previous day, which is early by up to a day. And nothing looks broken: the field is populated, the type is right, the value is plausible.
The three fields
response_due_local— what the notice says, as it says it. This is what you display.response_due_utc— a true UTC instant, andnullunless the precision isinstant. This is what you schedule against.response_due_precision— which case you are in, so the choice between the first two is made by code rather than by hope.
response_timezone comes along too, so an instant can be rendered in the contracting office's local time rather than the reader's.
What this means for a bid calendar
-- Real deadlines: safe to convert, safe to alarm on
SELECT notice_id, title, response_due_utc
FROM notices
WHERE response_due_precision = 'instant'
AND response_due_utc > now();
-- Date-only: show a human the date, do not invent a time
SELECT notice_id, title, response_due_local, response_due_precision
FROM notices
WHERE response_due_precision <> 'instant'
AND response_due_local IS NOT NULL;Two queries rather than one, and the second is the one that keeps you honest: a date-only deadline belongs in front of a person who will read “due on the 25th” and act on it, not in an automated countdown.
The general principle
When a source encodes uncertainty as precision, the right response is to add a field rather than to pick a convention. Three fields cost a little storage; picking midnight costs somebody a bid.
The same reasoning produced `budget_type` on Workana and the `*_raw` fields on coches.net: record which case you are in, and keep what the source actually said.
