Add package self-identification as a third registration axis for PURL types

[ppkarwasz]

Each PURL type definition (types/<type>.json, ECMA-427 Clause 6) currently documents two characteristics of a type:

1. Identification — the namespace/name/version definitions and qualifiers list: how a purl of this type is structured.
2. Resolution (optional) — the repository object: how a purl of this type can be resolved to a location to retrieve the package.

Proposal

Add a third, optional characteristic: self-identification — whether, and how, a package of this type can declare its own purl inside its native metadata/manifest, so the purl can be recovered directly from the artifact without external registry or build-time context.

It matters increasingly for supply-chain tooling — SLSA provenance, VEX, and SBOMs all use PURL as a subject identifier, but nothing today lets a verifier check "does the artifact agree with what the attestation claims it is?" directly against the artifact itself.

Concretely, this would be a new self_identification object in the type JSON Schema, structured like the existing repository object:

"self_identification": {
  "type": "object",
  "properties": {
    "supported": {
      "type": "boolean",
      "description": "Whether this type has a documented convention for a package to declare its own purl in its native metadata."
    },
    "documentation": {
      "type": "array",
      "items": { "type": "string", "format": "uri" },
      "description": "Official or semi-official documentation of the manifest format referenced above (mirrors the documentation field proposed for repository in #<link>)."
    },
    "note": { "type": "string" }
  }
}

Two examples to establish this is workable, not exhaustive — full ecosystem coverage is explicitly out of scope for this issue (see below):

• maven: META-INF/MANIFEST.MF already tolerates arbitrary headers, so a Purl: header fits the same slot as Implementation-Version.
• npm: package.json tolerates unknown top-level keys, so a bare "purl" key fits alongside name/version.

Not every type will have an equally natural fit — some have closed schemas that need a nested extension point (Cargo's [package.metadata]), and some have no natural fit at all (golang, where the module path already serves as the identifier). That variation is exactly why per-type population belongs in separate issues rather than this one.

Scope of this issue

This issue is only about introducing the axis and its schema shape. Once (if) that's agreed, populating self_identification for each registered type — deciding manifest/field/documentation per ecosystem, which in
several cases will involve real debate (see the closed-schema and reserved-namespace cases above) — should happen as separate, per-type issues so each can be reviewed on its own merits rather than as one large PR.

[ppkarwasz]

This is a draft list of how a Purl metadata field could be introduced in each ecosystem:

Convention only — the native format already tolerates a custom field or has a sanctioned extension point, so this is purely a documentation exercise:

• maven — META-INF/MANIFEST.MF already tolerates arbitrary headers (Implementation-Version etc.); add a Purl: header.
• npm — package.json tolerates unknown top-level keys; add "purl".
• gem — .gemspec's metadata hash is the sanctioned extension point; spec.metadata['purl'].
• composer — composer.json's "extra" object is the sanctioned extension point.
• cargo — Cargo.toml's [package] table is closed, but [package.metadata] already exists as the sanctioned extension namespace.
• nuget — .nuspec supports <metadata> extension elements.
• conan — conandata.yml is free-form YAML.
• deb — debian/control supports X--prefixed fields by RFC822 convention; X-Purl:.
• rpm — .spec supports vendor-defined tags.
• cocoapods — .podspec is executable Ruby; arbitrary attributes settable, same shape as gemspec.
• conda — meta.yaml's extra section is the existing convention for non-standard fields.
• hex — mix.exs's project/0 keyword list is open; add purl:.
• cpan — CPAN::Meta::Spec (META.json/META.yml) explicitly reserves x_/X_-prefixed keys for private/custom use; x_purl.
• cran — R's DESCRIPTION file has an established Config/ field namespace (documented in Writing R Extensions) for exactly this kind of tool-specific custom data; Config/purl.
• luarocks — rockspec is a Lua table; open, but I haven't verified an established custom-field convention — worth confirming in the per-type issue rather than assuming.
• mlflow — the MLmodel YAML file appears free-form; needs a closer look at what MLflow itself tolerates before committing to a field name.
• huggingface — README.md YAML frontmatter (model/dataset card metadata) is generally free-form; same caveat as mlflow.
• swid — ISO/IEC 19770-2 XML tags support vendor-namespaced extension attributes; worth noting this one is almost recursive, since a SWID tag is a software-identification artifact already — embedding a purl here is arguably the most natural fit of any type.
• pub — pubspec.yaml appears tolerant of extra top-level keys; needs verification against pub tooling behavior.
• alpm — .PKGINFO is key:value; likely tolerant like deb/rpm, but I haven't confirmed libalpm doesn't warn on unknown keys.
• apk — same caveat as alpm.

Requires more than documentation — a closed/versioned schema, a reserved namespace controlled elsewhere, or no real artifact-level manifest at all:

• pypi — wheel/sdist Core Metadata is a closed, versioned field set governed by PyPA; adding a field needs a PEP-equivalent through the Python packaging governance process, not just a purl-spec decision.
• oci — org.opencontainers.image.* is a namespace reserved by the OCI Image Spec; getting org.opencontainers.image.purl recognized needs OCI's own buy-in. A neutral fallback (dev.packageurl.purl) is possible without that, but it's a weaker outcome than an official annotation.
• docker — same reserved-namespace issue as oci, since Docker images are OCI images in practice today.
• golang — go.mod is a closed, toolchain-parsed grammar with no extension mechanism, and the module path already serves as the purl-equivalent identifier. This type may just not be a good fit for the axis at all.
• swift — Package.swift is executable Swift, evaluated by the compiler rather than parsed as data; there's no established convention for embedding non-code metadata like this, so it'd need real design work, not just a doc change.
• github — identifies a VCS ref (commit/tag), not a packaged artifact; there's no artifact-level manifest for this axis to apply to.
• bitbucket — same as github.
• generic — deliberately ecosystem-agnostic by design; there's no native manifest format to standardize against.
• bitnami — I couldn't confirm what native manifest, if any, this type's artifacts carry; needs investigation before it can be scoped either way.
• qpkg — same as bitnami — needs investigation first.