resources: a resource description can declare which namespaces it mints

ResourceConfig gains a mints field: the identifier namespaces a resource
is the minting authority for, distinct from namespaces its schema merely
cross-references. Declared on ChEBI, HMDB, SwissLipids, LIPID MAPS, KEGG
and ChEMBL -- the resources whose own accessions anchor a chemical
identifier's key space.

KEGG mints kegg_compound and kegg_reaction but not pubchem_compound: its
conv/pubchem endpoint returns PubChem substance IDs, not compound IDs,
even though the ingestion schema still tags that cross-reference as
PUBCHEM_COMPOUND. The mints declaration states the intended authority
independently of that extraction bug, which a separate fix corrects.

Author: jannikfranken

pypath/inputs_v2/base.py

@@ -97,6 +97,12 @@ class ResourceConfig:
     short: str | None = None
     full: str | None = None
     synonyms: tuple[str, ...] = ()
+    # The identifier namespaces this resource is the minting authority for —
+    # not every namespace its schema tags data as. A resource can carry a
+    # cross-reference to a namespace it does not mint (KEGG cites PubChem
+    # identifiers). ChEBI is the one that mints `chebi`. Empty for a pure
+    # consumer, which is the default and the common case.
+    mints: tuple[IdentifierNamespaceCv, ...] = ()
 
     def names(self) -> 'ResourceNames':
         """Resolve this resource's (slug, short, full, synonyms).

pypath/inputs_v2/chebi.py

@@ -40,6 +40,7 @@
     pubmed='41312627',
     primary_category='small_molecules',
     annotation_ontologies=(OntologyCv.CHEBI,),
+    mints=(IdentifierNamespaceCv.CHEBI,),
     description=(
         'ChEBI is a manually curated database and ontology of small molecular '
         'entities. This inputs_v2 module emits searchable small-molecule '

pypath/inputs_v2/chembl.py

@@ -72,6 +72,7 @@ def _files_needed(version: int = VERSION, **_kwargs: object) -> list[str]:
     update_category=UpdateCategoryCV.REGULAR,
     pubmed='21948594',
     primary_category='interactions',
+    mints=(IdentifierNamespaceCv.CHEMBL_COMPOUND,),
     description=(
         "ChEMBL is a manually curated chemical database of bioactive molecules "
         "with drug-like properties."

pypath/inputs_v2/hmdb.py

@@ -46,6 +46,7 @@
     pubmed='34986597',
     primary_category='small_molecules',
     annotation_ontologies=(OntologyCv.CHEMONT,),
+    mints=(IdentifierNamespaceCv.HMDB,),
     description=(
         'The Human Metabolome Database (HMDB) is a comprehensive database '
         'containing detailed information about small molecule metabolites '

pypath/inputs_v2/kegg.py

@@ -124,6 +124,16 @@ def _kegg_organism_codes(
             'compound participants parsed from reaction equations and enriched '
             'with EC, Rhea, KO, RCLASS, ChEBI, and PubChem identifiers.'
         ),
+        # KEGG mints its own compound and reaction accessions. It cites
+        # PubChem identifiers via `conv/pubchem` but does not mint them.
+        # That endpoint returns PubChem substance IDs, not compound IDs, so
+        # `pubchem_compound` deliberately stays off this list. The schema
+        # below still tags the cross-reference as PUBCHEM_COMPOUND. A
+        # separate fix corrects that extraction, not this declaration.
+        mints=(
+            IdentifierNamespaceCv.KEGG_COMPOUND,
+            IdentifierNamespaceCv.KEGG_REACTION,
+        ),
     )
 
     f = FieldConfig(

pypath/inputs_v2/lipidmaps.py

@@ -36,6 +36,7 @@
     update_category=UpdateCategoryCV.REGULAR,
     pubmed='37855672',
     primary_category='lipids',
+    mints=(IdentifierNamespaceCv.LIPIDMAPS,),
     description=(
         'The LIPID MAPS Structure Database (LMSD) is a comprehensive database '
         'of lipid structures, annotations, and cross-references. It contains '

pypath/inputs_v2/swisslipids.py

@@ -40,6 +40,7 @@
     pubmed='25943471',
     primary_category='lipids',
     annotation_ontologies=(OntologyCv.SWISSLIPIDS,),
+    mints=(IdentifierNamespaceCv.SWISSLIPIDS,),
     description=(
         'SwissLipids is a curated resource providing a framework for the '
         'annotation of mass spectrometry data. It provides over 750,000 lipid '

tests/test_resource_config.py

@@ -0,0 +1,67 @@
+"""Tests for the ``mints`` declaration on ``ResourceConfig``.
+
+A resource description states which identifier namespaces it is the minting
+authority for. The authority relation (``identifier_authority`` in
+omnipath-build) is populated from this declaration, not inferred from what a
+resource's schema happens to tag data as — a resource can carry cross-
+references to a namespace without minting it.
+"""
+
+from __future__ import annotations
+
+from pypath.inputs_v2.base import ResourceConfig
+from pypath.internals.cv_terms import (
+    IdentifierNamespaceCv,
+    LicenseCV,
+    ResourceCv,
+    UpdateCategoryCV,
+)
+
+
+def _config(**overrides) -> ResourceConfig:
+    defaults = dict(
+        id=ResourceCv.CHEBI,
+        name='Test Resource',
+        url='https://example.org',
+        license=LicenseCV.CC_BY_4_0,
+        update_category=UpdateCategoryCV.REGULAR,
+        description='A resource used only to exercise the mints field.',
+    )
+    defaults.update(overrides)
+    return ResourceConfig(**defaults)
+
+
+def test_mints_defaults_to_empty():
+    """A resource that declares nothing mints nothing — a pure consumer."""
+    config = _config()
+    assert config.mints == ()
+
+
+def test_mints_declares_the_namespaces_a_resource_is_authoritative_for():
+    config = _config(mints=(IdentifierNamespaceCv.CHEBI,))
+    assert config.mints == (IdentifierNamespaceCv.CHEBI,)
+
+
+def test_mints_holds_more_than_one_namespace():
+    config = _config(
+        mints=(
+            IdentifierNamespaceCv.KEGG_COMPOUND,
+            IdentifierNamespaceCv.KEGG_REACTION,
+        ),
+    )
+    assert IdentifierNamespaceCv.KEGG_COMPOUND in config.mints
+    assert IdentifierNamespaceCv.KEGG_REACTION in config.mints
+
+
+def test_mints_does_not_claim_a_namespace_a_resource_only_cites():
+    """The regression this field exists to catch: KEGG cites PubChem
+
+    identifiers it does not mint. Declaring ``mints`` explicitly is what lets
+    the build tell "this resource is the authority" apart from "this resource
+    also carries a cross-reference".
+    """
+    kegg = _config(
+        id=ResourceCv.KEGG_METABOLIC,
+        mints=(IdentifierNamespaceCv.KEGG_COMPOUND,),
+    )
+    assert IdentifierNamespaceCv.PUBCHEM_COMPOUND not in kegg.mints