INTENT-1 v3 / INTENT-3 v2 / INTENT-4 v2: union slot sets + optional required_slots

[JarbasAl]

This PR relaxes the strict slot-consistency rule for .intent files and introduces an optional required_slots mechanism for template intents.

Changes

OVOS-INTENT-1

• §5.5 — narrowed to .dialog only. .intent files now allow templates with different slot sets (union semantics). The engine extracts only the slots declared by the template that best matches.
• §6.2 — engine obligation updated: verify consistent slot sets only for .dialog; accept differing slot sets for .intent.

OVOS-INTENT-3

• §5.1 — removes the slot-consistency obligation for template intents.
• §5.3 (new) — required_slots: an optional list of slot names the engine MUST extract for a match to be valid. When present, handlers MAY rely on those slots being populated. A required slot must be declared by at least one template; otherwise the definition is malformed.
• §7.1 — handler guarantee updated: handlers MAY rely on required_slots; all other slots remain optional and must be defensively handled.
• §5.4/§5.5 — renumbered from former §5.3 (Example) and §5.4 (Suppression).

OVOS-INTENT-4

• §6.1 — adds required_slots as an optional array-of-strings field to the ovos.intent.register.template payload.
• §6.2 — rewrites the slot-consistency rule: consuming plugins MUST accept template registrations with differing slot sets across templates.
• §6.3 — replaces the "slot sets differ" malformed rule with a required_slots malformed rule: a required slot not declared by any template is malformed.

OVOS-PIPELINE-1

• §6.2 — adds orchestrator MUST backstop for required_slots. After the denylist check, the orchestrator verifies the match's slot map contains every required slot; if absent, it treats the match as declined. Primary enforcement remains engine-side during match(); the orchestrator is a second line of defense.
• §6.1 flow diagram — adds the required_slots backstop step.

appendix/patterns.md

• §3.4 — new section with authoring patterns for union slot sets and required_slots, including practical examples (one intent with multiple phrasing shapes, guaranteeing a slot, optional phrasings, and the .dialog strictness distinction).

Design rationale

• Why relax §5.5? Padatious-like engines already match per-template and extract per-template. The strict consistency rule forced authors to split phrasings into separate files when slot sets differed, even when those phrasings represented the same command. Union semantics make authoring more natural.
• Why not a locale file for required_slots? required_slots contains technical slot identifiers, not localized natural-language data. It is intent metadata, not a translatable resource, so it belongs in the bus registration payload (consistent with handler binding, enable/disable state, and other non-locale metadata).
• Why not keyword intents? Keyword intents already have required vocabularies (§4.2) that serve an analogous role. required_slots is the template-intent counterpart, mirroring how .blacklist is template-only.
• Why orchestrator MUST backstop? The orchestrator and pipeline plugins are co-located in the utterance-handling process and consume the same bus broadcasts. The orchestrator already actively gatekeeps with blacklisted_skills / blacklisted_intents; required_slots backstop is the same shape. This gives handlers the strongest guarantee regardless of engine bugs.

Cross-references updated

• INTENT-4 §5.4 cross-reference to INTENT-3 §5.5 (suppression) corrected.
• README spec index table unchanged (specs remain Draft, no version bump).

Companion design record: #57

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b7846e3b-f0c7-435b-ba59-9aae6d83a318

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch spec/intent-union-slots-required

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[JarbasAl]

Merge-ready (MERGEABLE, 0 commits behind dev). Fix applied: §5.4 (Suppression/.blacklist) in INTENT-3 was a duplicate heading — renumbered to §5.5 to match the cross-references that already used §5.5. All internal §-references across INTENT-3 and INTENT-4 are consistent. Version headers left at v2/v1/v1 per the Draft-freeze policy (commit 1fe29fc). Note: after #55 merges, GLOSSARY.md in this branch will need ovos-intent-*.md links updated to the short names.