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, it 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
■ 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.
3 Writing Rules
3.1 Rules for identifying a business data term or group
3.2 General Rules for naming a business data term or group
3.3 Specific Rules for naming a business data term or group
3.4 General rules for definitions of business data terms or groups
3.5 Specific Rules for definitions of business data terms or groups
3.6 Rules for "Used Code list" within business data terms
3.7 Rules for the field Usage
3.8 Rules for the field Usage rule
3.9 Rules for the field Example
3.10 Rules for Document Model
The following general rules apply for identifying a semantic business data term and group
R1. Each business data term must be identified by a unique identifier in the GS1 semantic dictionary
R2. 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.
R3. The name must be in British English.
R4. Only the first word in the name must start with a capital letter except for proper nouns.
R5. The name must be business oriented and non-technical.
R6. The business data term and group name must be kept as shorter as possible.
R7. The name may not contain abbreviations or acronyms except for those business data terms and business data term groups described in sections 3.3.1 and 3.3.2.
R8. The name must be designed in a way that it is clear for what piece of information (data) it is to be used.
R9. The name may not be designed in a way that allows it to be used for multiple purposes.
R10. The name must be as generic as possible (makes it useful in different context), but without losing meaning and without violating R9.
R11. 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.
R12. The name must be syntax independent (e.g. no references to EANCOM® or GS1 XML may be included).
R13. 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.3.1 Business data terms or groups, which are constituted by a GS1 acronym such as GLN, GTIN, SSCC, GDTI and other GS1 identification keys.
R14. The business data terms or groups must be written in full name.
R15. The acronym of the GS1 identification key must be included in the business data term name separated by a “,”.
3.3.2 Business data terms or groups which are constituted by an abbreviation
R16. The business data terms or groups must be written in full name.
R17. The abbreviation must be included in the business data term name separated by a “,”.
3.3.3 Business data terms or groups which contains dates
R18. The word “date” must be included in the name.
R19. The name must be designed in a way that it is clear what is meant by the indication of the date.
3.3.4 Business data terms or group which contain a date and time
R20. The words “date” and “time” must be included in the name.
R21. 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.
R22. 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.3.5 Rules only for business data terms which contain a time period or date period
R23. When the SDD include a time or date period, the business data term must been split in two business data terms.
R24. 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.3.6 Business data terms or groups which contain a coded value
R25. The word “code” must be included in the name.
R26. The word “code” must be in the end of the name.
R27. The name must be designed in a way that it is clear what is meant by the coded information.
3.3.7 Business data terms or groups which contain a reference to a document
R28. The name must begin with the word “Referenced” when referring to a document.
R29. The Business data term group name must end with “information” when the reference is to a set of information.
R30. The name referring to a document must be designed in a way that it is clear which document is referenced.
3.3.8 Business data terms or groups which contain a reference to a line in a document
R31. When referring to a document line, the generic business data term must be used.
R32. Where the business data term is used the exact meaning must be specified in the document model.
3.3.9 Business data terms or groups which contain a monetary amount
R33. When the name constitutes a monetary amount, it must include the word “monetary amount”.
3.3.10 Business data terms derived from a Boolean data type
R34. No business data terms … Boolean data type should appear in the semantic data dictionary.
R35. A GDD Boolean attribute should be created as a business data term.
R36. 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.
R37. The definition must be in British English.
R38. The definition must be business-oriented and non-technical.
R39. The definition must be as short as possible.
R40. The definition must be designed in a way that it is clear for what piece of information (data) it is to be used.
R41. The definition must be as generic as possible (makes it useful in different context), but without losing meaning.
R42. The definition must not contain any references to other business data terms or groups.
R43. The definition must not contain any references to code lists.
R44. The definition must not contain any references to standards (e.g. ISO).
R45. The definition … references should be defined as “used code list” and “Link to used code list” to the business data term/group.
R46. The definition must be syntax independent (i.e. no references to EDIFACT or XML may be included).
R47. The definition must be recognised globally. The definition must not be regional (e.g. EU).
R48. 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.5.1 Business data terms or group definitions which contain identifiers such as GLN, GTIN, SSCC, GDTI or other GS1 identification keys
R49. The definition must begin with the words “Identity” when defining a business data term which constitutes an identifier.
R50. The business data term definition may not mention any GS1 identification key.
3.5.2 Business data term or group definitions which contain a reference to a document
R51. 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.5.3 Rules for a definition in business data terms or groups using the word “information”
R52. The description may start with: “The information specifying …”.
3.5.4 Rules for a definition in business data terms or groups using the word “date time”
R53. The description may start with: “The date and optional time from when…”.
R54. The direct link to a specific ISO code list should not be included but may be stated where it is available.
R55. 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.
R56. If the applied code list is a GS1 code list, the SDD should contain the direct link.
R57. The sentence must start with the word: “Used to”, “Used by”, “Used in” or “Used for”.
R58. The information should express global or regional usage rules.
R59. All Local information should be expressed in a different location.
R60. 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.10.1 Rules for the field Description
R61. The information should express specified instructions for the document model.
3.10.2 Rules for the field Example
R62. 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