[Feature] Document marketplace.json schema

[rcollette]

Problem

There is no dedicated documentation in the APM project that clearly defines the schema for marketplace.json. As the APM tool expands its marketplace model—including support for both Git-backed and URL-backed marketplaces—having an up-to-date, authoritative schema reference is critical for:

• Marketplace publishers (defining their own marketplace.json)
• Third-party integrators (validating and generating compatible indexes)
• Users diagnosing issues with marketplace registration or skill indices

Proposal

• Add a dedicated documentation page or appendix to the current docs that describes the full JSON schema expected for marketplace.json.
• Cover all current required and optional fields, types, value constraints, and examples.
• Document how differences are handled between repo-backed and URL-backed marketplace schemas (including references to Agent Skills specification if applicable).
• Include versioning strategy and backward compatibility notes.
• Link to any relevant RFCs/specifications (e.g., Agent Skills, RFC 8615).

Motivation

• Reduce publisher/integrator confusion and support requests
• Enable better validation, error messages, and automation for marketplace publishing
• Support the planned generalization of the marketplace discovery model

Example Content to Include

• Example minimal and full-featured marketplace.json files
• JSON schema definition (or link)
• Common mistakes and troubleshooting
• Comparison table/references for .well-known/agent-skills/index.json vs. repo marketplace.json

Reference material

The guide at https://github.com/microsoft/apm/blob/main/docs/src/content/docs/guides/marketplaces.md is insufficient for agents and other tooling to generate marketplace.json files.

[danielmeppiel]

Hi @rcollette , the reference for plugin marketplaces is not an industry standard as of today. The implementation in APM follows the reference schema from GitHub Copilot CLI and Claude Code, which should both match. Agree this should be clearly stated in the docs.

[github-actions]

Triage decision

accept

Proposed labels

theme/governance
area/marketplace
area/docs-site
type/docs
status/accepted
priority/low
good first issue
status/triaged

Milestone

null

Suggested next action

Add a marketplace.json schema reference page to docs/src/content/docs/guides/marketplace/ (or equivalent) documenting all required and optional fields, types, constraints, and examples for both Git-backed and URL-backed marketplace formats.

Suggested issue comment

Thanks for pointing this out -- the marketplace.json schema is a real documentation gap. Publishers who want to create their own marketplace, and integrators who need to generate or validate compatible indexes, currently have to reverse-engineer the schema from source or examples.

This is a well-scoped documentation task:

1. Add a schema reference page to the Starlight docs site under `docs/src/content/docs/guides/marketplace/` (or a similar location).
2. Cover all required and optional fields, their types, constraints, and examples.
3. Document how the two marketplace formats (Git-backed and URL-backed) differ in their schema expectations.
4. Include a minimal working example that a publisher can copy-paste as a starting point.

The existing marketplace source in `src/apm_cli/marketplace/` is the authoritative reference for field names and validation rules -- no new design decisions are needed, just documentation of what already exists. If you would like to take this, a docs-only PR is a clean contribution with no risk of breaking changes. See CONTRIBUTING.md for the docs setup (it uses Starlight / Astro).

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps to a concrete user task: marketplace publishers and third-party integrators need a schema reference to create and validate their marketplace.json without reading source code. The request includes a clear scope (required and optional fields, types, value constraints, examples, multi-format differences), making this a well-specified documentation task with no ambiguity in scope.

Supply Chain Security Expert -- Risk-Surface Reviewer

Documenting the marketplace.json schema is a governance positive: it creates an authoritative reference that makes deviations and schema violations easier to spot. If the schema documentation includes the expected protocol constraints and domain trust expectations, it also strengthens the marketplace trust surface documentation. theme/governance is appropriate because marketplace schema specification is part of the package governance story.

OSS Growth Hacker -- Contributor-Tone Reviewer

Activated. rcollette is NONE association. The request is well-organized and demonstrates understanding of the marketplace model (distinguishes Git-backed vs URL-backed formats). The reply should be warm, validate the gap immediately, and give them a concrete path to contribute a docs-only PR with no risk of breaking anything.

Python Architect -- Architecture Reviewer

Not activated -- this is a documentation task. The schema reference should be derived from the existing marketplace source code (src/apm_cli/marketplace/), not from a new design decision. No cross-cutting impact.

Doc Writer -- Documentation Reviewer

Activated. This fits as a dedicated reference page in the Starlight docs site. The marketplace guides section likely needs a "Schema Reference" page. The implementing PR should validate the documented schema against the marketplace source code to prevent doc drift. area/docs-site is primary; area/marketplace is secondary to ensure the PR is linked to the marketplace feature area. Suggested comment wording is clear and grounded in the vocabulary used in the README marketplace section.

APM CEO -- Triage Arbiter

Clean docs win. Accepting as good first issue because it is a bounded documentation task with a clear authoritative source (the marketplace source code) and no architectural decisions needed. theme/governance because marketplace schema documentation is part of the package governance story. No milestone -- this is not a release blocker, and docs contributions are welcome on their own schedule.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/governance",
  "areas": ["area/marketplace", "area/docs-site"],
  "type": "type/docs",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": ["good first issue"],
  "milestone": null,
  "next_action": "Add a marketplace.json schema reference page to docs/src/content/docs/ documenting all fields, types, and examples for both marketplace formats.",
  "comment_markdown": "The marketplace.json schema is a real documentation gap. A docs-only PR adding a schema reference page to the Starlight site is a clean, self-contained contribution. Source of truth: src/apm_cli/marketplace/."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 3.3M · ◷