Writing Best Practices
Writing clear, precise, and unambiguous Duplex Sync rule definitions is crucial for effective implementation and interpretation. This section provides comprehensive guidelines to ensure your rule definitions are well-structured and easily understood.
Use of Precise Terminology
Mandatory Verbs
Use consistent and precise verbs to indicate requirements:
| Verb | Usage |
|---|---|
| SHALL | Used to indicate a mandatory requirement. Use it for errors. |
| SHALL NOT | Used to indicate a prohibition. Use it for errors. |
| MAY | Used to indicate an optional feature. Use it for warnings. |
Stick to one style of mandatory verbs throughout your rule documentation. Mixing verbs can create confusion.
Example of proper verb usage:
✅ 'minimumTradeItemLifespanFromTimeOfArrival' (3479) SHALL be indicated on the smallest unit in the hierarchy.
Attribute References
When referencing attributes, always use the attribute name and ID formatted like this: 'fatPercentageInDryMatter' (441).
Example of proper attribute reference:
✅ IF 'isTradeItemAConsumerUnit' (3066) equals 'true', THEN 'regulatedProductName' (3314) with languageCode 'da' SHALL be provided.
Some attributes may have the same attribute name but different IDs.
Always use the specific ID to avoid ambiguity.
Some attributes may be referenced in a path-like structure, but for clarity, use the attribute name and ID directly with minimal context.
Avoid using full paths unless absolutely necessary.
Examples of proper minimal path reference:
✅ IF 'depth/measurementUnitCode' (3532) equals 'CM', THEN ...
✅ IF 'width/measurementUnitCode' (3539) equals 'CM', THEN ...
Clear Conditional Statements
If-Then Structure
For conditional rules, use a consistent format: "If [condition], then [requirement]".
Example of a well-structured conditional statement:
✅ IF 'preparationStateCode' (1225) is used, THEN 'nutrientTypeCode' (1241) SHALL equal 'ENER-' AND 'quantityContained/measurementUnitCode' (1244) SHALL equal 'KJO' in the same instance of the 'nutrientDetail' class.
Multiple Conditions
When specifying multiple conditions, connect them with AND or OR clauses. Avoid using bullet points to list conditions within a rule definition.
Example of well-structured multiple conditions:
✅ IF 'tradeItemUnitDescriptorCode' (3074) is not 'PALLET' AND 'isTradeItemADespatchUnit' (3062) is 'TRUE' AND the actual unit is itself not a child of any further packaging, THEN 'nonGTINLogisticsUnitInformation/grossWeight' (xxxx) SHALL be indicated.
Clarity and Precision
Avoid Ambiguity
Be explicit and avoid vague terms. Your definitions should be clear to a developer.
Example of ambiguous wording:
❌ The attribute must be populated with appropriate values.
Example of clear wording:
✅ The attribute 'sunProtectionFactor' (4133) SHALL be indicated with a numeric value between 1 and 100.
Be Specific About Cardinality
Clearly indicate how many instances of an attribute or class are required.
This is the only instance, when the attribute ID is not used, as it is referencing multiple attributes.
Example of clear cardinality:
✅ For every instance of 'nutrientDetail/quantityContained', there SHALL be exactly one instance of 'nutrientDetail/measurementPrecisionCode'.