GS1 Semantic Model Methodology Writing Rules Standard

1 Introduction

2 Notes inside Semantic Data Dictionary

• 2.1 Notes expressing a Business Data Term or Business Data Term Group

■ 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.

• 2.2 Notes expressing the Context field for a specific document model

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.



Example of context note with BDT notes.

3 Writing Rules

• 3.1 Rules for identifying a business data term or group

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.

• 3.2 General Rules for naming a business data term or group

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.

Sample of good naming
Entity identification
Document status code
Global trade item number, GTIN
Allowance monetary amount
European Union unique identifier type code

• 3.3 Specific Rules for naming a business data term or group

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 “,”.

Not so good naming	Reason	Better naming
GTIN	Not British English (R 3). Not business oriented (R 5). No clear use (R 8). The name must be written in full name and be complete by “,” and the acronym (R 13, R 14).	Global trade item number, GTIN
GLN	Not British English (R 3). Not business oriented (R 5). No clear use (R 8). The name must be written in full name and be complete by “,” and the acronym (R 13, R 14).	Global location number, GLN

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 “,”.

Not so good naming	Reason	Better naming
SEPA	The name must be written in full name and be complete by “,” and the acronym (R 16, R 17).	Single euro payments area information, SEPA

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.

Not so good naming	Reason	Better naming
Date	No clear use (R 8). Multiple purposes (R 9). Lacks meaning for the date (R 19).	Document creation date
Estimated date for the delivery	Too long (R 6).	Estimated delivery 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.

Not so good naming	Reason	Better naming
Requested delivery time	No clear meaning (R 22). The word “date” must be included (R 20).	Requested delivery date time
Requested date and time for the delivery	Too long (R 6). Bad naming (R 21).	Requested delivery date time
Referenced customer document date and time information	(R21) the business data term does not mainly express a date. It contains date and time and other information.	Referenced customer document information

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.

Not so good naming	Reason	Better naming
time period	split in 2 business data terms (R 23).	Begin time period || End time period
Date period	split in 2 business data terms (R 23).	Begin date period || End date 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.

Not so good naming	Reason	Better naming
Currency code for invoice	Name is too specific (R 10). The word “code” not at the end (R 26).	Currency code
currency ccording to ISO-4217	Name is too specific (R 10). Name includes reference to standard (R 11). The word “code” not at the end (R 26). (R54, R55, R56) For Code list reference	Currency code (Reference to ISO-4217 to be included in a separate field: “used code list”, in the semantic model of the business document in which the business data term is used.)

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.

Not so good naming	Reason	Better naming
Despatch advice	Name begins incorrect (R 28). Not clear as a reference (R 30).	Referenced despatch advice information

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.

Not so good naming	Reason	Better naming
Line in despatch advice	Name begins incorrect (R 31). Not clear as a reference (R 32).	Document line number

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”.

Not so good naming	Reason	Better naming
Total tax amount	The word “monetary” is not included (R 33).	Total tax 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.

Not so good naming	Reason	Better naming
Is signature required	The word “indicator” is not included (R 36).	Signature requirement indicator

• 3.4 General rules for definitions of business data terms or groups

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”.

• 3.5 Specific Rules for definitions of business data terms or groups

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.

1. Business data term name	Not so good definition	Reason	Better definition
Global trade item number, GTIN	The identification of any item (product or service) upon which there is a need to retrieve pre-defined information and that may be priced, ordered, or invoiced at any point in any supply chain.	Not business oriented (R 38). Too long (R 39). The word “Identity of” missing (R 49).	Identity according to the GS1 identification system for unique identification of products and services.
Global location number, GLN	The globally unique identification attached to the logistic unit, used for logistical and traceability purposes.	Not business oriented (R 38). No clear use (R 40). The word “Identity of” missing (R 49).	Identity according to the GS1 identification system for unique identification of legal entities, roles and functions, physical and digital locations.

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…”.

• 3.6 Rules for "Used Code list" within business data terms

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.

• 3.7 Rules for the field Usage

R57. The sentence must start with the word: “Used to”, “Used by”, “Used in” or “Used for”.

2. Business data term name	Example
Butter fat reference	Used for customs declarations when importing or exporting goods.
GS1 global product classification GPC attribute value code	Used in conjunction with the attribute type to further characterise the product specified by the brick.

• 3.8 Rules for the field Usage rule

R58. The information should express global or regional usage rules.

R59. All Local information should be expressed in a different location.

• 3.9 Rules for the field Example

R60. An example should be valid for all Business documents models, otherwise no example should be included.

• 3.10 Rules for Document Model

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