Define the package `props.json` contract and multi-package schema behavior

[dlabaj]

Context

patternfly-component-schemas currently receives one manually copied component-metadata.json file generated by patternfly-doc-core. We are adding a transition path where each PatternFly package publishes its own prop metadata artifact, for example:

@patternfly/react-core/schema/props.json

The minimum initial contract is:

{
  "formatVersion": 1,
  "package": "@patternfly/react-core",
  "packageVersion": "6.6.1",
  "components": {
    "Button": {
      "name": "Button",
      "description": "...",
      "props": []
    }
  }
}

patternfly-component-schemas will consume these artifacts and continue producing the JSON Schema and Zod package consumed by MCP. The MCP should not need to consume package-level props.json directly during the initial migration.

Goals

• Define and document the stable props.json format.

• Keep formatVersion available for future incompatible metadata changes.

• Preserve the existing component metadata shape where possible.

• Include the exact npm package name and version for provenance.

• Allow the schema repository to aggregate metadata from multiple PatternFly packages.

• Preserve the current schema package API during the first migration.

Questions for agreement

1. Component identity across packages

Should the aggregate schema package identify components by short name:

Button

or by package-qualified name:

@patternfly/react-core/Button

Suggested approach: preserve short names when unambiguous, detect and report collisions, and add package-qualified identities when needed.

2. Component variants

Should next and deprecated components remain separate schema entries?

Examples:

WizardFooter
WizardFooter-deprecated

If they remain separate, should the variant be represented only in the component key or also as explicit metadata?

3. Supporting declarations

How should named supporting types and *Props declarations be represented?

The current generator excludes top-level entries whose names end in Props. We need to decide whether those declarations should eventually be retained as reusable references or remain implementation details.

4. Schema strictness

The current generated JSON Schemas use:

"additionalProperties": false

Should schemas reject all props not present in extracted metadata, or should they allow common React/native attributes and unknown props when metadata is incomplete?

This affects MCP validation behavior for props such as className, id, aria-*, data-*, and inherited DOM props.

5. Complex TypeScript types

The current conversion is intentionally lossy for function types, React nodes, generics, intersections, and named types. Should these remain descriptive/opaque in JSON Schema, or should we define a richer representation for MCP generation and validation?

6. Package/version compatibility

Should the aggregate schema package expose the source package and version in its generated index so MCP can determine which PatternFly release it is validating against?

7. Artifact location and npm exports

Should packages publish metadata at:

schema/props.json

and explicitly export it through package.json, or is including the file in the npm tarball at a documented path sufficient for the first phase?

Non-goals for the initial migration

• Changing the MCP server's current schema consumption API.

• Making generatedBy a required field in props.json.

• Updating patternfly-org documentation consumption immediately.

• Generating JSON Schema or Zod inside each component package.

• Removing the existing flat dist/props.json documentation workflow before consumers migrate.

Acceptance criteria

• The props.json format is documented and versioned.

• Package name and exact package version are required metadata.

• patternfly-component-schemas can aggregate at least two package artifacts.

• Component name collisions are detected and reported.

• Existing MCP imports and schema lookup behavior remain compatible for the first release.

• A migration plan is documented for package-qualified component identities.

• JSON Schema strictness is agreed upon and covered by tests.

---

Jira Issue: PF-4627