Added GTIN and Condition to variant for structured data use

[rahulsingh321]

Introduction of Structured Data for Item Condition and Global Trade Item Number ("GTIN").

Contained Information

• Brief Introduction into structured data
• Detailed Description of added fields including 3rd party support
• Screenshots of Admin Interface
• Example of API request to post / get / update an item with the fields

Introduction

This is the first in a series of PRs to implement full structured data support on Solidus.
Structured Data is the common standard to exchange product and content information via the frontend with search engines and marketing platforms and is defined by the schema.org organisation (through the founding companies Google, Microsoft, Yahoo and Yandex).

It has become the defacto standard to communicate with search engines and also many social networks (such as Facebook).

In this first PR following fields are tackled:

• GTIN
• ItemCondition

This scope of this PR is not to provide structured data on the frontend but merely to provide the information required to generate fully compliant structured data on frontend and feeds without 3rd party extensions or added fields.

GTIN (frequently also known as UPC / EAN in Europe)

Definition

A unique identifier for products usually given by either the manufacturer or the official distributor of a product. Frequently required to have stock listed with marketplaces. It's usually used to identify a product uniquely across multiple steps in the supply chain. While the GTIN is a unique identifier for a product entity it is in no mean a serial number (eg every iPhone of the same model and configuration sold in one country share the UPC, but not the serial number).
It's frequently used to match products in stock synchronizations or order APIs.

Support

Search Engines

Search Engine	Supported
Google	YES
Bing	YES
Yahoo	YES
Yandex	YES
Baidoo	Partial / Closed Beta Program

Marketplaces

Search Engine	Supported
Amazon	YES
Facebook	YES
Ebay	YES
Etsy	No
Vinted	No

Search Ads

Search Engine	Supported
Google Shopping	YES
Bing	YES (mandatory if given by manufacturer)
Yahoo	YES
Yandex	YES
Baidoo	Unknown

Item Condition

Definition

The item condition has found wide acceptance over the past years to annotate if a product is

1. New
2. Used
3. Refurbished
4. Damaged

While the origins where originally found in second hand marketplaces and the car industry, it became widely used with the emergence of the circular economy.

Support

Search Engines

Search Engine	Supported
Google	YES
Bing	YES
Yahoo	YES
Yandex	YES
Baidoo	Partial / Closed Beta Program

Marketplaces

Search Engine	Supported
Amazon	YES (in addition Collectable)
Facebook	YES (in addition various usage grades)
Ebay	YES (with various additional information)
Etsy	No
Vinted	YES (Free field)

Search Ads

Search Engine	Supported
Google Shopping	YES
Bing	YES (optional)
Yahoo	YES
Yandex	YES
Baidoo	No

Concerns: #6060

Screenshots Admin Backend

Product

Variant

APIs

Get Product

Update Product

Possible Improvements

• Validate GTIN against current schemes (EAN 9, UPC, ...)

[kennyadsl]

Thanks for the contribution. Out of curiosity, did you consider using an enum for the condition status? Not suggesting to use it (yet), just wondering if some reasoning around enum already happened, and in case, why it was discarded.

On a note for the future, I'd have appreciated two separate PR or at least commits. The reason is that we might need to revert one of the fields and it would take longer if the changes are mixed with some other feature. I think I'll live with the PR as is.

[fthobe]

Thanks for the contribution. Out of curiosity, did you consider using an enum for the condition status? Not suggesting to use it (yet), just wondering if some reasoning around enum already happened, and in case, why it was discarded.

The value requested by third parties is literally the text String itself, which is well human readable. I felt enum would not have added value here, if there's something I am not seeing, we should make a change here. Could you elaborate your reasoning to ask?

On a note for the future, I'd have appreciated two separate PR or at least commits. The reason is that we might need to revert one of the fields and it would take longer if the changes are mixed with some other feature. I think I'll live with the PR as is.

We can absolutely do that.

[kennyadsl]

Could you elaborate your reasoning to ask?

The reason is just not having the hardcoded strings in the database. I understand that you are looking at this in terms of 3rd party platform reading data, but there might be someone displaying those fields on the frontend, and they might have more states to display. They could go with a new field or extend the already present condition field. With the way the feature is designed now, the best option is going with another field because it's very hard to extend.

[rahulsingh321]

@kennyadsl

Thanks for the contribution. Out of curiosity, did you consider using an enum for the condition status? Not suggesting to use it (yet), just wondering if some reasoning around enum already happened, and in case, why it was discarded.

Yes, I tried using the enum for this initially like this, but later moved to constant [ which I think give more flexibility to change ]
enum conditions: %i[damaged, new, refurbished, new ]

But using that got some error at variant level when using - variant.damaged? causing error, it been already defined by some other enum.

Also, if you want, I can keep conditions in yaml and using YAML.load_file, I can get that, that way, it can be easily used in different languages and extend a well. Let me know what do you think?

[fthobe]

The reason is just not having the hardcoded strings in the database. I understand that you are looking at this in terms of 3rd party platform reading data, but there might be someone displaying those fields on the frontend, and they might have more states to display. They could go with a new field or extend the already present condition field. With the way the feature is designed now, the best option is going with another field because it's very hard to extend.

I See your point and would like to add some notes:

• These values will be displayed in feeds and on frontend (via json snippets) as those are the two options given by 3rd parties short of api integration.
• the values itself (conditions are I believe 8 years old by now) are very static, the implementation is not (the json might change down the road, the feeds are relatively stable in specs for many years as well)

If you feel like it adds value where platforms require additional values (eBay has like 8 states of used, Amazon 4).

@kennyadsl if you happiness depends on it we can do it, if not I'd leave it like that.

@rahulsingh321 wait for Kenny's reply and act accordingly.

[fthobe]

@rahulsingh321 after discussions with Kenny please enumerate the conditions.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.70%. Comparing base (b367f99) to head (53b229a).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6097   +/-   ##
=======================================
  Coverage   88.70%   88.70%           
=======================================
  Files         829      829           
  Lines       17992    17993    +1     
=======================================
+ Hits        15959    15960    +1     
  Misses       2033     2033           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[fthobe]

@kennyadsl tests pass.

[mamhoff]

There are no tests for the new features. Please add them.

[fthobe]

Thank you for your input. We will add them when we go out of draft.

[fthobe]

@mamhoff should better now

[kennyadsl]

Please also:

• update API documentation here, let me know if you need help with that, I know it's not easy to navigate. This will populate https://solidus.stoplight.io/docs/solidus/branches/main/e0fd2dd6925ca-solidus-api.
• New admin show page here: https://github.com/solidusio/solidus/blob/main/admin/app/components/solidus_admin/products/show/component.html.erb
• samples to add the new attribute to seeded products: https://github.com/solidusio/solidus/blob/main/sample/db/samples/products.rb

Thanks

[rahulsingh321]

Please also:

• update API documentation here, let me know if you need help with that, I know it's not easy to navigate. This will populate https://solidus.stoplight.io/docs/solidus/branches/main/e0fd2dd6925ca-solidus-api.
• New admin show page here: https://github.com/solidusio/solidus/blob/main/admin/app/components/solidus_admin/products/show/component.html.erb
• samples to add the new attribute to seeded products: https://github.com/solidusio/solidus/blob/main/sample/db/samples/products.rb

Thanks

Sure @kennyadsl Let me update those as well.
Thanks