TSV Generation¶

The TSV bundles are generated for uml2semantics-python from the GDSN UML JSON dump and taxonomy sources. The current implementation is in src/gdsn_tsv_transformer/cli.py and follows the repository mapping documents:

• artefacts/GDSN-TSV-Mapping-v0.1.0.md
• GDSN-TSV-Mapping-v0.1.0.md
• GDSN_TSV_Transformer_README_v0.1.0.md

Each module writes the standard file set:

Classes.tsv
Attributes.tsv
Datatypes.tsv
Enumerations.tsv
EnumerationNamedValues.tsv
AnnotationProperties.tsv
Annotations.tsv
diagnostics.tsv

GDSN and GPC¶

Generate GDSN and GPC TSVs together. The --input-dir value is the default, but it is shown explicitly for repeatability:

.venv/bin/gdsn-json-to-tsv \
  --input-dir artefacts/GDSN_Current_v3.1.35 \
  --output-dir build/gdsn-tsv

Generate only GDSN:

.venv/bin/gdsn-json-to-tsv \
  --input-dir artefacts/GDSN_Current_v3.1.35 \
  --output-dir build/gdsn-tsv \
  --skip-gpc

Output directories:

build/gdsn-tsv/gdsn/
build/gdsn-tsv/gpc/

The executable always writes the GDSN module to build/gdsn-tsv/gdsn/. Unless --skip-gpc is supplied, it also writes the separate GPC module to build/gdsn-tsv/gpc/.

Google Product Taxonomy¶

Generate Google Product Taxonomy TSVs:

.venv/bin/google-taxonomy-to-tsv \
  --input-file artefacts/google/taxonomy-with-ids.en-GB.txt \
  --output-dir build/gdsn-tsv

Output directory:

build/gdsn-tsv/google/

Source Inputs¶

The GDSN transformer reads these source files from artefacts/GDSN_Current_v3.1.35/:

The source files can be obtained from navigator.gs1.org

Implemented Type Rules¶

The GDSN UML dump uses numeric type values. The transformer applies these rules:

Attribute type values in gdsn_classAttributes.json are separate from class type values. Attributes owned by structured type-3 records are emitted as normal attributes on the generated value class.

GDSN Classes¶

Classes.tsv contains:

• type-2 UML classes;
• structured type-3 value classes;
• synthetic containers for AVPs, extended attributes, and extension modules.

Class CURIEs are stable and source-ID based:

gdsn:c{id}

Generalisation extensions in gdsn_classes.json become ParentNames. A generalisation is identified as an extension with type == 1, name == "Generalization", and destinationClassId pointing at the parent.

GDSN Attributes¶

Attributes.tsv contains:

• owned UML attributes from gdsn_classAttributes.json;
• association extensions from gdsn_classes.json where extension.type == 2;
• AVP properties on gdsn:GDSNAVP;
• extended attributes on gdsn:GDSNExtendedAttribute or a synthetic group class;
• a synthetic gdsn:extensionModule property from TradeItemInformation to gdsn:GDSNExtensionModule.

Attribute CURIEs are stable and source-ID based:

gdsn:a{id}

Association property CURIEs are generated from the source class, destination class, and association position:

gdsn:assoc_{sourceClassId}_{destinationClassId}_{index}

Ranges are resolved in this order:

1. xsd: primitive when the source type name is a known XML Schema datatype.
2. GDSN enumeration when the range points to a code list or enumeration.
3. GDSN class or datatype CURIE for known source class IDs.
4. Extended-code enumeration when an extended attribute type name matches gdsn_extendedCodeValues.json.
5. xsd:string fallback when the source type cannot be resolved.

Malformed multiplicities are not guessed. MinMultiplicity and MaxMultiplicity are left blank, the source value is preserved as gdsn:originalMultiplicity, and a warning is written to diagnostics.tsv.

Datatypes and Limits¶

Simple type-3 records become Datatypes.tsv rows. Base datatypes are resolved by walking type-1/type-3 generalisations to the ultimate XML Schema primitive.

Structured type-3 records are not emitted as datatypes. If a type-3 record owns attributes, it is emitted as a class with a gdsn:valueDatatype annotation. This preserves qualified values such as language-tagged descriptions and measurements with units.

For example:

Normal GDSN string limits such as {1..200} are converted into named synthetic datatypes, not inline attribute facets. This avoids anonymous datatype ranges that caused Protege rendering and parsing issues.

Example implemented mapping:

Extended attribute limits are deliberately not converted into datatype facets. Their limit values are preserved as gdsn:originalLimit annotations instead. This decision avoids invalid datatype classes from malformed or ambiguous extended-attribute metadata, including the Carrefour and US FoodService cases that previously surfaced as ErrorNN ranges in Protege.

Enumerations and Named Values¶

Enumerations.tsv contains:

• GDSN type-4 code lists;
• GDSN type-5 enumerations;
• classes referenced by gdsn_codeValues.json;
• generated fallback code-list classes when code values reference a missing class;
• gdsn:ISO3166CountryCode;
• generated extended-code enumerations from gdsn_extendedCodeValues.json.

EnumerationNamedValues.tsv contains:

• standard GDSN code values as gdsn:cv{id};
• ISO 3166 alpha-3 values as iso3166:{alpha3};
• extended-code values as gdsn:extcv{id}_{groupName}.

The iso3166: prefix is intentionally preserved for ontology generation, so the uml2semantics command should include:

iso3166:urn:iso:std:iso:3166

AVPs and Extended Attributes¶

AVPs and extended attributes are generated into synthetic containers because their explicit ownership is not available in the same way as normal UML class attributes.

If an AVP has inline code values, the transformer emits a generated gdsn:avpCode_{name} enumeration. If an extended attribute type name matches a group in gdsn_extendedCodeValues.json, the range becomes gdsn:extCode_{groupName}.

Implemented examples:

Extension Module Detection¶

Extension modules are represented with a synthetic superclass:

gdsn:GDSNExtensionModule

The implemented detection rule marks 77 module classes. A class is treated as an extension module when it is a type-2 class whose name ends with Module and it appears under a gdsn_instances.json XPath containing:

/tradeItemInformation/extension/*

The implementation also includes module-like type-2 classes ending in Module that are not present in gdsn_instances.json. This captures the known orphan module class FoodAndBeveragePropertiesInformationModule and keeps the module inventory at 77.

Each detected concrete module class gets gdsn:GDSNExtensionModule in ParentNames, and the synthetic gdsn:extensionModule property links TradeItemInformation to that superclass.

Annotations and Provenance¶

AnnotationProperties.tsv and Annotations.tsv preserve source metadata used for traceability and downstream SHACL/RDF generation:

GPC Module¶

GPC is generated as a separate ontology module using the gpc: namespace. The source hierarchy from GPCv20260520GB.json becomes classes with parent relationships. The namespace base for generated gpc: CURIEs is:

urn:gs1:std:gpc:

GPC annotations include:

• gpc:level;
• gpc:active;
• gpc:definitionExcludes;
• gpc:contextCode from gdsn_gpcBricks.json;
• dct:source.

Google Product Taxonomy Module¶

Google Product Taxonomy is also generated as a separate ontology module. It uses the google: prefix and follows the same broad taxonomy pattern as GPC: categories become classes, hierarchy becomes parent relationships, and category metadata is emitted as annotations.

Diagnostics and Validation¶

Diagnostics are written to each module's diagnostics.tsv.

The implemented unit tests validate the key TSV-generation decisions:

• Carrefour extended-code attributes resolve to generated extended-code enumerations.
• Carrefour string extended attributes remain xsd:string and do not receive converted length facets.
• normal GDSN string limits become named synthetic datatypes.
• US FoodService notSignificantSourceOfNutrient remains xsd:string with no facet conversion.
• extension-module detection marks 77 module classes.
• structured type-3 records such as Measurement and Description35 are value classes, not datatypes.

Run the TSV test suite with:

.venv/bin/python -m unittest tests.test_tsv_transformer tests.test_google_taxonomy