Proposal to add support for customs declaration code

[Radiergummi]

Context - This is a proposal from Matchory; we build a comprehensive database of manufacturing companies, their customers, and shipments between them. Currently, we have a database of around 10 million companies and about 800 million individual shipments, all structured as an extended schema.org vocabulary, stored as JSON-LD.
While designing the data structure, we had to come up with several additional properties; some of them are too specific to B2B shipping for schema.org (we plan to publish our own vocabulary in the future), but others would make good candidates for inclusion. This is one of them.

Proposal - Schema.org already provides a lot of properties for shipments and trading (#3122 being highly anticipated); we would like to propose adding a property for the customs declaration code from the internationally used Harmonized System. More than 200 countries are members in the issuing organisation and use those codes for imported and exported goods. Every merchant buying and every supplier selling goods knows, and searches for, those codes. Every participating country requires these codes to be declared for goods leaving and entering customs.

An HS code is a hierarchical, numeric string, consisting of three two-digit groups of wares, from less to more specific. This makes them ideal for broadly categorising products. As HS is an internationally used and maintained standard, it fosters interoperability across vendors and platforms.

Therefore, we'd like to propose to add a new hsCode property to the Demand and Offer classes. This would fit in well with the existing gtin property, but provide a way to express offers or demand for a category of products, not just a single instance.

Alternatives - Currently, we use the category property to store the HS code, but that is only available on Offer, not Demand, and it doesn't feel particularly correct to store the customs classification code in a general product category.

It's our -- my -- first time contributing to schema.org, so apologies for any missteps. I'm more than happy to carry this forward, though.

[github-actions[bot]]

This issue is being nudged due to inactivity.

[danbri]

Interesting proposal. Are you actively using Demand, or you mention it for symmetry?

On Sun, 22 Jan 2023 at 02:34, github-actions[bot] @.***> wrote:

This issue is being nudged due to inactivity.

— Reply to this email directly, view it on GitHub https://github.com/schemaorg/schemaorg/issues/3197#issuecomment-1399388841, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABJSGOBHLQ363377HPIOSLWTSMCBANCNFSM6AAAAAARMH7JZA . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[Radiergummi]

That's a good question. Right now, we pretty much only use Offer, because we can only infer demand from the existing trading we know about. In the future however, we plan on integrating demand from our customers, at which point we'll also use the Demand class in our data schema.

[danbri]

Thanks. If we add schema.org terms, web publishers, SEOs etc wonder whether the ought to add such markup to public web pages. Do you see this as addressing those usecases, or having value elsewhere? We have "value elsewhere" terms already, so that isn't a blocker, ... but ideally the usage ought to be publicly visible, or documented, or otherwise not totally hidden away. Are you data structures exposed in an API, query service, public or partner collaborations etc?

On Sun, 22 Jan 2023 at 11:22, Moritz Friedrich @.***> wrote:

That's a good question. Right now, we pretty much only use Offer, because we can only infer demand from the existing trading we know about. In the future however, we plan on integrating demand from our customers, at which point we'll also use the Demand class in our data schema.

— Reply to this email directly, view it on GitHub https://github.com/schemaorg/schemaorg/issues/3197#issuecomment-1399458233, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABJSGNNY2SLHPE22YEVALLWTUJ6NANCNFSM6AAAAAARMH7JZA . You are receiving this because you commented.Message ID: @.***>

[Radiergummi]

I do see a direct value proposition for search engines other than our own here. HS codes describe the commodities manufactured by any company in well-known categories. Adding such information to schema data for companies, and making it accessible for searching, massively improves the current state of supplier research.

Do you see this as addressing those usecases, or having value elsewhere?

There are several large platforms on the web that offer companies to create a public profile. Some of those platforms provide structured schema data already. By adding the capability to specify a demand or an offer for goods in a standardised way, vendors like us could increase visibility and usefulness for users.

Relevant providers of public profiles might include Alibaba, Dun&Bradstreet, Panjiva, or Global Sources, although I'd also cite Google Business Profiles here.
There is also a downstream ecosystem of supply chain/procurement software that would profit from commodity classification data greatly. Such companies would be Beroe, Flexport, or Forto, for example, but the market is growing steadily.

Are you data structures exposed in an API, query service, public or partner collaborations etc?

Not yet. We do have an older version of our index online (see here), but working on opening up our newer, schema-based supplier search engine to the public (mostly a funding question).

[alex-jansen]

Nice proposal, it seems a straightforward and useful way of supporting an accepted standard for product categorization. We should also add the proposed hsCode property to the Product class though, since it it seems to naturally belong to Products, maybe even more than Offers (which are typically nested under Products).

[Radiergummi]

We should also add the proposed hsCode property to the Product class though, since it it seems to naturally belong to Products, maybe even more than Offers (which are typically nested under Products).

Adding it to Product seems like a good idea. I'm not quite sure how to express an intent to buy a certain range of products, or an ability to sell or manufacture such a range; that is what we use Offer and Demand for, although I realise we're probably stretching the original definitions quite a bit here.
If that is something too obscure or too niche for Schema.org, that's completely fine, however.

[github-actions[bot]]

This issue is being nudged due to inactivity.