Validation Rules User Guide

Understanding and managing OSCAL validation rules.

What are Validation Rules?

Validation rules are checks that ensure your OSCAL documents meet quality standards, comply with specifications, and contain all required information. When you validate an OSCAL document, the system runs these rules to identify potential issues.

OSCAL Hub includes two types of validation rules:

• Built-in Rules: Pre-configured rules based on OSCAL specifications and best practices.
• Custom Rules: Rules you create to enforce your own requirements. Custom rules fire alongside the built-in rules during validation — violations show up in results just like native OSCAL violations, distinguished by a [custom: <rule-id>] prefix on the message.

Custom rules can be authored two ways:

• AI Rule Generator (recommended for non-experts). Describe the rule in plain English and let the wizard generate, test, and save it for you. See the AI Validation Rule Generator guide.
• Manual editor. Write the Metaschema constraint XML yourself in the Custom Rules Management page. Useful for fine-grained control or when the AI gets a rule almost-but-not-quite right and you want to hand-tweak.

Built-in Validation Rules

Built-in rules are automatically included with the platform and cover common OSCAL validation scenarios. These rules check for:

• Required metadata fields (title, version, last-modified)
• UUID format and uniqueness
• Valid references to other OSCAL objects
• Proper structure and relationships between elements
• Date/time format compliance
• Security control identifiers and references

Custom Validation Rules

Custom rules allow you to enforce organization-specific requirements that go beyond the standard OSCAL specifications. You can create custom rules to:

• Enforce naming conventions for controls or components
• Require specific metadata fields for your organization
• Validate custom extensions or properties
• Check for required relationships between elements
• Ensure compliance with internal policies

Creating a Custom Rule with AI (recommended)

1. Open the AI Rule Generator

   Go to the Custom Rules Management page and click Generate with AI.

2. Pick the OSCAL model and describe the rule

   Select the model your rule applies to and type a plain-English description of what the rule should enforce. The wizard handles clarification, generation, and self-testing.

3. Review and save

   Inspect the test matrix and the generated constraint, give the rule a unique id, and click Save rule. Done.

For details on the conversation flow, the synthetic test matrix, and what the wizard generates under the hood, see the AI Validation Rule Generator guide.

Creating a Custom Rule manually

1. Navigate to Custom Rules Management

   Go to the Custom Rules Management page.

2. Click New Rule

   Click the New Rule button (next to Generate with AI) to open the rule creation form.

3. Fill in the rule details

   Provide the following information:

   • Rule ID: Unique identifier (e.g., custom-rule-001)
   • Name: Descriptive name for the rule
   • Description: What the rule validates
   • Rule Type: How the rule expression is interpreted (see Rule Types below)
   • Rule Expression: The constraint itself — Metaschema constraint XML for metapath rules, or a path/regex for simpler types
   • Severity: Error, Warning, or Info
   • Category: Organizational grouping
   • Applicable Model Types: Which OSCAL models this rule applies to
4. Save the rule

   Click Create Rule to save.

Rule Types

Understanding Severity Levels

Error

Critical issues that must be fixed. Documents with errors:

• Violate OSCAL schema requirements
• Have missing required fields
• Contain invalid data that prevents processing
• Should not be used in production until resolved

Warning

Issues that should be addressed but do not prevent processing:

• Recommended best practices not followed
• Potential quality issues
• Fields present but may need attention
• Could cause problems in certain contexts

Info

Informational notices for awareness:

• Suggestions for improvement
• Optional enhancements
• Documentation reminders
• Nice-to-have additions

Rule Categories

Rules are organized into categories to help you find and manage them:

Filtering and Searching Rules

The Validation Rules page provides several ways to narrow the list:

• Source tiles (clickable): The All Rules, Built-in Rules, and Custom Rules tiles at the top double as filter toggles. Click Custom Rules to show only your own rules; click again or click All Rules to clear. The active tile is ring-highlighted, and the tile counts always reflect the full data set so you can see at a glance what's there.
• Text search: Search by rule name, description, or ID.
• OSCAL Model Type: Filter by which OSCAL models the rule applies to (Catalog, Profile, SSP, etc.).
• Category: Filter by rule category to focus on specific areas.
• Clear filters: A "Clear filters" link appears next to the Showing N of M line whenever any filter is active.

Custom rule cards are clickable — clicking one jumps to the Custom Rules Management page with the edit dialog pre-opened on that rule, so you can tweak, disable, or delete it in two clicks. Built-in rule cards are read-only and not clickable.

Best Practices

Start with Built-in Rules

Review all built-in rules to understand what is already being validated before creating custom rules.

Use Descriptive Names

Give your custom rules clear, descriptive names that explain what they validate.

Set Appropriate Severity

Use Error only for critical issues, Warning for best practices, and Info for suggestions.

Organize with Categories

Assign rules to appropriate categories to keep them organized and easy to find.

Document Your Rules

Include detailed descriptions explaining what the rule checks and why it is important.

Test Before Enabling

Create rules in a disabled state first, test them, then enable them for production use.

Additional Resources

• View All Validation Rules
• Manage Custom Rules
• AI Validation Rule Generator — describe a rule in plain English and let the wizard build it