feat: add plugin schema

[fzipi]

what

• add plugin schema for discovery and configuration

why

• enhance plugin onboarding experience

[Copilot]

Pull request overview

Adds a JSON Schema and accompanying documentation/examples to standardize CRS plugin discovery and configuration via a plugin.yaml descriptor.

Changes:

• Introduce plugin-schema.json (JSON Schema draft 2020-12) for validating plugin descriptors.
• Add documentation describing the schema fields and intended usage (docs/plugin-descriptor-schema.md).
• Provide example plugin descriptors under examples/ for reference and onboarding.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
plugin-schema.json	Defines the structure/constraints for plugin.yaml plugin descriptors.
docs/plugin-descriptor-schema.md	Documents the schema fields, intent, and rollout plan.
examples/wordpress-rule-exclusions-plugin.yaml	Example descriptor for a rule-exclusion plugin.
examples/fake-bot-plugin.yaml	Example descriptor for a detection plugin with multiple variables.
examples/body-decompress-plugin.yaml	Example descriptor for a utility plugin with numeric bounds.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fzipi]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied all changes from the review in commit bc82781:

• configuration.variables: added minItems: 1 to prevent empty variable lists
• default/example type validation: added if/then conditionals for all four types — boolean values must be integer 0 or 1; integer values must be integers; string and enum values must be strings
• allowed_values: added items: {type: string} and a conditional requiring it when type is "enum", and forbidding it for non-enum types
• min/max: changed from type: number to type: integer and added a conditional that forbids them on non-integer variable types
• Example fix: renamed tx.body-decompress-plugin_enable → tx.body-decompress-plugin_enabled to match the documented convention
• Docs: updated the boolean type description to clarify values are integers (0/1) following the ModSecurity convention

[theseion]

The registry will also need to have a new way to register plugins, i.e., a YAML file that contains an entry for each GitHub repository. That means that at least the repository URL in the schema is an unnecessary duplicate.

We should make it clear that we currently only support GitHub repositories.

[theseion]

Do you agree with what I wrote here? Is I wrote there, we should also make it clear that we only support GitHub atm.

[fzipi]

I agree on allowing only github repos for now.

[fzipi]

@copilot fix all table formatting and add a similar section for the engines category taxonomy.

[Copilot]

@copilot fix all table formatting and add a similar section for the engines category taxonomy.

Done in commit eae1216:

• Fixed table alignment for separator, prefix, and suffix rows in the variable definition table
• Added an "Engine taxonomy" section under Design Decisions (parallel to the existing "Category taxonomy" section) listing all four supported values (modsecurity2, modsecurity3, coraza, all) with descriptions

Do you agree with what I wrote here? Is I wrote there, we should also make it clear that we only support GitHub a...

Agreed — the repository URL in plugin.yaml can be used as the lookup key until a separate registry YAML exists. For now, in commit eae1216 the repository field in the schema has been restricted to a GitHub owner/repo URL pattern (^https://github\.com/[^/]+/[^/]+/?$), and the docs field description has been updated to note that only GitHub repositories are currently supported.

[theseion]

Suggested change

	When omitted, no compatibility constraints are assumed. Tooling should treat missing `engines` field as if `engines` were set tp `all`.
	When omitted, no compatibility constraints are assumed. Tooling should treat missing `engines` field as if `engines` were set to `all`.