ISO 8601 vs RFC 3339: API 応答の背後にある 2 つの日付形式

有効な ISO 8601 を拒否する 'ISO 8601' フィールド — RFC 3339 を期待する API に送信される週の日付または精度を下げた値

「ISO 8601」と何気なく記述されている API フィールドは、日付/時刻形式を 1 つだけ受け入れることができます。別の標準に準拠した表現を送信しても、パーサーは失敗する可能性があります。解決策は、傘の名前から議論しないことです。それは、例と検証テストを使用して正確なワイヤー文法を文書化することです。

ToolAcre は、`Date.toISOString()` からの安定した標準出力を提供しますが、すべての表現に対する適合性スイートではありません。生成された文字列を 1 つの有用な交換フォームとして扱い、それを実際に所有する API コントラクトと比較します。

したがって、スキーマは、パーサーを正確に反映している場合にのみ、正規表現または形式型を公開する必要があります。例だけでも役に立ちますが、明示的な拒否の場合は曖昧さを解消します。

幅広い日付の標準と狭い API 文法は互換性がありません

生成されたフォームには、カレンダーの日付、`T`、ミリ秒までの時間、および末尾の Z が含まれます。実装では、これを UI で ISO 8601 (UTC) と呼びます。入力は、明示的なオフセットやローカル ピッカーのゾーンレス日時形状など、JavaScript Date が読み取るものを受け入れます。

その動作は、完全な標準パーサーよりもはるかに範囲が狭いです。週の日付、間隔、期間、および精度の低下には、リポジトリ テストがありません。したがって、あるブラウザで受け入れられる文字列 Date は言語間で保証されず、拒否された特殊なフォームが他の場所での立場を反証することはありません。

出力の固定ミリ秒精度は書式設定の選択であり、ソースがミリ秒を測定したという証拠ではありません。 Date が整数秒の値を受け取った場合でも、`.000` が出力される可能性があります。

ToolAcre は 1 つの 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 の整数または単位の曖昧さを避けるために、1 つの正規文字列を選択します。

API が両方を保持する場合は、どのフィールドが権限があるかを定義し、合意をテストします。新しいエポックの横にある古いフォーマットされた文字列は、どちらか一方を単独で使用するよりも悪影響を及ぼします。 ToolAcre は整数を変換し、生成された ISO 値をチェックすることでペアを比較できますが、一貫性の強制はプロデューサーに属します。

動作例: 1 つのインスタント、4 つの表現 — エポック秒、エポックミリ秒、UTC の RFC 3339 文字列、およびローカル オフセットを含む 1 つ

インスタント `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 出力、および日付解析された数値オフセット文字列の 4 つのリポジトリ検証可能な表現です。この例では、すべての外部パーサーが同じ小数精度またはオフセット構文を受け入れるとは主張しません。出荷前に API 独自の検証を実行します。

書き込まれたクロックから +02:00 オフセットを減算すると、10:22 UTC が得られます。完全な標準文法を一般化することなく、この特定の入力をテストするには、この単純な等価性で十分です。

動作例: このリポジトリが検証できる 4 つのフォームのうちの 1 つのインスタント

HTTP ヘッダーと電子メールの日付では、ここでは実装されていないテキストの契約が使用されます。 ToolAcre はこれらのプロトコルをフォーマットしません。また、ISO 出力を置き換えることも保証しません。タイムスタンプの瞬間は同じであっても、必要なワイヤ表現は異なります。

権威ある仕様からコピーされたフィクスチャを使用して、専用アダプタでプロトコルのシリアル化を維持します。エポック変換を使用して基礎となるインスタントを検証し、文法を個別にテストします。これにより、カレンダーに正しい値が構文的に無効なエンベロープでレビューに合格することがなくなります。

専用アダプターは、欠落しているオフセットまたは不明なオフセットがドメインの意味を持っているかどうかも保持する必要があります。すべてのテキスト日付をローカルな仮定に平坦化すると、その情報が破壊される可能性があります。

他のテキスト プロトコルはコンバーターの外部に残ります

幅広いラベルに依存するのではなく、API が受け入れる狭い形式を指定します。このツールの場合、最も安全な再現可能な出力は `toISOString()` によって返される UTC ISO 文字列であり、最も安全な数値入力には明示的な秒またはミリ秒の契約が含まれます。

ToolAcre は、これらのフォームとレポートの前提条件を橋渡しします。すべての ISO 8601 または RFC 3339 のエッジ ケースを判断するものではありません。文法、単位、およびゾーン指定子の明確な所有権により、タイムスタンプを移植可能にすることができます。不明確なフィールドに使い慣れた標準名を付ける必要はありません。

正確なコントラクトにより、クライアントは有益なメッセージで早期に失敗することができます。ラベルが広いと、不一致がランタイムに押し込まれ、そうでなければ正しい 2 つのパーサーが異なるサブセットを選択する可能性があります。