Validation
One of the benefits of working in XML is that you can validate your content against established Validation Rules. So you can be confident that your topics have a valid XML structure that is consistent and can be exported easily if needed.
Depending on your preferences, you can either:
-
Set Paligo to validate your content automatically whenever you save a topic,Turn Validation On or Off.
-
Manually validate your content by using the manual validation feature in the Toolbar.
When you validate your content, Paligo examines the structure of your topic and checks that it complies with the validation rules. If the content:
-
Complies with the validation rules, you can save the topic.
-
Breaks the rules, Paligo displays an error message and also provides information in the Validation section in the side panel. You will need to fix the errors before the topic can be saved (or disable the validation rules that are being broken). If you have tried to save a topic, but Paligo has detected a problem and displayed a validation error message, see Invalid Content.
 |
The Validation Panel provides information about the error to help you solve it.
Paligo has three different sets of rules that you can apply:
-
The content must be valid XML and comply with the Paligo XML Schema Validation. Always have this enabled as a minimum, as this will help to make sure your topics are valid XML at least.
-
The content must also comply with the Paligo Recommended Rules.
-
The content must also comply with some Schematron Rules. To use your own Schematron file to apply extra validation rules, see Upload Schematron Files to Paligo.
By default, Paligo checks that a topic complies with the Paligo Recommended Rules and Paligo XML Schema Validation before it saves the content.
You can choose to use all three sets of rules, any combination of the rules or no rules at all (not recommended). The option to disable these features is designed for those occasions where you need to save the content and will fix the validation problems later. For example, if an import produces invalid content or the person who encounters the validation error is not the person who will fix it.
If you have validation turned on, Paligo will not save the topic until it complies with the rules. To choose which rules should be used and when they should apply, either when you try to save and / or when you validate manually, see Turn Validation On or Off.
Important
We strongly recommend that you have Paligo XML Schema Validation and Paligo Recommended Rules enabled in your topics. Disabling them could mean that features in Paligo do not work as intended and Paligo may run slowly.
Paligo XML is based on DocBook 5.1 XML, which is a well-established XML standard for technical documentation. You can find out about it, and its rules, at www.docbook.org. There is a reference section where you can look up elements and find out where they can be used. However, be aware that Paligo XML is not identical to DocBook XML.
The Paligo XML schema rules specify what elements can be used, where they can be used, and what order they need to appear in. For example, they define that a <step> element has to be a child (descendant) of a list element, such as <itemizedlist>. There are also rules about the element attributes.
The Paligo editor is designed to guide you so that you only insert elements where they are valid. For example, you cannot add a table inside a paragraph. However, if you turn validation off, it is possible to create invalid structures that will break the Paligo XML rules.
Typically, if you have a topic that will not save due to a Paligo XML validation error, it is because the structure of the topic is invalid or there are Invalid Content. To save the topic, you will need to either:
-
Edit the topic and fix the problems
-
Turn off Paligo XML schema validation (not recommended).
The Paligo recommended rules are an extra set of validation rules that you can use. They are enabled by default, and are designed to help writers avoid creating topics that are too long. This is more in line with best practice for topic-based authoring. But the Paligo recommended rules are not hard rules and you can disable them if needed (see Turn Validation On or Off).
However, please be aware that topics containing an excessive amount of content in one topic could result in performance issues in the browser.
The Paligo recommended rules are:
-
A topic should contain a maximum of 10 sections.
This rule helps to ensure best practice for topic-based authoring, as well as browser performance issues if you were to create extremely long topics.
Note
This rule only applies to
sectionelements created directly in the topic. If you create subsections by inserting other topics as embedded components, they do not count against these rules.
If you have the Paligo recommended rules turned on, and your content breaks the rules, Paligo will display an error message when you try to save the topic. You will only be able to save your topic if you:
-
Edit your topic so that it complies with the rules
-
Turn the Paligo recommended rules validation off. You can also do this temporarily and then turn them back on later. But if your topic breaks these rules, it is a sign that your content could be better structured by nesting smaller components in the structure view or as embedded components.
Schematron is a language that you can use to create customized validation rules for your Paligo topics. This is useful when you want to add extra rules, for example, you could create a rule that each topic can only contain one procedure.
So the rules of Schematron are up to you! You can define the rules to suit your content requirements, and you can use them in addition to, or instead of, the Paligo XML schema rules and Paligo recommended rules.
To find out about creating a Schematron file, uploading it to Paligo, and enabling Schematron validation, see Custom Validation Rules with Schematron.
If you are trying to save a topic and get a Schematron error, it means the topic's content is breaking the rules set in a Schematron file. You can either:
-
Edit your topic and fix the problem that is breaking the rules in the Schematron file. To do this, you will need to find out what rules are set in the Schematron file.
You could ask whoever is responsible for uploading and maintaining the Schematron file. If that is not possible, you can ask someone with Schematron experience to view the Schematron file and figure out what rules are in place. The location of the Schematron file is explained in Upload Schematron Files to Paligo.
Note
It is possible to have multiple types of validation enabled at the same time, for example, Paligo XML Schema validation and Schematron validation. In this scenario, a topic will only save when it complies with all of the rules.
Your content is validated by Paligo when you save a topic or when you Validate Content Manually. If Paligo detects that your content breaks the applied rules, it displays an error message, adds a red highlight to the elements and a description is displayed in the Validation panel. The most common reasons for a topic being invalid are described in this section.
An error message appears to inform about the validation errors. Paligo also adds a red highlight to the elements that contain invalid content and a description is displayed in the Validation panel to the right.
Paligo XML schema validation errors are usually due to the incorrect positioning or ordering of elements. To make your topic valid, check that the content follows the Paligo XML Schema Validation which is based on DocBook, see DocBook.
Invalid attributes and attribute values can also result in Paligo XML schema validation errors. To check for those, see Breaks the Rules for Attribute Values.
Paligo's recommended rules are an extra set of rules that are included as a Schematron file. They are optional, and you can Turn Validation On or Off.
To make the topic valid so that it can be saved, edit the topic so that it complies with the Paligo Recommended Rules. Alternatively, you can turn the rules off.
If you have a Schematron validation error, it means that there are custom rules in place in your Paligo instance. These rules are set in a Schematron file. To find out what rules your content is breaking, you will need to find out what rules the Schematron defines.
You could ask whoever is responsible for uploading and maintaining the Schematron file. If that is not possible, you can ask someone with Schematron experience to view the Schematron file and figure out what rules are in place. The location of the Schematron file is explained in Upload Schematron Files to Paligo.
A topic can be invalid because it contains attributes that have values that are not supported. This can happen when:
-
An attribute value is added in the source code editor
-
Unsupported characters in your attribute values.
For example, if you have an orderedlist element, you can add a continuation attribute. In the Paligo editor, you can only select valid values for this, either: continues or restarts. But in the source code editor, you could set the value to "stop", which is invalid.
Note
Invalid attribute values are part of the Paligo XML Schema Validation.
To fix invalid attribute values:
-
For each attribute, use the Paligo editor to look at the values that are in place, and also the options that can be selected for the values. These are valid values for the attribute.
-
Use the Source Code Editor to look at the values that are set for your attributes.
If there are any invalid values, remove them and then use the Paligo editor to add a valid value.
-
Select Save.
Schematron is a language that you can use to create customized validation rules for your Paligo topics. This is useful when you want to add extra rules, for example, you could create a rule that each topic can only contain one procedure.
Note
Schematron rules are additional rules that you can apply to the Paligo XML content model, which is based on DocBook. You cannot use it to add custom elements that are not supported by Paligo XML/DocBook.
To use Schematron rules in Paligo:
-
Create a Schematron file named:
custom.schYou can do this in any code editor or text editor, but you will need an understanding of how Schematron works. You can find out more at the official Schematron website. Note that the file must be named
custom.schor it will not work in Paligo.When you create a "custom.sch" Schematron file, you should consider:
-
The structure of your Paligo content and the patterns in that content
-
The Schematron rules you create are applied to each topic individually in Paligo.
-
When Schematron validation is enabled, Paligo checks the content of a topic against the rules in the Schematron file. This happens when the you attempt to save the topic. If the topic's content breaks the rules, Paligo will display an error notification and will not save. You can then:
-
Edit your topic and fix the problem that is breaking the rules in the Schematron file. To do this, you will need to find out what rules are set in the Schematron file.
You could ask whoever is responsible for uploading and maintaining the Schematron file. If that is not possible, you can ask someone with Schematron experience to view the Schematron file and figure out what rules are in place. The location of the Schematron file is explained in Upload Schematron Files to Paligo.
Note
It is possible to have multiple types of validation enabled at the same time, for example, Paligo XML Schema validation and Schematron validation. In this scenario, a topic will only save when it complies with all of the rules.
If you have created a Schematron file, you can upload it to your Paligo instance. When it is in place, your Paligo authors will be able to open a topic, enable Schematron validation and Paligo will use the custom rules from your Schematron file.
If the topic's content breaks the Schematron rules, a notification message is displayed and the topic will not save. The Validation side panel shows details about why the content breaks the rules, see Invalid Content.
It is a good idea to document the rules of your Schematron file so that writers can refer to it. If they create topics that break the rules, Paligo will generate an error message. The writers will then need to correct the topic so that it complies with the rules but to do that, they will need to know what the rules are.
The first time that you upload a Schematron file, you have to create a folder structure for it. Once the folders are in place you only replace the existing file.
Note
It is important that both the schematron file and folders are named with lowercase letters.
To create and upload a schematron file to Paligo for the first time:
-
Connect to your Paligo instance via WebDAV, see WebDAV Access to your Paligo Instance Folders.
-
Create a new folder in the root folder called schematron.
-
Inside that folder, create a folder called editor
-
Upload your
custom.schSchematron file into the editor folder.
-
Let your Paligo writers know that the Schematron file is uploaded and they can now Turn Validation On or Off.
Paligo can check that your content is valid either manually or before the topic is saved to the database. But these checks will only take place if one or more of the validation features are turned on for your topics.
If you want to enable validation (recommended), you can choose which Validation Rules Paligo should use. You can also choose when the rules are applied, either when you save a topic, during a manual validation or both.
To turn validation on or off and choose which rules are used:
-
Select the topic or component in the Content Manager to open it in the Editor.
Alternatively, you can Create a Topic and edit that.
-
Select Editor settings in the toolbar.
-
Paligo displays the Editor Settings dialog.
The editor settings are global and will apply to all the topics and publications that you work with. The settings will only be applied to your user account.
-
Select the General tab.
-
Set your validation rules In the Documentation Validation section.
The options are:
-
Paligo XML schema validation
Complies with the validation rules, you can save the topic.
-
Breaks the rules, Paligo displays an error message and also provides information in the Validation section in the side panel. You will need to fix the errors before the topic can be saved (or disable the validation rules that are being broken). If you have tried to save a topic, but Paligo has detected a problem and displayed a validation error message, see Invalid Content.
The content must also comply with the Paligo Recommended Rules.
-
Schematron validation
The content must also comply with some Schematron Rules.
For each type of rule:
-
Check the Save box to turn the type of validation on when saving a topic. Paligo will test that your content complies with the selected rules whenever you try to save a topic. Clear the box to turn the validation off when saving a topic.
-
Check the Validate box to use that type of validation when you Validate Content Manually. Paligo will test whether your content complies with the selected rules whenever you use the validate option in the Editor's toolbar. Clear the box to turn the validation off.
-
Clear the Save and Validate boxes to disable validation. We strongly recommend that you have Paligo XML schema validation enabled as this will prevent you from saving invalid content. Paligo can only publish content that has a valid structure. To learn more, see Validation Rules.
Note
You can use any combination of these validation rules or you can disable validation completely if you want. We recommend that you always have Paligo XML schema validation enabled as a minimum, as this will help to make sure your topics are valid XML at least.
-
-
Select Save Settings.
Paligo validates your content automatically when you save a topic, but you can also start the validation process yourself, at any time. The rules that are used for the validation vary, depending on what you have in place in the editor settings. You can use the same rules for validation on save and manual validation, or you can apply different rules for each, see Turn Validation On or Off.
 |
The Save checkboxes are for the rules that apply when saving a topic.
Note
If you want to save your topic and come back to fix the problems later, you will need to turn the validation off. You cannot save a topic that has invalid content while the validation rules (that it has broken) are turned on.
To find out more, see Turn Validation On or Off.
To validate your content manually:
-
Select the topic or component in the Content Manager to open it in the Editor.
Alternatively, you can Create a Topic and edit that.
-
Select Validate the document in the Toolbar.
Paligo will check that your content is valid based on the rules that are set for manual validation (in the topic editor settings). These are the rules that have Validate checked.
If your content has broken any of the validation rules, Paligo displays an error message. It also provides information about the problems in the Validation panel, so that you know what parts of the content you need to fix. Learn more, see Invalid Content.