Skip to main content

Validating against schema & BREX

A data module passes through two separate checks before it is official. First you check that the file is correct XML and matches its S1000D schema. Then you check that the content obeys the project's business rules, recorded in a BREX data module. The s1kd-tools toolchain gives you one command for each check: s1kd-validate and s1kd-brexcheck.

Two checks, two questions

s1kd-validate answers "Is this a well-formed S1000D file?" s1kd-brexcheck answers "Does this file follow my project's rules?" A data module can pass the first and fail the second. You usually run both.

Examples are illustrative

The commands and the data module filename on this page are examples. Tool names and option flags are verified against the s1kd-tools documentation (see Sources). The data module code DMC-MYPRJ-A-00-00-00-00A-040A-D_000-03_EN-CA is a sample, not a real product.

Step 1 — Validate against the schema​

s1kd-validate checks whether a CSDB object is valid XML and whether it is valid against its own S1000D schema. The schema reference lives inside the data module, so you do not normally name a schema on the command line.

# Example only — illustrative data module filename.
s1kd-validate DMC-MYPRJ-A-00-00-00-00A-040A-D_000-03_EN-CA.XML

If the file is clean, the tool prints nothing and exits with status 0. If the file is malformed or breaks its schema, the tool reports the problem and exits with a non-zero status. A few useful options:

OptionWhat it does
-v, --verboseReport success as well as failure
-q, --quietPrint nothing; use the exit status only
-f, --filenamesList the names of invalid files only
-x, --xmlWrite the report as XML
-T, --summaryPrint validation statistics
-s, --schema <path>Override the object's default schema

The exit status lets you wire s1kd-validate into a script or a CI pipeline:

Exit statusMeaning
0No errors found
1One or more objects are malformed or invalid
2Schema cache ran out of memory
3A specified schema could not be read
Validate the whole CSDB at once

s1kd-validate accepts many objects on one command line, and the -q flag makes it silent except for the exit status. That pair is handy for a pre-commit hook: validate every data module, and fail the commit if any object is invalid.

Step 2 — Check against the BREX​

A file can be valid XML and still break a project rule — for example, by using an information code the project has banned, or by leaving out an element the project requires. The schema cannot catch this, because the rule is specific to the project, not to S1000D as a whole. That is the job of s1kd-brexcheck.

s1kd-brexcheck validates CSDB objects using the context, SNS, and notation rules of one or more BREX data modules. By default it finds the BREX each object references and checks the object against it.

# Example only — illustrative data module filename.
s1kd-brexcheck DMC-MYPRJ-A-00-00-00-00A-040A-D_000-03_EN-CA.XML

Common options:

OptionWhat it does
-b, --brex <brex>Check against a named BREX; repeat for several
-B, --default-brexCheck against the built-in S1000D default BREX only
-S, --snsCheck Standard Numbering System rules
-n, --notationsCheck notation rules
-c, --valuesCheck the object values named in context rules
-l, --layeredFollow layered (chained) BREX references
-v, --verbosePrint explicit test results
-x, --xmlWrite the report as XML

The exit status reports what happened:

Exit statusMeaning
0No BREX errors found
1Some objects had BREX errors
2An object could not be read
3A referenced BREX module was not found
4An unsupported XPath version was requested
5The memory limit was exceeded
XPath version

s1kd-brexcheck evaluates BREX context rules as XPath. By default it supports XPath 1.0, with partial support for EXSLT functions. Write project rules with this in mind.

What a BREX failure means​

A BREX failure does not mean the file is broken XML. It means the content breaks a rule the project chose to enforce. The data module is still a valid S1000D file; it is simply not allowed under this project's business rules.

For each violation, s1kd-brexcheck reports three things:

  1. The objectUse message — the plain-language note the BREX author wrote to explain the rule. This tells you why the rule exists.
  2. The line number in the data module where the rule was broken.
  3. A representation of the invalid XML tree — the part of the content that triggered the failure.

Together these point you straight to the offending element and tell you the project's intent. To fix a BREX failure you change the content so it obeys the rule — for example, remove a forbidden element, add a required attribute, or use a permitted value. You do not change the schema.

Read the message, not just the line

The objectUse text is the most useful part of the report. It is the rule author speaking directly to you. If a check keeps failing, the message usually explains the project decision behind the rule — see Business rules & BREX for how those decisions are recorded.

Putting both checks together​

A typical "make it official" sequence runs the two tools in order. Schema first, because there is no point checking business rules on a file that is not even valid XML; rules second, because that is where project-specific problems show up.

# Example only — illustrative data module filename.
s1kd-validate   DMC-MYPRJ-A-00-00-00-00A-040A-D_000-03_EN-CA.XML
s1kd-brexcheck  DMC-MYPRJ-A-00-00-00-00A-040A-D_000-03_EN-CA.XML
ToolQuestion it answersA failure means
s1kd-validateIs the file valid XML and valid S1000D?Wrong structure — fix syntax or schema conformance
s1kd-brexcheckDoes the file follow the project's rules?Wrong content choice — fix to match the BREX

Summary​

  • Validate every data module twice: against its schema, then against its BREX.
  • s1kd-validate checks XML well-formedness and S1000D schema conformance.
  • s1kd-brexcheck checks content against the context, SNS, and notation rules of a BREX data module.
  • A BREX failure means the file is valid S1000D but breaks a project rule; the report gives the objectUse message, the line number, and the offending XML.
  • Both tools use exit status, so they fit cleanly into a script or CI pipeline.

Sources​