Proposed pkg:service specification

[VanL]

PURL service type proposal

Overview

Package URLs are widely used as the stable identity for catalog, dependency,
and inventory referents. The standard PURL types cover software package
ecosystems, but one increasingly important class of software is not addressed:
software provided as a service, where there is no distributable artifact and no
authoritative package registry — only a hosted product reached through an API.

This proposal defines a PURL type, pkg:service, for that class. It is written
to be compatible with ECMA-427 PURL syntax and precise enough to discuss with
the Package URL working group.

Motivation (why now). CycloneDX 2.0 retires the separate services[] array
and represents everything as a component; components carry a purl, where the
former service object did not. That change creates a concrete consumer for a
service-shaped PURL: a hosted service becomes a component that needs an
identifier, and no existing registry type fits one. pkg:service fills that gap.

Design principles

Three principles govern every decision below. The per-decision rationale notes
refer back to them.

1. Location is not identity. A PURL identifies what a thing is, not where
   it is reached. This is why PURL has no URL authority component, and it is the
   basis for excluding endpoints, hosts, and regions from identity (see
   ECMA-427; purl-spec #127).
2. Identity is constructible from observables (a Schelling point). Two
   independent producers who both know the schema, and who observe the same
   thing, shall mint the same PURL — and a holder of the PURL can locate the
   thing. Every naming rule is chosen so that convergence does not depend on a
   central registry or private knowledge.
3. A service is deployment-only. Unlike a package, a service has no artifact
   distinct from its delivery. "The product" and "the vendor's native delivery
   of the product" are therefore the same referent.

Relationship to ECMA-427

ECMA-427 defines the seven-component form:

scheme:type/namespace/name@version?qualifiers#subpath

For this type:

• scheme is always pkg.
• type is service.
• namespace, name, version, and qualifiers keep their ECMA-427 roles.
• There is no URL authority. Host-like strings in namespace are owner
  namespaces, not URL hosts.
• subpath is not used.

Verbal forms

This document uses the verbal forms of the ISO/IEC/Ecma drafting conventions:
"shall" and "shall not" state requirements, "should" and "should not" state
recommendations, and "may" states permission. "can" and "cannot" state
possibility or capability. The keywords are not capitalized, and "must" is not
used as a normative term.

Scope and type selection

Use a standard ecosystem type when one exists. Types such as pypi, npm,
maven, docker, oci, github, and huggingface are preferred over
service whenever the referent is actually distributed through those
ecosystems. For an open-weight model, prefer pkg:huggingface.

Use pkg:service only when the missing concept is the package ecosystem itself:
the referent is a hosted product, model API, managed service, commercial
platform, provider-defined resource class, or a specific provider-native
resource instance, and no authoritative package registry should own its identity.

Identity model

The root service/product identity is composed from three things and nothing
else:

identity = vendor namespace + canonical product name (+ responsible intermediary, when distinct)

More specific identities may narrow that root with resource_type and
native_id as described in Identity levels.

• The delivery URL is never part of identity. Multiple endpoints of the same
  product — regional hosts, load-balanced hosts, API versions serving the same
  product — are the same identity.
• A distinct responsible intermediary forks identity. The same model reached
  through a different vendor or aggregation provider (such as OpenRouter, AWS,
  or Azure) is a different referent: different terms, availability, and
  frequently different served bits.

Rationale (P1, P2). Responsible entity forks, transport does not. The
discriminator is which named vendor or intermediary you contract with —
observable at procurement — not "are the served bits identical," which a
producer usually cannot inspect. Keying on the responsible entity keeps the
identifier constructible while still capturing the real differences that the
intermediary stands in for.

Identity levels

pkg:service identifies a referent at three nested levels of specificity. Each
qualifier narrows the referent; each level is a strict subset of the one above.

Level	Form	Meaning
Service / product	pkg:service/openai.com/gpt-4o	A stable vendor service, product, model API, or platform — the vendor's native deployment.
Resource class	pkg:service/aws.amazon.com/ec2?resource_type=instance	A provider-defined kind of resource within the named service.
Native instance	pkg:service/aws.amazon.com/ec2?native_id=arn:aws:ec2:us-west-2:123456789012:instance%2Fi-0abcdef1234567890&resource_type=instance	A specific deployed resource, by the provider's canonical identifier.

Rationale (P3). For a service there is no "product as such" separate from
"product as deployed," so the bare service/product form is the vendor-native
deployment. It is also the root of the deployment family: a finding inherent to
the product (for a model, a weights-level flaw) is recorded against the bare
form and reaches aggregated siblings through the relationships in
Equality and propagation. For a closed product
there is no separate abstraction node to record it against — no artifact, no
registry id — which is precisely why service is its own type.

The service/product level is appropriate for catalog, dependency, and component
identity. The instance level is appropriate for inventory, evidence, and
point-in-time system descriptions, and should not appear in public advisories or
catalog records unless disclosure of the native identifier is intended.

Components

Component	Requirement	Definition
type	required	Literal service, lowercase.
namespace	required	DNS-order vendor namespace; may be aggregator-qualified as {surface}:{vendor}.
name	required	The vendor's stable, canonical product identifier.
version	optional	Vendor-provided product, model, snapshot, date, or API version.
qualifiers	optional	Resource class or native resource identity.
subpath	not used	Service PURLs should not use subpath.

Namespace

The namespace identifies the product owner, not a deployment region, API
host, billing account, or tenant. It is DNS-order (e.g., openai.com).
Implementations should store and compare namespaces in canonical lowercase.

Choosing the canonical namespace

Choose the broadest domain that unambiguously identifies the vendor,
division, or intermediary responsible for the offering — not the parent
conglomerate.

Vendor or owner	Canonical namespace
OpenAI	openai.com
Anthropic	anthropic.com
Meta	meta.com
Pinecone	pinecone.io
Grafana	grafana.com
Amazon Web Services	aws.amazon.com
Google Cloud	cloud.google.com

Rationale (P2). Anchoring to the responsible entity's domain makes the
namespace verifiable and convergent without a naming authority. "Division or
intermediary, not parent" resolves sub-branded and hosted-provider cases
deterministically — aws.amazon.com, not amazon.com; cloud.google.com, not
google.com — and matches how owners present the offering. It also handles
acquisitions for free: an acquired product that keeps its domain keeps its
identity (GitHub under Microsoft remains github.com), and one folded into the
acquirer's domain gets a new PURL. meta.com is used rather than meta.ai,
because meta.ai is a product domain, not the responsible-owner domain.

A rebrand or acquisition that changes the responsible domain yields a new
PURL; continuity is expressed as a relationship, not as identifier stability
(see Equality and propagation). This matches PURL's
existing behavior for renames in every other type.

Aggregator-qualified namespaces

When a product is reached through a distinct responsible intermediary, the
namespace may be aggregator-qualified. Segments are colon-separated and read
left to right; the rightmost segment is always the originating vendor, and
each segment to its left is an aggregation provider, outermost first. Each
segment is itself a canonical namespace chosen by the rule above.

pkg:service/openrouter.ai:openai.com/gpt-4o
pkg:service/aws.amazon.com:anthropic.com/claude-sonnet-4
pkg:service/together.ai:meta.com/llama-3.1-70b-instruct

Grammar (normative):

• : is a namespace sub-delimiter. A service-aware parser splits the namespace
  on :; the rightmost segment is the vendor, the rest is the aggregation chain.
• A namespace segment shall not contain a literal colon or a percent-encoding that
  decodes to a colon. Colon is reserved as the aggregation separator.
• Empty segments are prohibited (a::vendor is invalid).
• Multi-level aggregation is permitted but should be avoided.
• A non-service-aware consumer may treat the whole namespace as one opaque
  string. It still obtains a valid, distinct identity; only the aggregation
  structure is opaque to it.

Rationale (P2). The colon explicitly marks the aggregation boundary, which a
plain multi-segment (/) namespace cannot, since multi-segment vendor
namespaces are themselves legal. Because a different surface is a different
referent (above), distinguishing the aggregated form from the bare form is the
intended behavior, not a loss. Defining the parse — rightmost-is-vendor, no
empty segments, no colon escape hatch — keeps every aware parser in agreement.

Name

The name is the vendor's stable, canonical product identifier. Where the vendor
exposes the product through an API, the name should be the identifier the API
accepts (the on-the-wire model or product id); a canonical lowercase, URL-safe
slug is the fallback when no API identifier exists. Where the vendor's identifier
carries a separable snapshot or date, move that to @version and keep the stable
product identity in name.

gpt-4o
claude-sonnet-4
mistral-small-24b-instruct
redis-cloud

Rationale (P2). The API-accepted identifier is the natural Schelling point:
it is the exact string both the producer and any consumer already use to call
the product, so independent producers converge on it without coordination, and a
holder of the PURL can locate and invoke the service from namespace + name alone.

Version

The version is optional and opaque. It should be the vendor's own product, model
snapshot, date, release, or API version. It is the temporal axis of a service
whose name is stable while its behavior evolves.

pkg:service/openai.com/gpt-4o
pkg:service/openai.com/gpt-4o@2024-08-06
pkg:service/openai.com/gpt-3.5-turbo@0613
pkg:service/mistral.ai/mistral-small-24b-instruct@2501

Omitting version denotes the product identity without a pinned version. When a
product exposes a snapshot or dated build, encode it as @version rather than
flattening it into name.

Qualifiers

service requires no qualifiers. The following are defined; the Identity
column states whether the qualifier is part of component identity, because the
type-definition schema has no field to express this and consumers need to be told.

Qualifier	Requirement	Identity	Meaning
resource_type	optional	identity-bearing	Provider-defined resource class within the named service. Narrows service → resource class.
native_id	optional	identity-bearing	Provider-native canonical identifier for a specific deployed resource. Narrows resource class → instance.

Rationale (#257). resource_type and native_id narrow the referent, the
same way @version does, so they are identity-bearing: …/ec2 and
…/ec2?native_id=… are different referents at different specificity. A finding
against a class therefore propagates down to its instances directionally, with
no separate relationship needed for the vertical axis.

resource_type should use the provider's stable API, catalog, or documentation
term for the resource class.

native_id, when present:

• shall be the provider-native canonical identifier (an AWS ARN, Azure Resource
  ID, GCP resource name, Cloudflare locator, SaaS object id, or equivalent).
• shall not encode resource state, configuration, affectedness, remediation
  status, detection logic, or other mutable assessment data.
• Carries region, account, tenant, project, and subscription inside the
  canonical identifier. These shall not be encoded as separate qualifiers.
• Is percent-encoded in the canonical PURL string as with all qualifier values,
  per the web percent-encoding standard (RFC 3986 / WHATWG URL).

Rationale (P1). Region and tenancy are part of where/what instance, not a
separate product-level axis, so they live inside the instance's canonical id, if
at all; the product itself is region-agnostic. A distinct regional product
(separately contracted, with its own terms) is instead a distinct surface or
name, not a "region."

Region, pricing plan, deployment mode, tenant, customer configuration,
affectedness, and remediation state should not be encoded as qualifiers.

Equality and propagation

PURL equality is defined on the decoded components, so equivalent percent-encodings
of the same value are equal.

Identity narrowing handles the vertical axis: a finding recorded against a
service or class applies, directionally, to the instances below it. No
relationship is needed for this.

Two relationships, carried in the BOM or catalog layer rather than in the PURL,
handle the rest:

• variant-of links sibling deployments of the same product (the bare vendor
  form and its aggregator-qualified forms). A product-level finding recorded
  against the bare form propagates across these (CycloneDX pedigree.variants,
  SPDX VARIANT_OF).
• successor / alias links a renamed or re-homed identity to its predecessor,
  and links two equally-canonical domains for the same owner where the namespace
  rule does not fully converge.

Rationale (P1, P2). PURL is identity, not a graph; cross-deployment and
cross-rename continuity is real but belongs on edges, not inside the
identifier. The alias edge is also the pragmatic backstop for the residual
namespace divergence a prose directive cannot fully eliminate.

Relationship to CycloneDX and SPDX

In CycloneDX 2.0, services are represented as components, which carry purl; a
pkg:service identifier attaches directly to such a component. This proposal is
intended to align type: service with the component type CycloneDX 2.0 uses for
service-shaped components. Runtime endpoints are component-level
evidence/occurrence, not identity. A native_id is identity-bearing only
when the component is intentionally described at the native-instance level. In
SPDX, the identifier is an external identifier on the corresponding element,
with deployment relationships expressed via SPDX relationships.

Resolution

There is no single public repository for all products. Resolution is a catalog
lookup:

1. Parse and normalize the PURL.
2. Determine the identity level: service/product, resource class, or native
   instance.
3. Look up the service/product in a product or component catalog.
4. If resource_type is present, include the resource class.
5. If native_id is present, treat it as the provider-native resource
   identifier; use catalog metadata only for service, product, and class context.
6. If the namespace is aggregator-qualified, include both the surface and vendor
   context.
7. Use catalog metadata for homepage, documentation, licensing, source and
   operator parties, lifecycle status, and product relationships.

Package-collection tooling that crawls standard registries should treat
pkg:service as valid PURL syntax but not automatically collectable without a
product-catalog backend.

Candidate type-definition JSON

{
  "$schema": "https://packageurl.org/schemas/purl-type-definition.schema-1.0.json",
  "$id": "https://packageurl.org/types/service-definition.json",
  "type": "service",
  "type_name": "Service",
  "description": "Hosted, managed, or otherwise service-shaped software with no distributable artifact or authoritative package registry: hosted products, model APIs, managed platforms, provider-defined resource classes, and specific provider-native resource instances. Use an existing package-ecosystem type when the referent has a canonical package-registry identity.",
  "repository": {
    "use_repository": false,
    "note": "There is no default repository for services. Resolution uses a product catalog."
  },
  "namespace_definition": {
    "requirement": "required",
    "case_sensitive": false,
    "permitted_characters": "^[a-z0-9.-]+(:[a-z0-9.-]+)*$",
    "native_name": "vendor namespace",
    "normalization_rules": [
      "The canonical namespace is the domain of the vendor, division, or intermediary responsible for the offering, not the parent conglomerate, in DNS order and lowercase (for example openai.com, aws.amazon.com).",
      "An aggregator-qualified namespace prefixes the vendor namespace with one or more intermediary namespaces separated by a colon; segments read left to right with the rightmost segment as the originating vendor (for example openrouter.ai:openai.com).",
      "Colon is reserved as the aggregation separator; namespace segments shall not contain a literal colon or a percent-encoding that decodes to a colon; empty segments are not permitted."
    ],
    "note": "The namespace identifies the product owner, not a URL authority."
  },
  "name_definition": {
    "requirement": "required",
    "case_sensitive": false,
    "permitted_characters": "^[a-z0-9][a-z0-9._-]*$",
    "native_name": "product identifier",
    "normalization_rules": [
      "Use the vendor's API-accepted identifier where one exists; otherwise a lowercase, URL-safe slug of the vendor's stable product name.",
      "Where the vendor identifier carries a separable snapshot or date, place that in version and keep the stable product identity in name."
    ]
  },
  "version_definition": {
    "requirement": "optional",
    "case_sensitive": true,
    "native_name": "product, model, snapshot, date, or API version",
    "note": "An opaque vendor-provided string."
  },
  "qualifiers_definition": [
    {
      "key": "resource_type",
      "requirement": "optional",
      "description": "Provider-defined resource class within the named service. Identity-bearing: narrows the referent to a kind of resource."
    },
    {
      "key": "native_id",
      "requirement": "optional",
      "description": "Provider-native canonical identifier for a specific deployed resource (AWS ARN, Azure Resource ID, GCP resource name, or equivalent). Identity-bearing: narrows the referent to a specific instance. Carries region/account/tenant inside the canonical id; percent-encoded as with all qualifier values."
    }
  ],
  "examples": [
    "pkg:service/openai.com/gpt-4o",
    "pkg:service/openai.com/gpt-4o@2024-08-06",
    "pkg:service/mistral.ai/mistral-small-24b-instruct@2501",
    "pkg:service/openrouter.ai:openai.com/gpt-4o",
    "pkg:service/aws.amazon.com:anthropic.com/claude-sonnet-4",
    "pkg:service/aws.amazon.com/ec2?resource_type=instance",
    "pkg:service/cloud.google.com/kubernetes-engine?resource_type=cluster",
    "pkg:service/aws.amazon.com/ec2?native_id=arn:aws:ec2:us-west-2:123456789012:instance%2Fi-0abcdef1234567890&resource_type=instance"
  ],
  "note": "Identity is vendor namespace plus canonical product name plus responsible intermediary when distinct; the delivery URL is never part of identity."
}

Summary of key decisions

Decision	Reason
Identity = vendor + product (+ responsible intermediary); never the delivery URL.	Location is not identity (P1); responsible entity forks, transport does not.
Name = the vendor's API-accepted identifier.	It is the string both sides already use — the natural Schelling point (P2).
Canonical namespace = responsible vendor/division/intermediary, not parent.	Verifiable, convergent owner identity without a naming authority (P2).
Rebrand/acquisition → new PURL; continuity via a successor edge.	Identifier stability is not the mechanism for continuity; relationships are.
Aggregator namespace, colon-separated, rightmost = vendor; multi-level discouraged.	The colon marks the aggregation boundary a / namespace cannot; a distinct surface is a distinct referent.
resource_type and native_id are identity-bearing.	Narrowing qualifiers change the referent like @version (#257).
For a service, the bare form is the vendor-native deployment.	A service is deployment-only; there is no separate "product as such" (P3).
Region/tenant live inside native_id, not as qualifiers.	They are instance-level facts, not a product axis (P1).
Deployment/rename continuity lives on BOM edges, not in the PURL.	PURL is identity, not a graph.

References

• ECMA-427 Package-URL specification: https://ecma-tc54.github.io/ECMA-427/
• Ecma International ECMA-427 page:
  https://ecma-international.org/publications-and-standards/standards/ecma-427/
• Package URL type definitions:
  https://github.com/package-url/purl-spec/tree/main/types
• Package URL type-definition schema:
  https://raw.githubusercontent.com/package-url/purl-spec/main/schemas/purl-type-definition.schema-1.0.json
• purl-spec #127 "Decoupling location from identity":
  https://github.com/package-url/purl-spec/issues/127
• purl-spec #257 "What is a package?":
  https://github.com/package-url/purl-spec/issues/257
• RFC 3986 (URI Generic Syntax) and the WHATWG URL Standard (percent-encoding).
• ISO/IEC Directives, Part 2 (verbal forms for the expression of provisions).