Define index-specific-metadata

Author: warsaw

peps/pep-0694.rst

@@ -334,7 +334,8 @@ The request includes the following top-level keys:
 
 ``meta`` (**required**)
     Describes information about the payload itself.  Currently, the only defined sub-key is
-    ``api-version`` the value of which must be the string ``"2.0"``.
+    ``api-version`` the value of which must be the string ``"2.0"``.  Optional sub-keys can define
+    :ref:`index-specific behavior <index-specific-metadata>`.
 
 ``name`` (**required**)
     The name of the project that this session is attempting to release a new version of.  The name
@@ -363,6 +364,34 @@ The session is owned by the user that created it,
 and all subsequent requests **MUST** be performed with the same credentials,
 otherwise a ``403 Forbidden`` will be returned on those subsequent requests.
 
+.. _index-specific-metadata:
+
+Optional Index-specific Metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Index can optionally define their own metadata for index-specific behavior.  The metadata key
+**MUST** begin with an underscore, with the following value easily and uniquely identifying the
+index.  For example, PyPI could allow for projects to be created in an `organization account
+<https://docs.pypi.org/organization-accounts/>`__ of which the publisher is a member by using the
+following index-specific metadata section:
+
+.. code-block:: json
+
+    {
+      "meta": {
+        "api-version": "2.0",
+        "_pypi.org": {
+            "organization": "my-main-org"
+        }
+      },
+      "name": "foo",
+      "version": "1.0",
+    }
+
+This is only an example.  This PEP does not define or reserve any index-specific keys or metadata;
+that is left up to the index to specify and document.  The semantics (e.g. whether bogus keys or
+values result in an error or are ignored) of the index-specific metadata is also undefined here.
+
 .. _publishing-session-response:
 
 Response Body
@@ -1018,9 +1047,9 @@ To do this, :ref:`create a new publishing session <publishing-session-create>`,
 JSON body of the create session request, you can simply use a placeholder version number such as
 ``"0.0.0a0"``.  The version is ignored if no artifacts are uploaded.
 
-TBD: org is ignored if it's not a new project registration.
-
-The user that created the session will become the owner of the new project.
+Generally the user that created the session will become the owner of the new project, however the
+index could define :ref:`index-specific metadata <index-specific-metadata>` to, for example, allow
+an organization of which the publisher is a member, to own the new project.
 
 
 Open Questions