@@ -159,6 +159,7 @@ these steps:
159159#. Complete the upload session, publishing or discarding the stage.
160160#. Optionally check the status of an upload session.
161161
162+ .. _versioning :
162163
163164Versioning
164165----------
@@ -759,26 +760,42 @@ interpretation to aid in diagnosing underlying issue.
759760File Upload Mechanisms
760761----------------------
761762
762- File Upload Mechanisms, with the exception of ``http-post-application-octet-stream `` are left as an
763- implementation detail specific to each server. Servers **MUST ** implement a
764- ``http-post-application-octet-stream `` mechanism. This serves as a fallback if no server specific implementations
765- exist.
763+ Servers **MUST ** implement :ref: `required file upload mechansisms <required-file-upload-mechanisms >`.
764+ Such mechanisms serve as a fallback if no server specific implementations exist.
766765
767- A given server may implement an arbitrary number of mechanisms and is responsible for documenting
768- their usage. Implemenatations **SHOULD ** be prefixed with a string that clearly identifies the
769- server and is unique from other well known servers or implementations.
766+ Each major version of the Upload API **MUST ** specify at least one required File Upload Mechanism.
770767
771- If a server intendes to match the behavior of another server's implementation, it **MAY ** respond
768+ New required mechanisms **MUST NOT ** be added and existing required mechanisms **MUST NOT ** be removed
769+ without an update to the :ref: `major version <versioning >`.
770+
771+ A given server **MAY ** implement an arbitrary number of server specific mechanisms
772+ and is responsible for documenting their usage.
773+ Server specific implementations **MUST ** be prefixed with ``vnd- ``
774+ and **SHOULD ** further contain a string that clearly identifies the server operator
775+ and is unique from other well known servers or implementations.
776+
777+ For example:
778+
779+ ====================================== ================ ========================================================
780+ File Upload Mechanism string Server Operator Mechanism description
781+ ====================================== ================ ========================================================
782+ ``vnd-pypi-s3multipart-presigned `` PyPI S3 multipart upload via pre-signed URL
783+ ``vnd-pypi-fetch `` PyPI File delivered by instructing server to fetch from a URL
784+ ``vnd-acmecorp-fetch `` Acme Corp File delivered by instructing server to fetch from a URL
785+ ``vnd-acmecorp-postal `` Acme Corp File delivered via postal mail
786+ ``vnd-madscience-quantumentanglement `` Mad Science Labs Upload via quantum entanglement
787+ ====================================== ================ ========================================================
788+
789+ If a server intends to match the behavior of another server's implementation, it **MAY ** respond
772790with that implementation's file upload mechanism name.
773791
774- All implementations of this PEP **MUST ** implement the ``http-post-application-octet-stream `` file
775- upload mechanism.
792+ .. _required-file-upload-mechanisms :
776793
777- `` http-post-application-octet-stream `` Mechanism
778- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
794+ Required File Upload Mechanisms
795+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
779796
780- The ``http-post-application-octet-stream `` mechansism ** MUST ** be supported servers which
781- implement this PEP.
797+ ``http-post-application-octet-stream ``
798+ ++++++++++++++++++++++++++++++++++++++
782799
783800A client executes this mechanism by submitting a ``POST `` request to the ``file_url `` returned in the
784801``http-post-application-octet-stream `` map of the ``mechanism `` map of the
0 commit comments