Code Lists

Return to Table of Contents

• External code lists
• Internal code lists
  • Internal code lists in context
  • Internal code list versioning

There are two types of code lists in GS1 XML messages: external and internal ones.

External code lists

External code lists are defined and maintained outside the GS1 community, usually by other standard bodies, e.g. ISO. Their examples are:

• Country Codes - ISO 3166-1:1997, defined in Country.xsd schema, as the ISO3166_1CodeType
• Country Subdivision Codes - ISO 3166-2:1998, defined in Country.xsd schema, as the ISO3166_2CodeType
• Currency Codes - ISO 4217:2001, defined in MonetaryAmount.xsd schema, as the CurrencyISOCodeType

All of them are defined as a part of the common library. They are defined as strings restricted to an appropriate number of characters, but do not contain the code list values. The reason behind this decision is that enumerating the lists content would cause problems with their maintenance, which is done outside of the GS1 System and would breach the copyright ownership.

The users are advised to consult the website of the International Standard Organisation www.iso.org to check how the lists can be acquired and used.

Internal code lists

• Internal code lists in context
• Internal code list versioning

Internal code lists are those developed and maintained within the GS1 System. Starting from release 2.0, those code lists are defined in separate schemas and are no longer embedded in the common library schemas. This practice requires giving up some advantages, mainly the ability for parsers to enforce strict validation. In other words, the code list embedded within the schema cannot be changed, without affecting the validation process. On the contrary, if a code list is only referenced in the given schema and defined externally, various versions of that code list can be used as a base for validation.

On the other hand, this ensures that any change to a code list schema does not trigger a new release of the entire set of GS1 schemas, which would require additional upgrades for the users. Defining code lists outside of the main schema document allows upgrading lists as soon as business demand arises and facilitates version management.

Code lists are defined as xsd:enumeration. The lists are included or imported into the schema document, which uses it.

Advantages for implementers of this approach include reduced maintenance costs, faster implementation of list changes, reduced versions of schemas and simpler publications. In addition, the handling of code lists is consistent with the new, similar handling of components.

Internal code lists in context

Code list schemas follow the same principles as all the other GS1 schemas, with respect to namespaces. If a given code list is used across different contexts, it is defined within the common library namespace, e.g. TimePeriodList.xsd or AllowanceChargeList.xsd.

Code lists used just in one context are defined in the namespace of the schema document that uses them. For example, ReplenishmentRequestStatusList.xsd and CollaborationPriorityCodelist.xsd are defined in the Plan namespace (xmlns:plan="urn:ean.ucc:plan:2").

This approach ensures backward compatibility. Due to the fact that the minor versions are not reflected in the namespace of a schema, instance documents can be validated against the older minor schema. In addition, any schemas that ‘include’ this schema do not need to change because the target namespace of the included components is the same as the target namespace of the including schema.

Internal code list versioning

Each code list is defined in its own schema file, which is versioned separately. When a change is made to a code list schema, it is versioned in the same way as any other component. When new code definitions are approved by the respective Business Requirements Group (BRG), the code list schema is updated and the minor version number within the code list schema is incremented. This allows users to have access to the codes in the most efficient manner.

Addition of code values constitutes a minor version change. If a code deletion or modification of definition is necessary, it will only be implemented under a major version change.

Return to Table of Contents

TOP