paragraphs_contextual_validation

Paragraphs Contextual Validation adds configurable rules to paragraph reference fields: limit how many times a type appears, require a type to be first or last, or require two types to be (or not be) adjacent. Validation runs on save, REST, and API.

Introduction

Paragraphs Contextual Validation adds configurable validation rules to paragraph reference fields. If you use the Paragraphs module to build flexible content (e.g. landing pages with Hero, CTA, and Text blocks), this module lets you enforce structure: for example, "at most one Hero," "Hero must be first," or "Disclaimer must be immediately above CTA." Rules are configured per field on the field settings form, and validation runs whenever the entity is validated—on save, via REST/JSON:API, or in custom code. No new content types or config pages; everything is under the existing field configuration.

Features

• Cardinality rules — Limit how many times a paragraph type may appear in the field. Choose from: more than, at least, exactly, fewer than, or at most a given count (e.g. "Hero at most 1 time," "CTA at least 2 times").
• Absolute position — Require a paragraph type to be the first or last item in the field (e.g. "Hero must be first," "Footer block must be last").
• Relative position — Require (or forbid) two paragraph types to be placed immediately next to each other (e.g. "Disclaimer must be immediately above CTA," "Banner must not be immediately below Hero").
• Constraints are defined per field on the field's edit form, in a Paragraphs contextual validation section. No separate config entity or admin screen.
• Violation messages use paragraph type labels (not machine names) so editors see clear errors (e.g. "Quick Links must be immediately below Basic Cards.").
• Settings are stored as third-party settings on the field config and export with configuration (e.g. drush config:export).
• When a paragraph type is deleted, the module removes any constraints that referenced it from all field configs.
• Other modules can provide custom rule plugins (PHP 8 attribute–based) that appear in the same constraint list.

When to use it: Use this module when you need to enforce editorial rules on the order and count of paragraph types (e.g. one hero, hero first, or specific ordering between types). It is aimed at content editors and site builders who already use Paragraphs and want to prevent invalid layouts without writing custom code.

Post-Installation

1. Enable the module (Drush: drush en paragraphs_contextual_validation or Admin → Extend).
2. Go to Structure → Content types (or the structure page for the entity type that has your paragraph reference field).
3. Click Manage fields for the content type that uses paragraphs.
4. Click Edit on the paragraph reference field you want to constrain.
5. Open the Paragraphs contextual validation details section.
6. Check Enable paragraphs contextual validation.
7. Click Add constraint, choose a rule type (Cardinality, Absolute position, or Relative position), fill in the options (paragraph type, operator/count or position/relation), and confirm. Repeat for each rule.
8. Click Save settings at the bottom of the field form.

No new content types, text formats, or config pages are created. All configuration lives on the field. After saving, validation runs automatically when content using that field is saved (form, REST, JSON:API, or any code that validates the entity). If a rule is violated, the save is blocked and errors are shown next to the relevant paragraph(s) in the form.

Additional Requirements

• Drupal core 10.2+ or 11.x
• PHP 8.1+
• Entity Reference Revisions — required (paragraph reference fields use this).
• Paragraphs — required (the module only applies to fields that reference paragraph entities).

No external APIs or non-Drupal libraries are required.

Recommended modules/libraries

None required. This module works with standard Paragraphs and Entity Reference Revisions setups. If you use REST or JSON:API, validation is applied there as well when entities are validated.

Similar projects

Other modules may offer paragraph or layout restrictions (e.g. limiting which types can be added in certain contexts). Paragraphs Contextual Validation focuses specifically on validation rules for order and count: "this type must be first," "at most N of this type," "type A must be immediately above/below type B." Rules are configured per field and enforced by Drupal's validation system, so they apply consistently on the form, in APIs, and in custom code. If you need different behavior (e.g. conditional visibility or different UX), compare with other Paragraphs-related modules to see which fits your use case.

Additional information

• Validation scope: The constraint is attached at runtime to the field definition for fields that have the feature enabled. Validation runs wherever the entity (e.g. node) is validated—entity form submit, REST PATCH/POST, JSON:API, or $entity->validate() in code.
• Extending: Custom rule plugins live in src/Plugin/ParagraphsContextualValidation/Rule/ and use the #[ParagraphsContextualValidationRule] PHP 8 attribute. They are discovered automatically; no YAML registration is needed.