RFC 0009 — Entity Category and Category Taxonomy

1. Motivation

The MSR JSON 2.0 schema describes entity as the "identity, categorization, and localized descriptions of the software entity", yet it defines no category property. Because entity carries additionalProperties: false, a publisher cannot state what kind of software it publishes without making the manifest invalid.

Registries classify software anyway, by hand and off-manifest. Each registry guesses, the guesses drift apart, and none of them can be checked against the domain-bound source of truth at /.well-known/msr.json. Identity, trust and releases already live in the manifest; category is the one piece of catalog metadata that does not.

2. Manifest Fields (entity.category, entity.subcategories)

RFC 0009 adds two OPTIONAL properties to entity:

"entity": {
  "category": "funeral-management",
  "subcategories": ["erp", "point-of-sale"]
}

Normative rules

1. A publisher SHOULD choose slugs from the MSR category taxonomy (Section 3).
2. subcategories MUST NOT repeat the value of category. The schema cannot express this rule; validators MUST check it.
3. A category describes what the software is for (funeral-management is software for funeral homes), not the business of its vendor or its users.

3. The MSR Category Taxonomy

Slugs come from one published taxonomy, versioned with the specification at taxonomy/categories.json. Each entry has a slug and an English name:

{
  "version": "1.0.0",
  "categories": [
    { "slug": "funeral-management", "name": "Funeral Management" }
  ]
}

1. Seed. Version 1.0.0 holds 107 categories, taken from the categories software registries already use for 1,012 listings. Starting from classifications in use keeps existing listings mappable.
2. Stability. A published slug is never renamed and never reused. A slug to retire is marked deprecated in a later version and stays valid.
3. Versioning. Adding a category is a MINOR taxonomy change; deprecating one is MINOR; clarifying a name is PATCH. The taxonomy version is independent of the protocol version.
4. Changes. New categories are proposed as pull requests to the specification repository, with the listings that need them.

4. Validation

• The JSON Schema enforces format, length, count, uniqueness and the subcategories → category dependency. A violation is an error.
• A well-formed slug that is not in the taxonomy is a validator warning in 2.1, never an error, so taxonomy lag never blocks a publisher.
• Registries MAY map unknown slugs to their own classification.

5. Registry Processing

When a manifest declares a category found in the taxonomy, a registry SHOULD prefer it over its own classification, because it is domain-bound (and signed when trust.signatures is present). A registry keeps its own classification as a fallback for manifests without a category and for unknown slugs.

6. Compatibility

The change is additive and optional: every valid MSR JSON 2.0 manifest stays valid under 2.1, which makes it a MINOR protocol change. The properties ship in MSR JSON 2.1 (schemas/msr-2.1.json); the 2.0 schema keeps rejecting them under additionalProperties: false.

7. Security Considerations

• Self-declared claim. A publisher can declare any category. Registries SHOULD treat it as a claim, moderate it like any other self-declared field, and MAY override a category that misrepresents the software (for example to reach a less crowded listing).
• No new surface. The fields add no endpoint and no network fetch; validating a slug against the taxonomy uses a local copy of categories.json.

8. Open Questions

• Some seed categories describe a platform or a format rather than a purpose (mobile-apps, internet-apps, desktop-utilities, ai-apps). The Working Group decides whether to deprecate them in favour of purpose categories.
• Whether taxonomy names are localized in the taxonomy file or left to registries.