How to configure rules validation?
Overview
Quark Author provides configurable settings to enable or disable authoring controls based on document types. These configurations help maintain document integrity by preventing unauthorized modifications. This document details the configuration, rules, and behavior of the rules validation feature.
Setup
To use the rules validation feature in Quark Author, you need to configure the system by creating two essential files and enabling a feature flag. Follow the steps below to set it up:
Feature Flag: Enable the feature by setting the following flag in the
qaservicecontainer:feature.rules.validation=true
rules.json: This file defines the validation rules for restricting elements and commands.- Default Path:
Home/sysinternals/qaservice/conf/ - Create this file in the specified directory with your rule definitions (see Section 3.4 for sample rules configuration).
- Default Path:
ruleset.json: This file specifies the rulesets that determine where the rules apply.- Default Path:
Home/sysinternals/qaservice/conf/<Collection-With-Content-Type-Name>/ - Replace
<Collection-With-Content-Type-Name>with the appropriate collection name for your content type, and place the file there (see Section 4.4 for sample ruleset configuration).
- Default Path:
Configurable Base Path: The base path for these configuration files (
Home/sysinternals/qaservice/conf/) is configurable. You can override the default path by setting the environment variableconfigs.collection.pathin theqaservicecontainer to your sysinternals collection.
Once both files are in place, the feature flag is enabled, and the base path is correctly configured (if customized), Quark Author will apply the command restrictions as defined.
Important Note: When configuring these files, ensure that values such as element names, types, and metadata align with the document’s XML structure. This ensures the rules and ruleset match the document’s structure and work as expected.
Rules Definition
Rules define the validation logic for restricting elements and commands in the document.
Key Rule Parameters
validationType: Specifies the type of validation (e.g.,"ELEMENT").element: Defines the target element (e.g.,"image","table").elementType: Type of the element (e.g.,"callout"). Use""if not applicable.maxOccurrence: Specifies the maximum allowed instances of the element (e.g.,"2"). Use"0"to disallow entirely.disableCommands: List of commands to disable. Refer to Section 5: Validation Framework – Covered & Uncovered Commands for supported and unsupported commands.
Disabling Elements with maxOccurrence
Elements such as tables, regions, citations, tags, and paragraphs can be restricted using maxOccurrence. When the limit is reached, associated UI options become unavailable, even if disableCommands is empty.
Examples
Disable Table Type (table-test)
{
"validationType": "ELEMENT",
"element": "table",
"elementType": "table-test",
"maxOccurrence": "2"
}
Disable Region Type (Callout)
{
"validationType": "ELEMENT",
"element": "region",
"elementType": "callout",
"maxOccurrence": "5"
}
Disable Paragraph Type (Long Quote)
{
"validationType": "ELEMENT",
"element": "p",
"elementType": "lq",
"maxOccurrence": "0"
}
Disable Tag Type (Country)
{
"validationType": "ELEMENT",
"element": "tag",
"elementType": "country",
"maxOccurrence": "0"
}
Disable Citations
{
"validationType": "ELEMENT",
"element": "refnote",
"elementType": "citation",
"maxOccurrence": "2"
}
Disabling Commands Without maxOccurrence
For commands not tied to element counts, use disableCommands without maxOccurrence.
Example
{
"RULE-PINNING-COMPONENT-NOT-ALLOWED": {
"validationType": "ELEMENT",
"disableCommands": ["pinReference", "unpinReference"]
}
}
Sample rules.json
{
"RULE-BOLD-NOT-ALLOWED": {
"validationType": "ELEMENT",
"element": "b",
"elementType": "",
"maxOccurrence": "0",
"disableCommands": ["bold"]
},
"RULE-ITALIC-NOT-ALLOWED": {
"validationType": "ELEMENT",
"element": "i",
"elementType": "",
"maxOccurrence": "0",
"disableCommands": ["italic"]
},
"RULE-UNDERLINE-NOT-ALLOWED": {
"validationType": "ELEMENT",
"element": "u",
"elementType": "",
"maxOccurrence": "0",
"disableCommands": ["underline"]
},
"RULE-STRIKE-NOT-ALLOWED": {
"validationType": "ELEMENT",
"element": "strike",
"elementType": "",
"maxOccurrence": "0",
"disableCommands": ["strike"]
},
"RULE-COUNTRY-TAG-NOT-ALLOWED": {
"validationType": "ELEMENT",
"element": "tag",
"elementType": "country",
"maxOccurrence": "0",
"disableCommands": []
},
"RULE-PARA-LONG-QUOTE-VALIDATOR": {
"validationType": "ELEMENT",
"element": "p",
"elementType": "lq",
"maxOccurrence": "2",
"disableCommands": []
},
"RULE-SMART-TABLE-ONE-ALLOWED": {
"validationType": "ELEMENT",
"element": "table",
"elementType": "",
"maxOccurrence": "1",
"disableCommands": ["insertTable"]
},
"RULE-REGION-VALIDATOR": {
"validationType": "ELEMENT",
"element": "region",
"elementType": "",
"maxOccurrence": "2",
"disableCommands": []
},
"RULE-CALLOUT-VALIDATOR": {
"validationType": "ELEMENT",
"element": "region",
"elementType": "callout",
"maxOccurrence": "1",
"disableCommands": []
},
"RULE-TABLE-TEST-1-VALIDATOR": {
"validationType": "ELEMENT",
"element": "table",
"elementType": "test-1",
"maxOccurrence": "4",
"disableCommands": []
},
"RULE-NUMBERED-LIST-NOT-ALLOWED": {
"validationType": "ELEMENT",
"element": "ol",
"elementType": "",
"maxOccurrence": "0",
"disableCommands": ["numberedlist"]
},
"RULE-VIDEO-ONE-ALLOWED": {
"validationType": "ELEMENT",
"element": "bodydiv",
"elementType": "video",
"maxOccurrence": "1",
"disableCommands": ["insertVideo"]
},
"RULE-IMAGE-ONE-ALLOWED-VALIDATOR": {
"validationType": "ELEMENT",
"element": "image",
"elementType": "",
"maxOccurrence": "1",
"disableCommands": [
"insertImage",
"localimage",
"insertFigure",
"localfigure",
"insertExcelChart"
]
},
"RULE-ATTACHMENT-ONE-ALLOWED": {
"validationType": "ELEMENT",
"element": "object",
"elementType": "attachment",
"maxOccurrence": "1",
"disableCommands": ["insertAttachment", "insertLocalAttachment"]
},
"RULE-CROSS-REFERENCE-NOT-ALLOWED": {
"validationType": "ELEMENT",
"element": "xref",
"elementType": "",
"maxOccurrence": "0",
"disableCommands": [
"link",
"insertXref",
"insertDocXref",
"insertInterDocXref"
]
},
"RULE-FOOTNOTE-ONE-ALLOWED": {
"validationType": "ELEMENT",
"element": "refnote",
"elementType": "footnote",
"maxOccurrence": "1",
"disableCommands": ["insertFootnote"]
},
"RULE-ENDNOTE-ONE-ALLOWED": {
"validationType": "ELEMENT",
"element": "refnote",
"elementType": "endnote",
"maxOccurrence": "1",
"disableCommands": ["insertEndnote"]
},
"RULE-CITATION-ONE-ALLOWED": {
"validationType": "ELEMENT",
"element": "refnote",
"elementType": "citation",
"maxOccurrence": "1",
"disableCommands": ["insertCitation"]
},
"RULE-TABLE-NOTE-ONE-ALLOWED": {
"validationType": "ELEMENT",
"element": "refnote",
"elementType": "table-note",
"maxOccurrence": "1",
"disableCommands": ["insertTableNote"]
},
"RULE-TABLE-CONTEXT-MENU-NOT-ALLOWED": {
"validationType": "ELEMENT",
"disableCommands": [
"tableDelete",
"replaceTableFromServer",
"createTableComponent",
"rowInsertBefore",
"rowInsertAfter",
"columnInsertBefore",
"columnInsertAfter",
"rowDelete",
"columnDelete",
"tableTitle",
"tableDesc",
"toggleHeaderRow",
"cellMerge",
"cellHorizontalSplit",
"cellVerticalSplit",
"convertToFormalTable",
"addTitleToFormalTable",
"addDescToFormalTable",
"addParaAfterTable"
]
},
"RULE-SECTION-NOTE-ONE-ALLOWED": {
"validationType": "ELEMENT",
"element": "refnote",
"elementType": "section-note",
"maxOccurrence": "1",
"disableCommands": ["insertSectionNote"]
}
}
Ruleset Definition
Rulesets determine where validation rules apply within the document structure.
Key Selector Parameters
contentRules: Root object containing all selectors.selectors: Array of selector objects.elementName: Target element name (e.g.,"body","title",table,region).elementType: Optional type (e.g.,"callout"). Use""if not applicable.elementTypePaths: Hierarchical path to the element (e.g.,["/body/bodydiv"]).sectionTypePath: Document section path (e.g.,"/document/section/subsection").validationRuleSets: Array of rule sets.ruleSetId: Unique identifier.validationConditions: Conditions to be validated specified for the selector. Empty ([]) means always applied. Refer to Section 4.3 for more detail.validationRules: List of rule IDs.
Actual Path: sectionTypePath/elementTypePaths/elementName[elementType]
Using elementTypePaths
Use elementTypePaths to target nested elements.
Example: Title Inside a Figure
{
"contentRules": {
"selectors": [
{
"elementName": "title",
"elementType": "",
"elementTypePaths": ["/body/bodydiv"],
"sectionTypePath": "/document/section/subsection",
"validationRuleSets": [
{
"ruleSetId": "rule-set-1",
"validationRules": [
"RULE-INSERT-IMAGE-NOT-ALLOWED",
"RULE-INSERT-TABLE-NOT-ALLOWED"
]
}
]
}
]
}
}
Note
- Use
elementTypePathsto narrow scope (e.g.,"/body"or"/title").
Using validationConditions
Conditions restrict rule application based on metadata or attributes.
Parameters
conditionType:"META"or"ATTRIBUTE".scope: Defines where the condition is checked—"SELF","SECTION", or"ROOT".SELF: Evaluates the condition on the element itself (the one specified in the selector).SECTION: Evaluates the condition on the parent section containing the element.ROOT: Evaluates the condition on the root of the document.
name: The field name to check (e.g.,"Status","audience").possibleValues: The allowed values for the field (e.g.,["Review"],["Internal"]).parentMetaHierarchy: An optional path to locate nested metadata fields (used with"META"conditions).
Example: Apply Rules When Status is in Review Status
{
"contentRules": {
"selectors": [
{
"elementName": "body",
"sectionTypePath": "/document/section/subsection",
"validationRuleSets": [
{
"ruleSetId": "rule-set-2",
"validationConditions": [
{
"conditionType": "ATTRIBUTE",
"scope": "ROOT",
"name": "Status",
"possibleValues": ["Review"]
}
],
"validationRules": ["RULE-INSERT-IMAGE-NOT-ALLOWED"]
}
]
}
]
}
}
Sample ruleset.json
{
"contentRules": {
"selectors": [
{
"elementName": "title",
"elementType": "",
"sectionTypePath": "/document/section",
"validationRuleSets": [
{
"ruleSetId": "rule-set-1",
"validationConditions": [
{
"conditionType": "META",
"scope": "SECTION",
"name": "audience",
"possibleValues": ["Internal"]
}
],
"validationRules": [
"RULE-BOLD-NOT-ALLOWED",
"RULE-ITALIC-NOT-ALLOWED",
"RULE-UNDERLINE-NOT-ALLOWED",
"RULE-STRIKE-NOT-ALLOWED"
]
}
]
},
{
"elementName": "body",
"elementType": "",
"sectionTypePath": "/document/section",
"validationRuleSets": [
{
"ruleSetId": "rule-set-1",
"validationConditions": [],
"validationRules": [
"RULE-REGION-VALIDATOR",
"RULE-CALLOUT-VALIDATOR",
"RULE-TABLE-TEST-1-VALIDATOR",
"RULE-PARA-LONG-QUOTE-VALIDATOR",
"RULE-NUMBERED-LIST-NOT-ALLOWED",
"RULE-CROSS-REFERENCE-NOT-ALLOWED",
"RULE-FOOTNOTE-ONE-ALLOWED",
"RULE-ENDNOTE-ONE-ALLOWED",
"RULE-CITATION-ONE-ALLOWED",
"RULE-SECTION-NOTE-ONE-ALLOWED"
]
}
]
},
{
"elementName": "section",
"elementType": "section",
"sectionTypePath": "/document/section",
"validationRuleSets": [
{
"ruleSetId": "rule-set-1",
"validationConditions": [
{
"conditionType": "ATTRIBUTE",
"scope": "ROOT",
"name": "Status",
"possibleValues": ["Draft"]
},
{
"conditionType": "ATTRIBUTE",
"scope": "ROOT",
"name": "Workflow",
"possibleValues": ["Demo Workflow"]
}
],
"validationRules": [
"RULE-VIDEO-ONE-ALLOWED",
"RULE-IMAGE-ONE-ALLOWED-VALIDATOR"
]
}
]
},
{
"elementName": "region",
"elementType": "",
"elementTypePaths": [],
"sectionTypePath": "/document/section",
"validationRuleSets": [
{
"ruleSetId": "rule-set-1",
"validationConditions": [
{
"conditionType": "META",
"scope": "SELF",
"name": "keywords",
"parentMetaHierarchy": "",
"possibleValues": [""]
}
],
"validationRules": ["RULE-ATTACHMENT-ONE-ALLOWED"]
}
]
},
{
"elementName": "table",
"elementType": "",
"elementTypePaths": [],
"sectionTypePath": "/document/section",
"validationRuleSets": [
{
"ruleSetId": "rule-set-1",
"validationConditions": [],
"validationRules": [
"RULE-TABLE-CONTEXT-MENU-NOT-ALLOWED",
"RULE-TABLE-NOTE-ONE-ALLOWED"
]
}
]
},
{
"elementName": "body",
"elementType": "",
"elementTypePaths": [],
"sectionTypePath": "/document/section/subsection",
"validationRuleSets": [
{
"ruleSetId": "rule-set-1",
"validationConditions": [],
"validationRules": [
"RULE-SMART-TABLE-ONE-ALLOWED",
"RULE-COUNTRY-TAG-NOT-ALLOWED"
]
}
]
}
]
}
}
Rules Validation – Covered & Uncovered Commands
The table below enumerates the commands that are supported by the rules validation feature, as well as those that are currently excluded from its scope.
| CKEditor Commands | Occurrence (Yes/No) | Disable (Yes/No) |
|---|---|---|
| bold | Yes | Yes |
| italic | Yes | Yes |
| underline | Yes | Yes |
| strike | Yes | Yes |
| subscript | Yes | Yes |
| superscript | Yes | Yes |
| numberedlist | Yes | Yes |
| bulletedlist | Yes | Yes |
| insertTableNote | Yes | Yes |
| insertSectionNote | Yes | Yes |
| insertFootnote | Yes | Yes |
| insertEndnote | Yes | Yes |
| insertFigure | Yes | Yes |
| insertImage | Yes | Yes |
| localimage | Yes | Yes |
| localfigure | Yes | Yes |
| insertExcelTable | Yes | Yes |
| insertExcelChart | Yes | Yes |
| insertDocXref | Yes | Yes |
| insertInterDocXref | Yes | Yes |
| insertXref | Yes | Yes |
| insertTable | Yes | Yes |
| link | Yes | Yes |
| createRegionComponent | Yes | Yes |
| insertVideo | Yes | Yes |
| insertAttachment | Yes | Yes |
| insertLocalAttachment | Yes | Yes |
| indent | No | Yes |
| outdent | No | Yes |
| showTableAschart | No | Yes |
| enableTracking | No | Yes |
| highlighting | No | Yes |
| previousChange | No | Yes |
| nextChange | No | Yes |
| acceptChange | No | Yes |
| rejectChange | No | Yes |
| acceptAndMoveToNext | No | Yes |
| rejectAndMoveToNext | No | Yes |
| acceptAllChanges | No | Yes |
| rejectAllChanges | No | Yes |
| addComment | No | Yes |
| deleteComment | No | Yes |
| previousComment | No | Yes |
| nextComment | No | Yes |
| toggleComments | No | Yes |
| createCitation | No | Yes |
| convertReferenceCitationToInline | No | Yes |
| insertFigureTitle | No | Yes |
| insertFigureDescription | No | Yes |
| deleteFigure | No | Yes |
| editImageComponentReference | No | Yes |
| pinToLatestVersion | No | Yes |
| editReference | No | No |
| createBranch | No | No |
| switchBranch | No | No |
| saveReference | No | No |
| saveAndCloseReference | No | No |
| discardReference | No | No |
| removeReference | No | No |
| pinReference | No | Yes |
| unpinReference | No | Yes |
| updateReferenceRevision | No | No |
| closeReference | No | No |
| showReferenceActions | No | No |
| updateXref | No | Yes |
| updateAllXref | No | Yes |
| removeXref | No | Yes |
| editXref | No | Yes |
| tableDelete | No | Yes |
| replaceTableFromServer | No | Yes |
| createTableComponent | No | Yes |
| rowInsertBefore | No | Yes |
| rowInsertAfter | No | Yes |
| columnInsertBefore | No | Yes |
| columnInsertAfter | No | Yes |
| rowDelete | No | Yes |
| columnDelete | No | Yes |
| tableTitle | No | Yes |
| tableDesc | No | Yes |
| toggleHeaderRow | No | Yes |
| cellMerge | No | Yes |
| cellHorizontalSplit | No | Yes |
| cellVerticalSplit | No | Yes |
| convertToFormalTable | No | No |
| addTitleToFormalTable | No | No |
| addDescToFormalTable | No | No |
| addParaAfterTable | No | Yes |
| removeLink | No | Yes |
| editLink | No | Yes |
| insertRegionTitle | No | Yes |
| removeRegion | No | Yes |
| deleteRegion | No | Yes |
| insertParaAfterRegion | No | Yes |
| replaceRegionFromServer | No | Yes |
| pasteFromServer | No | Yes |
| toggleProofReading | No | Yes |
| dialogBasedSpellChecking | No | Yes |
| setProofingLanguage | No | Yes |
| find | No | Yes |
| insertSpecialCharacter | No | Yes |
| viewXML | No | Yes |
| editStatus | No | No |
| toggleElementDOM | No | No |
| insertVideoTitle | No | Yes |
| insertVideoDescription | No | Yes |
| previewVideo | No | Yes |
| deleteVideo | No | Yes |
| replacePoster | No | Yes |
| addParaAfterVideo | No | Yes |
| editVideoComponentReference | No | No |
| createDataTableCmd | No | Yes |
| editAttachment | No | Yes |
| pinAttachment | No | Yes |
| unpinAttachment | No | Yes |
| goToAttachmentLocation | No | Yes |
| removeAttachment | No | Yes |