ISO 8601 против RFC 3339: два формата дат, лежащих в основе ваших ответов API

Поле 'ISO 8601', которое отклоняет действительные ISO 8601 — дату недели или значение пониженной точности, отправленное на API, который ожидал RFC 3339

Поле API, случайно описанное как «ISO 8601», может принимать только одну форму даты и времени. Отправка другого представления, соответствующего стандартам, все равно может привести к сбою его синтаксического анализатора. Лекарство состоит не в том, чтобы спорить, опираясь на общее название; это документирование точной грамматики проводов с примерами и проверочными тестами.

ToolAcre обеспечивает стабильный канонический вывод из `Date.toISOString()`, но это не пакет соответствия для каждого представления. Рассматривайте сгенерированную строку как полезную форму обмена и сравнивайте ее с фактически принадлежащим вам контрактом API.

Поэтому схема должна публиковать регулярное выражение или формальный тип только в том случае, если она точно отражает синтаксический анализатор. Сами по себе примеры полезны, но случаи явного отклонения закрывают двусмысленность.

Широкий стандарт даты и узкая грамматика API не являются взаимозаменяемыми.

Сгенерированная форма содержит календарную дату `T`, время в миллисекундах и завершающую Z. Реализация называет ее ISO 8601 (UTC) в пользовательском интерфейсе. Ввод принимает то, что читает JavaScript Date, включая явное смещение и бесзональную форму даты и времени локального средства выбора.

Это поведение намного уже, чем у полного стандартного парсера. Даты недели, интервалы, продолжительность и пониженная точность не тестируются в репозитории. Таким образом, строка, принятая одним браузером, не гарантируется на разных языках, и отклоненная специализированная форма не опровергает ее статус в другом месте.

Фиксированная точность выходных данных в миллисекундах — это выбор форматирования, а не свидетельство того, что источник измерял миллисекунды. Дата, возможно, получила значение с точностью до целой секунды и по-прежнему печатает `.000`.

ToolAcre излучает одну форму в форме ISO; он не подтверждает полный стандарт ISO 8601

В рабочей книге описаны RFC 3339, его год и правила обязательного смещения. В исходном наборе нет текста RFC или специального синтаксического анализатора, поэтому эти сведения не утверждаются. Авторский контракт требует исключить неподдерживаемую точность, а не цитировать название по памяти.

Если ваш API означает RFC 3339, назовите его в схеме и протестируйте реализацию, основанную на фактической спецификации. ToolAcre может соединить известную эпоху с выходными данными UTC ISO для сравнения, но не может подтвердить, что произвольные входные данные удовлетворяют этому профилю.

Это редакционная и инженерная гарантия: профили стандартов представляют собой точные контракты, и их перефразирование без текста рискует изменить требования в документации.

Для требований RFC 3339 требуется внешний источник стандартов, которого нет в этом репозитории.

Утверждения об альтернативных разделителях, строчных обозначениях и `−00:00` зависят от конкретного языка стандартов. Они здесь опущены. Собственный детектор зон конвертера распознает завершающий Z или числовой `±HH:MM` и помечает дату и время без зоны как локальные; это граница, которую мы можем проверить.

Создайте проверку API на основе явных принятых примеров и случаев отклонения. Не делайте вывод о разрешении от удобного анализатора JavaScript Date. Разрешительный браузер может нормализовать ввод, который строгий сервер правильно отклоняет, скрывая дефекты совместимости во время ручного тестирования.

Специальный анализатор, учитывающий стандарты, должен возвращать структурированные причины ошибок. Разрешение Date нормализовать широкий ввод может превратить ошибку проверки API в позднее межплатформенное несоответствие.

Правила специального разделителя и неизвестного смещения опускаются без текста стандартов.

Значения эпохи делают арифметику и порядок более компактными, когда единица измерения и начало координат фиксированы. Текстовые даты и время делают чтение UTC или смещения видимым для людей и сохраняют этот указатель при передаче. Многие API выбирают одну каноническую строку, чтобы избежать неоднозначности целого числа или единицы измерения JavaScript.

Если API содержит оба значения, определите, какое поле является авторитетным, и проверьте соглашение. Устаревшая отформатированная строка рядом с новой эпохой хуже, чем любая из них по отдельности. ToolAcre может сравнить пару, преобразовав целое число и проверив сгенерированное значение ISO, но обеспечение согласованности принадлежит производителю.

Рабочий пример: одно мгновение, четыре представления — секунды эпохи, миллисекунды эпохи, строка RFC 3339 в UTC и одно с локальным смещением.

Используйте мгновенный `2025-02-03T10:22:00.000Z`. Его формы эпохи составляют 1,738,578,120 секунд и 1,738,578,120,000 миллисекунд. Чтение с явным смещением — `2025-02-03T12:22:00+02:00`; его анализ в ToolAcre возвращает ту же эпоху и каноническую строку UTC ISO.

Это четыре представления, проверяемые репозиторием: секунды, миллисекунды, выходные данные toISOString и строка числового смещения, проанализированная по дате. В примере не утверждается, что каждый внешний синтаксический анализатор принимает один и тот же синтаксис дробной точности или смещения. Перед отправкой запустите собственную проверку API.

Вычитание смещения +02:00 из записанных часов дает 10:22 UTC. Этого простого равенства достаточно, чтобы проверить этот конкретный ввод без обобщения полной стандартной грамматики.

Рабочий пример: одно мгновение из четырех форм, которые может проверить этот репозиторий.

Заголовки HTTP и даты электронных писем используют текстовые контракты, которые здесь не реализованы. ToolAcre не форматирует эти протоколы и не обещает, что его вывод ISO может быть заменен. Момент временной метки может быть одинаковым, в то время как ее требуемое представление в сети может отличаться.

Сохраняйте сериализацию протокола в специальных адаптерах с приспособлениями, скопированными из авторитетных спецификаций. Используйте преобразование эпох, чтобы проверить основной момент, а затем отдельно проверьте грамматику. Это не позволяет правильному для календаря значению пройти проверку в синтаксически недопустимом конверте.

Выделенный адаптер также должен сохранять информацию о том, несет ли отсутствующее или неизвестное смещение значение предметной области. Сведение каждой текстовой даты к локальному предположению может уничтожить эту информацию.

Другие текстовые протоколы остаются вне конвертера.

Укажите узкий формат, который принимает ваш API, вместо того, чтобы полагаться на широкую метку. Для этого инструмента самым безопасным воспроизводимым выводом является строка UTC ISO, возвращаемая `toISOString()`, а самый безопасный числовой ввод включает явный контракт секунд или миллисекунд.

ToolAcre объединяет эти формы и сообщает предположения. Он не выносит решения по всем крайним случаям ISO 8601 или RFC 3339. Четкое владение грамматикой, обозначением единицы измерения и зоны — это то, что делает временные метки переносимыми, а не привязывание знакомого стандартного имени к недостаточно указанному полю.

Точный контракт позволяет клиентам рано выйти из строя, предоставляя полезные сообщения. Широкая метка приводит к разногласиям во время выполнения, где два правильных в других отношениях синтаксических анализатора могут выбирать разные подмножества.