Chapter 6:
Taxonomy Specification via JSON Schema

Introduction

To operationalize my controlled vocabularies, I defined JSON Schema contracts that enforce every facet and data rule for products in the Slow Fashion Catalog. This ensures data quality, predictable UI behavior, and a clear hand-off to engineering.

Objective

Translate my Protégé-modeled taxonomy into Draft 2020-12 JSON Schemas that:

Capture all core product properties
Map each facet (vendor, productType, priceBucket, color, size, material) to a precise enum
Enforce required fields and basic constraints (e.g. non-negative price)

Approach

Extract taxonomy values from the OWL model.
Draft the Product schema, defining types, enums, and required arrays.
Define Facet-Definition schema to describe each filter’s UI mapping.
Validate with sample JSON instances to prove compliance.

Schema Highlights

Full Product Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/slow-fashion-product.json",
  "title": "Slow Fashion Catalog Product",
  "description": "A single product in the Slow Fashion multi-brand catalog.",
  "type": "object",
  "properties": {
    "productId": {
      "description": "Unique identifier matching the PIM primary key.",
      "type": "integer"
    },
    "productName": {
      "description": "Display name of the product.",
      "type": "string"
    },
    "price": {
      "description": "Retail price in USD; must be ≥ 0.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "vendor": {
      "description": "Brand controlled vocabulary.",
      "type": "string",
      "enum": [
        "Eileen Fisher",
        "Matt & Nat",
        "Patagonia",
        "People Tree",
        "Reformation",
        "Stella McCartney"
      ]
    },
    "productType": {
      "description": "Product category (facet).",
      "type": "string",
      "enum": [
        "Bottoms",
        "Dresses",
        "Footwear",
        "Outerwear",
        "Tops"
      ]
    },
    "priceBucket": {
      "description": "Bucketed price range for faceting.",
      "type": "string",
      "enum": [
        "< $100",
        "$100–200",
        "$200–300",
        "> $300"
      ]
    },
    "color": {
      "description": "Normalized swatch value.",
      "type": "string",
      "enum": [
        "Beige",
        "Black",
        "Blue",
        "Olive",
        "Pink",
        "White"
      ]
    },
    "size": {
      "description": "Letter size (XS–XL).",
      "type": "string",
      "enum": [
        "XS",
        "S",
        "M",
        "L",
        "XL"
      ]
    },
    "material": {
      "description": "Primary material from taxonomy.",
      "type": "string",
      "enum": [
        "Linen",
        "Organic Cotton",
        "Recycled Cotton",
        "Recycled Polyester",
        "Silk",
        "Tencel",
        "Vegan Leather"
      ]
    }
  },
  "required": [
    "productId",
    "productName",
    "price",
    "vendor",
    "productType",
    "priceBucket",
    "color",
    "size",
    "material"
  ]
}

2. Facet-Definition Schema (snippet)

{
  "$id": "https://example.com/schemas/slow-fashion-facet-definition.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Facet Definition",
  "type": "object",
  "properties": {
    "facetId": {
      "type": "string",
      "pattern": "^[a-z][a-zA-Z0-9]*$"
    },
    "label": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": ["checkbox","swatch","dropdown"]
    },
    "multiSelect": {
      "type": "boolean"
    },
    "values": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "value": { "type": "string" },
          "label": { "type": "string" },
          "count": { "type": "integer" }
        },
        "required": ["value","label"]
      }
    }
  },
  "required": ["facetId","label","type","multiSelect","values"]
}

3. Sample Product Instance

{
  "productId": 1004,
  "productName": "Eco Wrap Midi Dress",
  "price": 178.00,
  "vendor": "Reformation",
  "productType": "Dresses",
  "priceBucket": "$100–200",
  "color": "Olive",
  "size": "S",
  "material": "Tencel"
}

Impact

By defining these schemas, I created a single source-of-truth that bridges taxonomy design and engineering enforcement—preventing typos, ensuring consistent filtering, and enabling automated validation.

Up Next: Chapter 7 – Hybrid Category Page Information Architecture

Chapter 6: Taxonomy Specification via JSON Schema