Overview
Validation rules capture the requirements a trading partner states in its companion guide: which fields are required, which values are allowed, and what format a field must match. A rule can also carry a condition, so a requirement applies only to the records the guide says it applies to. Rules live on a partner profile and target the profile’sgrain_fields, which are flattened field names such as member_id or benefit_status, never X12 segment positions.
Use validation rules when a partner’s guide states checks that go beyond simple element requirements, for example:
- A field that is required only when another field holds a given value.
- A field that must never carry one of a set of values the partner rejects.
- A date that must fall on or after another date in the same record.
Rules are configuration today. They are stored on the profile and returned by the API, but Integrate.io does not yet evaluate them when a job runs. Enforcement, where a blocking finding holds a file before it reaches the partner, is enabled per account separately once an account’s rules have been reviewed.
Rule anatomy
Every rule has:
Every rule type becomes conditional by attaching a
condition. required plus a condition is a conditional requirement; prohibited plus a condition is a conditional prohibition.
Rule types and params
length, pattern, code_list, blacklist, and compare stay quiet on a blank value. Presence is a required rule’s job, so one missing field does not produce two findings.
Conditions
A condition is{"field": ..., "operator": ..., "value": ...}:
The condition’s
field, like target_field and a compare rule’s other, must be one of the profile’s grain fields. A rule naming an unknown field is rejected at save time, with the grain listed in the error. A profile likewise refuses to drop a grain field while a rule still uses it.
Readable summaries
Each rule is returned with a generatedsummary sentence, for example cobra_qualifier is required when benefit_status is C. Set message to replace the generated wording in findings.
Rules on overlays
A profile that overlays a base is governed by both rule sets: the base’s rules run first, then the overlay’s own. Rules on platform-scoped profiles are readable by every account and read-only through the API; writes return403.
API
All rule endpoints require the same permissions as the profile they belong to: viewing connections to read, creating connections to write.Create a conditional requirement
Create a code list rule
Reorder rules
rule_ids must list every rule on the profile, in the order they should be evaluated. A partial or mismatched list is refused with the profile’s actual rule ids in the error.
Limits
- Patterns are capped at 200 characters, anchored at both ends, and run under a timeout per match. A pattern that exceeds the timeout on a value fails validation of the file rather than skipping the rule.
- Values longer than 4096 characters are not pattern-matched and are reported as findings instead.
valueslists andin/not_incondition lists are capped at 1000 entries.- Findings never quote more than 10 values from a list.
FAQ
Q: Why was my rule rejected at save time? The most common causes are atarget_field, condition field, or compare other that is not in the profile’s grain, an invalid or too-long pattern, an empty values list, or a min greater than max. The error names the field and lists the profile’s grain fields.
Q: What is the difference between block and warn?
block marks the finding as one that holds the file so it does not reach the partner. warn records the finding and lets delivery proceed. Until enforcement is enabled for your account, both are recorded only.
Q: Can I edit the rules on a platform profile?
No. They are curated centrally. Overlay the platform profile with an account profile and add your own rules on the overlay; the base’s rules still apply, followed by yours.