valid-for -> expires-at

Author: ewdurbin

peps/pep-0694.rst

@@ -350,7 +350,7 @@ The successful response includes the following content:
       },
       "mechanisms": ["http-post-bytes"],
       "session-token": "<token-string>",
-      "valid-for": 604800,
+      "expires-at": "2025-08-01T12:00:00Z",
       "status": "pending",
       "files": {},
       "notices": [
@@ -376,16 +376,14 @@ the following keys:
     that can be provided to installers in order to preview the staged release before it's published.
     If the index does *not* support stage previewing, this key **MUST** be omitted.
 
-``valid-for``
-    An integer representing how long, in seconds, until the server itself will expire this session,
+``expires-at``
+    An ISO8601 formatted timestamp string representing when the server will expire this session,
     and thus all of its content, including any uploaded files and the URL links related to the
-    session. This value is roughly relative to the time at which the session was created or
-    :ref:`extended <session-extension>`.  The session **SHOULD** live at least this much longer
+    session. The session **SHOULD** remain active until at least this time
     unless the client itself has canceled or published the session. Servers **MAY** choose to
-    *increase* this time, but should never *decrease* it, except naturally through the passage of
-    time.
+    extend this expiration time, but should never move it earlier.
     Clients can query the :ref:`session status <session-status>`
-    to get time remaining in the session.
+    to get the current expiration time of the session.
 
 ``status``
     A string that contains one of ``pending``, ``published``, ``error``, or ``canceled``,
@@ -664,7 +662,7 @@ The successful response includes the following:
         "file-upload-session": "..."
       },
       "status": "pending",
-      "valid-for": 3600,
+      "expires-at": "2025-08-01T13:00:00Z",
       "mechanism": {
         "identifier": "http-post-bytes",
         "file_url": "...",
@@ -682,6 +680,16 @@ the following keys:
     A dictionary mapping :ref:`keys to URLs <file-upload-session-links>` related to this session,
     the details of which are provided below.
 
+``status``
+    A string with valid values ``pending``, ``processing``, ``complete``, ``error``, and ``canceled``
+    indicating the current state of the File Upload Session.
+
+``expires-at``
+    An ISO8601 formatted timestamp string representing when the server will expire this File Upload Session.
+    The session **SHOULD** remain active until at least this time
+    unless the client cancels or completes it. Servers **MAY** choose to
+    extend this expiration time, but should never move it earlier.
+
 ``mechanism``
     A mapping containing the necessary details for the supported mechanism
     as negotiated by the client and server.
@@ -794,7 +802,7 @@ The server will respond to this ``GET`` request with the same
 :ref:`Publishing Session creation response body <publishing-session-response>`
 or :ref:`File Upload Session creation response body <file-upload-session-response>`,
 that they got when they initially created the Publishing Session or File Upload Session,
-except with any changes to ``status``, ``valid-for``, or ``files`` reflected.
+except with any changes to ``status``, ``expires-at``, or ``files`` reflected.
 
 
 .. _session-extension:
@@ -829,11 +837,11 @@ will respond with the same
 :ref:`Publishing Session creation response body <publishing-session-response>`
 or :ref:`File Upload Session creation response body <file-upload-session-response>`,
 that they got when they initially created the Publishing Session or File Upload Session,
-except with any changes to ``status``, ``valid-for``, or ``files`` reflected.
+except with any changes to ``status``, ``expires-at``, or ``files`` reflected.
 
 If the server refuses to extend the session for the requested number of seconds, it still returns a
-success response, and the ``valid-for`` key will simply include the number of seconds remaining in
-the current session.
+success response, and the ``expires-at`` key will simply reflect the current expiration time of
+the session.
 
 .. _staged-preview: