Catalog Validation Rules: Write the Check Before the File Arrives
How to write a catalog validation rule as a named predicate, version it with the dictionary, and stop a record that fails.
- 01 Name the rule
- 02 Write the predicate
- 03 Name the failure
- 04 Version the rule
A validation rule is a predicate you can fail
A catalog validation rule says what must be true of a record before it moves on, in a sentence a later reader can apply again. “Looks complete” is not a rule. “public_name is non-empty after trim” is a rule, once that field exists in the data dictionary and the obligation there agrees.
W3C Best Practice 6, in the Data on the Web Best Practices recommendation of 31 January 2017, says to provide information about data quality and fitness for particular purposes. It also says that known quality issues should be stated in the metadata. The recommendation is about datasets on the web. It does not list the predicates for your catalog, and the example measurements in that section are not thresholds for you to copy. The operational point is that a known check should be written down, and a known failure should stay visible. A pass mark with no rule text hides both.
Write the rule before the file arrives. A rule composed while a file is open will be shaped by the rows someone wants to save. The onboarding checklist already refuses that order: validate, then enrich.
This diagram scrolls sideways on a narrow screen.
Name the rule, the field, and the failure
Give each rule a stable name. The name is what the log stores. The predicate is the test. The failure action is what happens to the record or the file. Those three travel together. A predicate that only lives in code, with a log line that says “failed validation,” cannot be repaired, because nobody can see which test fired.
The failure action is one of a short list you write in advance: hold this row, stop the file, or accept the row and record a known issue. “Fix it during the run” is not on the list. A fix during the run is an edit with no owner. If the value can be repaired by a transform that was already on the field mapping, that transform belongs on the mapping row and runs before this check. The check then sees the transformed value and still records the rule name.
A missing optional field is not a failure. The dictionary says so. Do not add a rule that contradicts the entry. If the storefront cannot tolerate the empty value, change the dictionary obligation first, version it, and then add the rule. The metadata quality checklist is the pass over those obligations. This page is the shape of a single predicate, not a second list of required fields.
This table scrolls sideways on a narrow screen.
| Part | A usable shape | Not a rule |
|---|---|---|
| Name | public-name-present | The usual check |
| Predicate | public_name is non-empty after the mapping transform | The name looks fine |
| On failure | Hold the row and keep the source cell | Correct it quietly and continue |
| Version | The dictionary version the predicate was written against | Whatever is in production today |
Keep identifier collisions on their own page
A rule may say that a public handle appears once in the set you are checking. That is a predicate. It is not a decision about which record survives. When the same handle names two different things, or two rows claim one record, classify the failure with the guide to duplicate, missing, and conflicting records. The validation log can say “uniqueness failed” and point at that hold. It should not merge the rows.
The same split applies to a conflict of values. The rule detects that two filled values disagree. The ownership rule decides which copy may commit. Detection and permission are different sentences. Write both, in their own places, and have the validation result cite them.
Do not encode a similarity percentage in a rule unless you have a written method and a test you can repeat. This page will not supply a number. A number without a method becomes a fake precision, and two runs will not match.
Change a rule where the next release can see it
When a rule is wrong, change the rule and version it. Records that failed yesterday and pass today need the rule name and the version in the log, or the change looks like a silent data repair. The quality checklist makes the same point about a field that passes because the rule changed. Say it on the rule itself: previous text stays readable for as long as a log line cites it.
A release re-runs the rules of a named version. It does not draft new predicates at the door. The release page already refuses that. If the dictionary changed after you froze the rule version, either repeat the run against the new version or leave the dictionary change out of this release.
What this page does not claim
Best Practice 6 does not define “fit for purpose” for a shop, a library, or a media catalog. It does not set a completeness ratio. The predicates, the failure list, and the ban on merging inside the check are the publication’s method. A known issue that you accept on purpose still has to be written down. Accepting it in silence is not the same as stating it.
When a validation rule should fire
When can a failed row continue?
When the failure action you wrote in advance is "accept and record the issue," and the issue text names the rule. Any other continuation is an improvised pass.
When needed: A defect you have already decided the catalog may carry, with the reason attached.
When do you stop the whole file?
When the mapping version does not recognize the file shape, or when a rule you marked as file-level fails. A single bad row uses the row-level action instead, so one defect does not hide the rest of the file.
When needed: A header change, or a rule that is about the set rather than one record.
When is a new rule not allowed in this release?
When the release scope is already frozen. Add the rule to the next version and repeat validation, or take it out of this set. A predicate invented at the door was not the check you told the log you ran.
When needed: A defect discovered after scope was frozen.