Structured Data (Schema.org)

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/structured-data/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Structured Data is a core feature that auto-generates schema.org JSON-LD markup for products, ratings, and reviews. It enables Google rich snippets (star ratings, pricing, availability) in search results.

The problem

Search engines don’t understand product prices, ratings, or availability; rich results with stars and price don’t appear in Google.

What it does

• Generate Product schema.org markup for all products (price, name, description, availability)
• Generate AggregateRating schema for products with ratings and Review schema for individual reviews
• Support in-stock, out-of-stock, pre-order availability states and custom brand field
• Render JSON-LD in <script type=‘application/ld+json’> tag
• Support manufacturer and identifier (MPN, UPC, ISBN)
• Admin dashboard with schema validation (using Google Rich Results Test) and preview

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Does NOT generate schema for blog articles (reason: separate Article schema feature)
• Does NOT support Local Business schema (reason: limited to product/ecommerce)
• Does NOT track schema indexing by Google (reason: requires Google Search Console API)
• Does NOT auto-generate breadcrumb schema (reason: breadcrumb-navigation is separate feature)

Data model

New fields on products: brand (string, optional), mfn_code (string, optional), upc_code (string, optional). New fields on reviews: rating (int 1-5), author_name (string), review_text (text). Structured data generated dynamically from existing fields.

API

• GET /api/products/:id/schema
• GET /api/products/:id/schema-preview
• POST /api/schema/validate-url {url}

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Schema settings (brand name default, manufacturer name); product edit with MPN, UPC, brand override; validation button running Google Rich Results Test; preview panel showing JSON-LD.

The seam — why this is core

Core owns: schema generation, JSON-LD rendering, storage of schema fields.

Core owns the interface + honest schema.org generator; structured data is content markup, not a per-country obligation or credential.

Dependencies

• Assumes product API exists with price, rating, in_stock, description fields
• Assumes review API exists
• Assumes render engine supports JSON-LD injection

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Product schema.org includes name, description, price, currency, availability
• schema:price is product.price in minor units, schema:currency matches shop.currency
• AggregateRating included if product.rating > 0
• Review schema included for each review with rating and reviewBody
• JSON-LD valid schema.org and passes Google Rich Results validation
• Out-of-stock products have availability=‘OutOfStock’
• Pre-order products have availability=‘PreOrder’
• MPN and UPC codes included if provided
• All storage drivers generate identical schema markup
• Schema rendered even for products with no reviews

Risks

Rating aggregation: if 100 reviews averaging 4.5 stars but only last 5 recent, schema shows outdated rating. Out-of-stock handling: if in_stock field wrong, schema says out-of-stock but actually available. Price changes: if price changes after cached, old price in Google’s index until recrawl. Schema validation: Google Search Console may show rich results failing if malformed.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.