From 8283299d7cf206cf72e11d862398c98e5172eedf Mon Sep 17 00:00:00 2001 From: Hongming Wang Date: Wed, 12 Jun 2024 12:21:05 -0400 Subject: [PATCH] Update integrations README --- data/integrations/README.md | 114 +++++------------------------------- 1 file changed, 14 insertions(+), 100 deletions(-) diff --git a/data/integrations/README.md b/data/integrations/README.md index 75f92d4e..0ef46439 100644 --- a/data/integrations/README.md +++ b/data/integrations/README.md @@ -3,6 +3,7 @@ Integrations maintain the rules for how the Shopify Product Taxonomy interacts w ## Supported Integrations - Google (2021-09-21) +- Shopify (2022-02) ## How this works ### Overview @@ -11,12 +12,13 @@ Integrations live in the `data/integrations` directory and are further grouped b ``` data/integrations/ -├── integrations.yml # index +├── integrations.yml # lists integrations and their versions for taxonomy mappings in distribution ├── # name/handle of the commerce system (e.g. google/amazon) │ ├── # e.g. v1.0.1 or 2024-04 -│ │ └── mappings -│ │ ├── from_shopify.yml -│ │ └── to_shopify.yml +│ │ ├── mappings +│ │ │ ├── from_shopify.yml +│ │ │ └── to_shopify.yml +│ │ └── full_names.yml │ └── │ └── ... └── #... @@ -25,112 +27,24 @@ data/integrations/ ### Mappings The primary concern of integrations are mappings. Mappings are a set of rules that help us convert to and from the Shopify taxonomy and the taxonomy of that integration. -Each mapping is generated from a set of mapping rules that are defined as inputs and outputs. Inputs and outputs are sparse-products which means they are shaped like the products of the taxonomies being mapped. Attributes in a input/output can be one of the following: - -| Type of Entry | Matching logic | -|---------------|----------------| -| single value |match for this specific single value | -| list | match for any value that is in the list of values | -| present | match for any any valid value for this attribute | -| nil | matches when the value is not present (or is a null-type) | - #### Examples of mapping rules ```yaml -# Simple mapping rule (e.g. Shopify -> Google) -input: - product_category_id: aa # Apparel & Accessories (Shopify) -output: - product_category_id: 166 # Apparel & Accessories (Google) - - -# More complex mapping rules (e.g. Shopify -> Amazon) -input: - product_category_id: aa-6-9 - attributes: - - name: target_gender - value: target_gender__female -output: - amazon_category: - - 3888171 - - 9539904011 -input: - product_category_id: aa-6-9 -output: - product_type: - - Jewelry/FineRing - - Jewelry/Ring - -``` - -#### Generating mappings from rules -Mappings are generated from the rules as a part of the build/distribution step: -- Combinations for all input variations are generated for all product categories and their attributes that appear in the inputs found in the set of rules - - As an optimization, combinations including attributes that do not occur in any rules are omitted -- Builder then passes each generated input through the set of rules, reducing the output of each matching rule into a final output - - To combine outputs, we do a union of all attributes - - When an attributes is present in both outputs being combined an intersection is done - -Putting this all together, let us look at how mappings could be compiled for the `Apparel & Accessories > Jewelry > Rings` category in Shopify taxonomy to relevant Amazon categories (using attribute/attribute value names and handles for easier reading): - -```yaml -# Rule 1 - Adult Rings +# Mapping rule from Shopify taxonomy to Google taxonomy input: - product_category_id: aa-6-9 # Shopify: Apparel & Accessories > Jewelry > Rings - attributes: - - name: age_group - value: age_group__adults + product_category_id: aa # Apparel & Accessories (Shopify) output: - amazon_category: # list of all valid categories for adult rings - - 3888171 # Men > Jewelry > Rings - - 9539904011 # Men > Jewelry > Wedding Rings - - 9539894011 # Women > Jewelry > Women's Wedding & Engagement Rings - - 9539902011 # Women's Anniversary Rings - - 9539895011 # Women's Bridal Rings - - 9539896011 # Women's Engagement Rings - #... -``` + product_category_id: + - '166' # Apparel & Accessories (Google) -```yaml -# Rule 2 - Men's Rings +# Mapping rule from Shopify legacy taxonomy to Shopify latest taxonomy input: - product_category_id: aa-6-9 # Shopify: Apparel & Accessories > Jewelry > Rings - attributes: - - name: target_gender - value: target_gender__male + product_category_id: 126 output: - amazon_category: # list of all valid categories for male rings - - 3888171 # Men > Jewelry > Rings - - 9539904011 # Men > Jewelry > Wedding Rings - - 3880891 # Boys > Jewelry > Rings + product_category_id: + - aa ``` -```yaml -# Rule 3 - Women's Rings -input - product_category_id: aa-6-9 # Shopify: Apparel & Accessories > Jewelry > Rings - attributes: - - name: target_gender - value: target_gender__female -output - amazon_category: # list of all valid categories for female rings - - 9539894011 # Women > Jewelry > Women's Wedding & Engagement Rings - - 9539902011 # Women's Anniversary Rings - - 9539895011 # Women's Bridal Rings - - 9539896011 # Women's Engagement Rings - - 3881961 # Girls > Jewelry > Rings -``` - ---- - -**Final Mapping** - -| Input (generated) | Output | Notes -|--------|--------|--------| -| product_category_id: "aa-6-9", attributes: ["target_gender": "target_gender__male", "age_group": "age_group__adults"] | amazon_category: [3888171, 9539904011] | Matches rules 1 & 2 | -| product_category_id: "aa-6-9", attributes: ["target_gender": "target_gender__female", "age_group": "age_group__adults"] | amazon_category: [9539894011, 9539902011, 9539895011, 9539896011]| Matches rules 1 & 3 | -| ... | ... || -
Output as JSON