1 Introduction
This document describes the writing rules used for the creation and maintenances of GS1 EDI Semantic Data Dictionary (SDD). It contains also rules for Document Model.
All these rules are applied on Business Data Terms (BDT) and Business Data Terms Groups (BDTG).
A Business Data Term is a full set of information which expresses the Business name, definition and how to use it. The goal is to create a Business reference that will be the bridge to all technical information.
A Business Data Term group regroup several Business data terms and use it in order to constitute a particular business usage.
Another document, the GS1 EDI Semantic Model Methodology, includes:
■ Principles and preconditions
■ Business process
■ Collaboration processes
■ Business documents
■ Mapping to syntaxes
■ Publication
■ Communication
■ Maintenance
This document is a complement to this Semantic Model Methodology – Writing rules and should be read together.
2 Notes inside Semantic Data Dictionary
2.1 Notes expressing a Business Data Term or Business Data Term Group
2.2 Notes expressing the Context field for a specific document model
2.3 Code list management in Semantic Data Dictionary
■ Name: Name of the business data term or business data term group.
■ Definition: Description of the business data term or business data term group.
■ Business rule: Description of the reason why the business data term or group must be used in response to business or legal requirement.
□ Examples:” Mandatory if code "2" or "3" are entered in the business data term "EU unique identifier type code".”
■ Usage rule: Description of how to use the business data term or group.
□ Examples: “To be used in addition to GS1 Global Product Classification standard.”
■ Reference Definition: Used when there is a definition from a specific source which are relevant to include for a specific BDT.
■ Example: Concrete example of the use of the business data term or group.
■ Use code list: Name the code list.
■ Link to used code list: URL of the code list.
■ Remark: Complementary information.
■ Status: The status assigned to the business data term or group. (work in progress)
■ Synonyms: Business data terms that have the same meaning and definition
□ Examples: Post office box number and “P.O. box, postal box”
■ Version: Current version of the business data term or group. (work in progress)
■ GDD Name: Name of the GDD data term used for the creation of the business data term.
■ GDD Definition: Information about the GDD Name.
■ GDD Example: Information about the example inside GDD.
■ SDD-ID: ID used to identify this Business data term or business data term group.
Example of BDT notes.
The field “Context” is a block that expresses all information specific to a document model (e.g. Order). All this information will be linked to a specific business data term or group. It will help for understanding the business data term or group inside specific circumstances.
■ Description: Specified information about the business data term (BDT) and business data term groups (BDTG) in a Document model.
■ Examples: Specified example for the Document Model.
Example of context note.
Example of context note with multiple lines.
While the Semantic Data Dictionary is intended to be syntax neutral, different syntaxes may adopt different code lists to represent a business term.
In consideration of this aspect, the notes “Used code list” and “Link to used code list” must be considered as a reference helping in the correct interpretation of the business data term.
The effective set of admitted values, when developing a real message, will depend on the target syntax and may differ from the code list included in the SDD.
Similar considerations apply to enumerations. The eventually proposed set of possible values will represent only a reference for the correct interpretation of the type of expected content. The effective values may vary according to the target syntax specifications.
The set of applicable values may vary also due to the application of restricted code lists, allowing, in a specific context, only a subset of codes.
For instance, in an invoice, only the document types relevant for this kind of message are allowed while other document types are relevant in an order.
3 Writing Rules
3.1 General rules
3.2 Rules for identifying a business data term or group
3.3 General Rules for naming a business data term or group
3.4 Specific Rules for naming a business data term or group
3.5 General rules for definitions of business data terms or groups
3.6 Specific Rules for definitions of business data terms or groups
3.7 Rules for "Used Code list" within business data terms
3.8 Rules for the field Usage
3.9 Rules for the field Usage rule
3.10 Rules for the field Example
3.11 Rules for Document Model
R1. For business terms that are applicable at different levels in a message, for instance at header level as well as at item level, the reuse of existing BDTs or BDTGs should be privileged. If necessary, in order to clarify the usage of a term in different positions, the usage and context notes can be leveraged.
The following general rules apply for identifying a semantic business data term and group
R2. Each business data term must be identified by a unique identifier in the GS1 semantic dictionary
R3. The format of the identifier is written in the form: BDT + 8 digits and BDTG + 8 digits. (work in progress)
Example of identifier.
The following general writing rules apply for naming a business data term and a business data term group.
R4. The name must be in British English.
R5. Only the first word in the name must start with a capital letter except for proper nouns.
R6. The name must be business oriented and non-technical.
R7. The business data term and group name must be kept as shorter as possible.
R8. The name may not contain abbreviations or acronyms except for those business data terms and business data term groups described in sections 3.4.1 and 3.4.2.
R9. The name must be designed in a way that it is clear for what piece of information (data) it is to be used.
R10. The name may not be designed in a way that allows it to be used for multiple purposes.
R11. The name must be as generic as possible (makes it useful in different context), but without losing meaning and without violating R9.
R12. The name must not contain references to other business data terms, code lists, standards (e.g. ISO). Such references should be listed in another field such as a comment included in the semantic description of a business document.
R13. The name must be syntax independent (e.g. no references to EANCOM® or GS1 XML may be included).
R14. When referencing another business data term, the SDD-ID + name must be written as a quotation.
The following specific rules for naming a business data term or group apply to business data terms or group used for GS1 identification keys, coded values, monetary amounts, references and dates or date periods.
3.4.1 Business data terms or groups, which are constituted by a GS1 acronym such as GLN, GTIN, SSCC, GDTI and other GS1 identification keys.
R15. The business data terms or groups must be written in full name.
R16. The acronym of the GS1 identification key must be included in the business data term name separated by a “,”.
3.4.2 Business data terms or groups which are constituted by an abbreviation
R17. The business data terms or groups must be written in full name.
R18. The abbreviation must be included in the business data term name separated by a “,”.
3.4.3 Business data terms or groups which contains dates
R19. The word “date” must be included in the name.
R20. The name must be designed in a way that it is clear what is meant by the indication of the date.
3.4.4 Business data terms or group which contain a date and time
R21. The words “date” and “time” must be included in the name.
R22. The words “date” and “time” must be included in the business data term group if the group contains the business data terms “date” and “time”, and the business data term group mainly expresses date and time information.
R23. The business data term name must be designed in a way that it is clear what is meant by the indication of the date time.
3.4.5 Rules only for business data terms which contain a time period or date period
R24. When the SDD include a time or date period, the business data term must been split in two business data terms.
R25. The business data term name must be designed in a way that it is clear what is meant by the indication of the begin or end period.
3.4.6 Business data terms or groups which contain a coded value
R26. The word “code” must be included in the name.
R27. The word “code” must be in the end of the name.
R28. The name must be designed in a way that it is clear what is meant by the coded information.
3.4.7 Business data terms or groups which contain a reference to a document
R29. The name must begin with the word “Referenced” when referring to a document.
R30. The Business data term group name must end with “information” when the reference is to a set of information.
R31. The name referring to a document must be designed in a way that it is clear which document is referenced.
3.4.8 Business data terms or groups which contain a reference to a line in a document
R32. When referring to a document line, the generic business data term must be used.
R33. Where the business data term is used the exact meaning must be specified in the document model.
3.4.9 Business data terms or groups which contain a monetary amount
R34. When the name constitutes a monetary amount, it must include the word “monetary amount”.
3.4.10 Business data terms derived from a Boolean data type
R35. No business data terms … Boolean data type should appear in the semantic data dictionary.
R36. A GDD Boolean attribute should be created as a business data term.
R37. The name of the business data term must include the word “indicator” in the end.
The following general writing rules apply for the definition of a business data term and business data term group.
R38. The definition must be in British English.
R39. The definition must be business-oriented and non-technical.
R40. The definition must be as short as possible.
R41. The definition must be designed in a way that it is clear for what piece of information (data) it is to be used.
R42. The definition must be as generic as possible (makes it useful in different context), but without losing meaning.
R43. The definition must not contain any references to other business data terms or groups.
R44. The definition must not contain any references to code lists.
R45. The definition must not contain any references to standards (e.g. ISO).
R46. The definition … references should be defined as “used code list” and “Link to used code list” to the business data term/group.
R47. The definition must be syntax independent (i.e. no references to EDIFACT or XML may be included).
R48. The definition must be recognised globally. The definition must not be regional (e.g. EU).
R49. The definition should start with the word: “The”.
The following specific rules for the definition of a business data term and group apply to business data terms or group used for GS1 identification keys, coded values, monetary amounts, references and dates or date periods.
3.6.1 Business data terms or group definitions which contain identifiers such as GLN, GTIN, SSCC, GDTI or other GS1 identification keys
R50. The definition must begin with the words “Identity” when defining a business data term which constitutes an identifier.
R51. The business data term definition may not mention any GS1 identification key.
3.6.2 Business data term or group definitions which contain a reference to a document
R52. It should start “The information specifying the details of a reference to”.
Example: The information specifying the details of a reference to a despatch advice.
3.6.3 Rules for a definition in business data terms or groups using the word “information”
R53. The description may start with: “The information specifying …”.
3.6.4 Rules for a definition in business data terms or groups using the word “date time”
R54. The description may start with: “The date (and time)…”.
R55. The direct link to a specific ISO code list should not be included but may be stated where it is available.
R56. If the applied code list is an external code list from GS1 and is open and free of charge, the SDD should contain the direct link.
R57. If the applied code list is a GS1 code list, the SDD should contain the direct link.
R58. The sentence must start with the word: “Used to”, “Used by”, “Used in” or “Used for”.
R59. The information should express global or regional usage rules.
R60. All Local information should be expressed in a different location.
R61. An example should be valid for all Business documents models, otherwise no example should be included.
The following rules apply to all information included in the context fields that are linked to a Business Data Term or Group in the specified document model.
3.11.1 Rules for the field Description
R62. The information should express specified instructions for the document model.
3.11.2 Rules for the field Example
R63. An example should be understandable within the context it is written, otherwise no example should be included (dependent upon R60)
Contributors & change log
Contributors
Log of Changes
Useful links:
* PDF version of the GS1 Semantic Model Methodology Writing Rules Standard