How We Standardized WooCommerce Product Imports with a Folder-Based Schema

Obteohub — Tue, 22 Sep 2026 06:41:31 +0000

When product catalogs grow, importing products into WooCommerce becomes less about uploading data and more about controlling data quality. We kept running into the same problems:

Product names stored separately from descriptions; images arriving with inconsistent filenames; attributes structured differently across products
Variations missing required values; categories that did not match the existing catalog; brand, collection, product line, and location data being handled inconsistently

So we created a predictable product package. The result is the Shopwice WooCommerce Product Import Schema, which we have now released publicly on GitHub.

The basic idea

Each product is represented as a folder containing all the data required to validate and import it.

For example:

variable-product/
Example Smartphone/
product.json
attributes.json
variations.json
brand.txt
collection.txt
product-line.txt
location.txt
short.txt
long.txt
images/
01.jpg
02.jpg
03.jpg

Instead of passing one large spreadsheet around, the importer receives a complete product package. That package can then be validated before anything is written to WooCommerce.

Simple and variable products

The schema supports both simple and variable products. A simple product may only require:

product.json
attributes.json
brand.txt
short.txt
long.txt
images/

A variable product additionally includes:

variations.json

The variation file defines combinations such as storage, colour, size, or other variation attributes.

Example:

{
"variations": [
{
"attributes": {
"Storage": "128GB",
"Colour": "Black"
},
"sku": "EXAMPLE-128-BLK"
},
{
"attributes": {
"Storage": "256GB",
"Colour": "Black"
},
"sku": "EXAMPLE-256-BLK"
}
]
}
Validate before importing

One of the most important design decisions is that validation happens before the product reaches WooCommerce. The flow looks roughly like this:

Product package
↓
Schema validation
↓
Attribute validation
↓
Taxonomy validation
↓
Category matching
↓
API
↓
WooCommerce

This prevents malformed or incomplete product data from entering the catalog. Do not silently create categories. One rule we deliberately enforce is that missing categories should not automatically be created by the importer.

If a submitted product references:

Smart Home > Video Doorbells

and that category does not exist in the catalog, the import should fail with something similar to:

CATEGORY_NOT_FOUND

The missing category can then be reviewed and created deliberately before the import is retried.

This helps prevent duplicate or poorly structured categories from slowly damaging the catalog taxonomy.

Attribute validation

The same principle applies to product attributes.

Before creating a variable product, the importer should verify that:

the attribute exists
the value is valid
the attribute is allowed for variations
variation combinations reference valid values
duplicate values are removed
empty values are rejected

A product with invalid variation data should never be partially imported.

Why use separate files?

We considered putting everything into a single JSON document. That can work, but separating some parts of the product package has practical benefits. Descriptions remain easy to edit. Images remain normal files.

Large variation structures stay separate from the core product metadata. Non-technical catalog staff can also work with parts of the package without having to edit one huge JSON file.

Taxonomy data

The structure can also include separate values for:

brand.txt
collection.txt
product-line.txt
location.txt

These are treated independently from the product category. This matters because a brand, product collection, product line, and catalog category represent different relationships. Mixing all of them into the category tree eventually makes large catalogs difficult to manage.

Why we open-sourced it

This schema came out of work on the catalog infrastructure behind Shopwice. We realized the underlying problem is not unique to one marketplace. Any WooCommerce store handling large numbers of products can run into similar problems with inconsistent product data, variation structures, taxonomy mapping, and bulk imports. So we decided to publish the specification and examples publicly.

The project currently includes:

simple product examples
variable product examples
JSON schemas
attribute structures
variation structures
taxonomy guidance
image organization rules
validation documentation
category matching guidance

We have also opened issues for improvements including stricter attribute validation, image validation, category matching, and API validation examples.

Repository

The first public release is available on GitHub: Shopwice WooCommerce Product Import Schema

Obteohub / shopwice-woocommerce-product-import-schema

Open product-data schema for importing simple and variable WooCommerce products using structured folders, JSON, attributes, variations, taxonomy data, descriptions, and images. Built for the Shopwice Import platform.

WooCommerce Product Import Schema

An open, folder-based specification for preparing and validating e-commerce product data before importing it into WooCommerce.

This repository provides a practical structure for simple products, variable products, attributes, variations, brands, product collections, product lines, product locations, descriptions, images, and category validation.

This specification was developed as part of the Shopwice product import infrastructure. The import platform is available at import.shopwice.com.

Why this project exists

Large WooCommerce catalogs become difficult to maintain when product information arrives in inconsistent spreadsheets, folders, image sets, supplier documents, and free-form descriptions.

This project treats each product as a self-contained package. An importer can validate the package first, map its taxonomy against an existing catalog, and only then send the product to WooCommerce through the appropriate API or middleware layer.

ZIP or root folder
      |
      v
Product-type folders
      |
      v
One

…

View on GitHub

The project is currently at v1.0.0.

We developed the schema as part of the product infrastructure behind Shopwice. If you work with large WooCommerce catalogs, product feeds, headless commerce, or marketplace infrastructure, we welcome feedback and contributions.

DEV Community: Obteohub

How We Standardized WooCommerce Product Imports with a Folder-Based Schema

Obteohub / shopwice-woocommerce-product-import-schema

Open product-data schema for importing simple and variable WooCommerce products using structured folders, JSON, attributes, variations, taxonomy data, descriptions, and images. Built for the Shopwice Import platform.

WooCommerce Product Import Schema

Why this project exists