Merge Schema sections with their corresponding entries in Specifications

jaimergp · jaimergp · commit bac156302fc4 · 2026-02-06T01:19:59.000+01:00
diff --git a/peps/pep-0804.rst b/peps/pep-0804.rst
@@ -222,149 +222,8 @@ canonical, or which versioning scheme applies to virtual DepURLs (see Appendix
 B). The corresponding answers are not given in this PEP; instead we delegate
 that responsibility to the central registry maintainers.
 
-Mappings
---------
-
-The mappings specify which ecosystem-specific identifiers provide the canonical
-entries available in the central registry. A mapping mainly consists of a list
-of dictionaries, in which each entry consists of:
-
-- an ``id`` field with the canonical DepURL.
-
-- an optional free form ``description`` text.
-
-- a ``specs`` field whose value MUST be one of:
-
-  - a dictionary with three keys (``build``, ``host``, ``run``). The values
-    MUST be a string or list of strings representing the ecosystem-specific package
-    identifiers as needed as build-, host- and runtime dependencies (see :pep:`725` for
-    details on these definitions).
-
-  - for convenience, a string or a list of strings are also accepted as a
-    shorthand form. In this case, the identifier(s) will be used to populate
-    the three categories mentioned in the item above.
-
-  - an empty list, which is understood as the ecosystem not having packages to
-    provide such dependency.
-
-- a ``specs_from`` field whose value is a DepURL from which the ``specs``
-  field will be imported. Either ``specs`` or ``specs_from`` MUST be present.
-
-- an optional ``urls`` field whose value MUST be a URL, a list of URLs, or a
-  dictionary that maps a non-empty string to a URL. This is useful to link to external
-  resources that provide more information about the mapped packages.
-
-The mappings MUST also specify another section ``package_managers``, reporting
-which package managers are available in the ecosystem and how to use them. This field MUST
-take an empty list or a list of dictionaries, with each of them reporting the following fields:
-
-- ``name`` (string), unique identifier for this package manager. Usually, the executable name.
-
-- ``commands`` (list of dictionaries), the commands to run to install the mapped package(s) and
-  check whether they are already installed. Two types of commands are proposed:
-
-  - ``install``, to generate install instructions. The exit code MUST be ``0`` on success.
-
-  - ``query``, to check whether a given package is already installed. If the package is
-    installed, the command MUST result in an exit code of ``0``. Otherwise, a non-zero exit code
-    MUST be returned.
-
-- ``specifier_syntax``: instructions on how to map a subset of PEP 440 specifiers (as determined
-  in PEP 725)to the target package manager. Three levels of support are offered: name-only,
-  exact-version-only, and version-range compatibility (with per-operator translations).
-
-Each mapping MUST have a canonical URL for online retrieval, with the
-filename following the rules described in the section below. These
-mappings MAY also be packaged for offline distribution in each platform. The authors
-recommend placing them in the standard location for data artifacts in each operating
-system; e.g. ``$XDG_DATA_DIRS`` on Linux and others, ``~/Library/Application Support`` on
-macOS, and ``%LOCALAPPDATA%`` for Windows. The subdirectory identifier MUST
-be ``external-packaging-metadata-mappings``. This data directory SHOULD only
-contain mapping documents named ``{ecosystem-identifier}.mapping.json`` (see section below
-for details on the construction of ecosystem identifiers). The central
-registry and known ecosystem documents MAY also be distributed in this directory,
-as ``registry.json`` and ``known-ecosystems.json``, respectively.
-
-.. note::
-
-  The ``specifier_syntax`` mappings are meant to provide interoperability between
-  ecosystems where choosing which package version to install is possible. For
-  example, this is not the case in many Linux distributions, where each distro
-  release commits to a package version during its lifecycle (although often
-  with the necessary security backports).
-
-  In these cases, the ``install`` command could be used, optimistically, in
-  "name-only" mode, hoping that the OS-provided version is a good fit. A more
-  pessimistic alternative would be to use the ``query`` command first to see if
-  the available version matches the project constraints, and then install the
-  package by name.
-
-  Even in those cases, perfect 1:1 version matching is not always possible due to how
-  different ecosystems map upstream releases to repackaged versions (e.g. the epoch
-  had to be bumped to accommodate a change of release schema). In that regard, we do
-  not encode explicit mapping semantics for epochs or pre-releases.
-
-
-Known ecosystems
-----------------
-
-The list of known ecosystems has two roles:
-
-1. Reporting the canonical URL for its mapping.
-2. Assigning a unique, short identifier to each ecosystem.
-
-Ecosystem identifiers
-^^^^^^^^^^^^^^^^^^^^^
-
-The identifier MUST conform to this regex: ``[a-z0-9\-_.]+(\+[a-z0-9\-_.])?``.
-In other words, a first field optionally followed by a second, separated
-by a ``+`` symbol.
-
-For ecosystems corresponding to Linux distributions,
-the first field MUST correspond to the ``ID`` string as specified in the
-`os-release <https://www.freedesktop.org/software/systemd/man/latest/os-release.html>`__
-specification. If provided, the second field MUST correspond to the
-``VERSION_ID`` string if relevant.
-
-Since the version field is optional, tools SHOULD try to access the versioned
-identifier but fallback to the name-only identifier if not found.
-
-The complete filename MUST be ``{identifier}.mapping.json``.
-
-Some examples:
-
-.. list-table::
-    :header-rows: 1
-
-    * - Ecosystem
-      - Identifier
-      - Filename
-    * - Debian Bookworm
-      - ``debian+12``
-      - ``debian+12.mapping.json``
-    * - Fedora 40
-      - ``fedora+40``
-      - ``fedora+40.mapping.json``
-    * - Ubuntu 24.04
-      - ``ubuntu+24.04``
-      - ``ubuntu+24.04.mapping.json``
-    * - Arch Linux (rolling)
-      - ``arch``
-      - ``arch.mapping.json``
-    * - Homebrew
-      - ``homebrew``
-      - ``homebrew.mapping.json``
-    * - conda-forge
-      - ``conda-forge``
-      - ``conda-forge.mapping.json``
-
-Schema details
---------------
-
-Three JSON Schema documents are provided to fully standardize the registries and mappings.
-
-Central registry schema
-^^^^^^^^^^^^^^^^^^^^^^^
+Schema
+^^^^^^
 
 The central registry is specified by the following
 `JSON schema <https://github.com/jaimergp/external-metadata-mappings/blob/main/schemas/central-registry.schema.json>`__:
@@ -432,8 +291,61 @@ Each entry in this list is defined as:
       - ``AnyUrl | list[AnyUrl] | dict[NonEmptyString, AnyUrl]``
       - Hyperlinks to web locations that provide more information about the definition.
 
-Known ecosystems schema
-^^^^^^^^^^^^^^^^^^^^^^^
+Known ecosystems
+----------------
+
+The list of known ecosystems has two roles:
+
+1. Reporting the canonical URL for its mapping.
+2. Assigning a unique, short identifier to each ecosystem.
+
+Ecosystem identifiers
+^^^^^^^^^^^^^^^^^^^^^
+
+The identifier MUST conform to this regex: ``[a-z0-9\-_.]+(\+[a-z0-9\-_.])?``.
+In other words, a first field optionally followed by a second, separated
+by a ``+`` symbol.
+
+For ecosystems corresponding to Linux distributions,
+the first field MUST correspond to the ``ID`` string as specified in the
+`os-release <https://www.freedesktop.org/software/systemd/man/latest/os-release.html>`__
+specification. If provided, the second field MUST correspond to the
+``VERSION_ID`` string if relevant.
+
+Since the version field is optional, tools SHOULD try to access the versioned
+identifier but fallback to the name-only identifier if not found.
+
+The complete filename MUST be ``{identifier}.mapping.json``.
+
+Some examples:
+
+.. list-table::
+    :header-rows: 1
+
+    * - Ecosystem
+      - Identifier
+      - Filename
+    * - Debian Bookworm
+      - ``debian+12``
+      - ``debian+12.mapping.json``
+    * - Fedora 40
+      - ``fedora+40``
+      - ``fedora+40.mapping.json``
+    * - Ubuntu 24.04
+      - ``ubuntu+24.04``
+      - ``ubuntu+24.04.mapping.json``
+    * - Arch Linux (rolling)
+      - ``arch``
+      - ``arch.mapping.json``
+    * - Homebrew
+      - ``homebrew``
+      - ``homebrew.mapping.json``
+    * - conda-forge
+      - ``conda-forge``
+      - ``conda-forge.mapping.json``
+
+Schema
+^^^^^^
 
 The known ecosystems list is specified by the following
 `JSON Schema <https://github.com/jaimergp/external-metadata-mappings/blob/main/schemas/known-ecosystems.schema.json>`__:
@@ -496,8 +408,90 @@ to a sub-dictionary defined as:
       - URL to the mapping for this ecosystem
       - True
 
-Mappings schema
-^^^^^^^^^^^^^^^
+Mappings
+--------
+
+The mappings specify which ecosystem-specific identifiers provide the canonical
+entries available in the central registry. A mapping mainly consists of a list
+of dictionaries, in which each entry consists of:
+
+- an ``id`` field with the canonical DepURL.
+
+- an optional free form ``description`` text.
+
+- a ``specs`` field whose value MUST be one of:
+
+  - a dictionary with three keys (``build``, ``host``, ``run``). The values
+    MUST be a string or list of strings representing the ecosystem-specific package
+    identifiers as needed as build-, host- and runtime dependencies (see :pep:`725` for
+    details on these definitions).
+
+  - for convenience, a string or a list of strings are also accepted as a
+    shorthand form. In this case, the identifier(s) will be used to populate
+    the three categories mentioned in the item above.
+
+  - an empty list, which is understood as the ecosystem not having packages to
+    provide such dependency.
+
+- a ``specs_from`` field whose value is a DepURL from which the ``specs``
+  field will be imported. Either ``specs`` or ``specs_from`` MUST be present.
+
+- an optional ``urls`` field whose value MUST be a URL, a list of URLs, or a
+  dictionary that maps a non-empty string to a URL. This is useful to link to external
+  resources that provide more information about the mapped packages.
+
+The mappings MUST also specify another section ``package_managers``, reporting
+which package managers are available in the ecosystem and how to use them. This field MUST
+take an empty list or a list of dictionaries, with each of them reporting the following fields:
+
+- ``name`` (string), unique identifier for this package manager. Usually, the executable name.
+
+- ``commands`` (list of dictionaries), the commands to run to install the mapped package(s) and
+  check whether they are already installed. Two types of commands are proposed:
+
+  - ``install``, to generate install instructions. The exit code MUST be ``0`` on success.
+
+  - ``query``, to check whether a given package is already installed. If the package is
+    installed, the command MUST result in an exit code of ``0``. Otherwise, a non-zero exit code
+    MUST be returned.
+
+- ``specifier_syntax``: instructions on how to map a subset of PEP 440 specifiers (as determined
+  in PEP 725)to the target package manager. Three levels of support are offered: name-only,
+  exact-version-only, and version-range compatibility (with per-operator translations).
+
+Each mapping MUST have a canonical URL for online retrieval, with the
+filename following the rules described in the section below. These
+mappings MAY also be packaged for offline distribution in each platform. The authors
+recommend placing them in the standard location for data artifacts in each operating
+system; e.g. ``$XDG_DATA_DIRS`` on Linux and others, ``~/Library/Application Support`` on
+macOS, and ``%LOCALAPPDATA%`` for Windows. The subdirectory identifier MUST
+be ``external-packaging-metadata-mappings``. This data directory SHOULD only
+contain mapping documents named ``{ecosystem-identifier}.mapping.json`` (see section below
+for details on the construction of ecosystem identifiers). The central
+registry and known ecosystem documents MAY also be distributed in this directory,
+as ``registry.json`` and ``known-ecosystems.json``, respectively.
+
+.. note::
+
+  The ``specifier_syntax`` mappings are meant to provide interoperability between
+  ecosystems where choosing which package version to install is possible. For
+  example, this is not the case in many Linux distributions, where each distro
+  release commits to a package version during its lifecycle (although often
+  with the necessary security backports).
+
+  In these cases, the ``install`` command could be used, optimistically, in
+  "name-only" mode, hoping that the OS-provided version is a good fit. A more
+  pessimistic alternative would be to use the ``query`` command first to see if
+  the available version matches the project constraints, and then install the
+  package by name.
+
+  Even in those cases, perfect 1:1 version matching is not always possible due to how
+  different ecosystems map upstream releases to repackaged versions (e.g. the epoch
+  had to be bumped to accommodate a change of release schema). In that regard, we do
+  not encode explicit mapping semantics for epochs or pre-releases.
+
+Schema
+^^^^^^
 
 The mappings are specified by the following
 `JSON Schema <https://github.com/jaimergp/external-metadata-mappings/blob/main/schemas/external-mapping.schema.json>`__:
