DB011 Product schema and API

[maninderjk]

Ticket

• TicketCode

Description

This PR finalises product schema alignment across database, API contract, and mobile types to fully support cart and recommendations. It standardises the product document shape, adds enrichment metadata, and ensures strict schema validation so only expected fields are accepted.

File Locations:

• database/seeding/schema_definition.json
• api/contracts/product_v1.json
• mobile-app/types/Product.d.ts

Changes:

• database/seeding/schema_definition.json

  • Finalised product document structure with required cart/recommendation fields: barcode, productName, brand, images, categories, allergens, nutriments, nutriscoreGrade, tags
  • Added schema fields for lifecycle and enrichment support: metadata, enrichmentMetadata, dateAdded, lastUpdated, productJson
  • Kept schema compatible for cart snapshot storage and recommendation scoring context.

• api/contracts/product_v1.json

  • Aligned API contract with database and mobile Product type.
  • Added and structured fields for alignment: dateAdded, lastUpdated, metadata, enrichmentMetadata
  • Fixed schema structure so new fields are defined inside properties.
  • Retained strict validation with additionalProperties: false.

• mobile-app/types/Product.d.ts

  • Extended Product typing to match backend contract and DB schema.
  • Added ProductMetadata and enrichment fields: metadata, enrichmentMetadata, dateAdded, lastUpdated
  • Preserved existing cart/recommendation core fields for compatibility.

Feature :
Ensuring product schema consistency for cart and recommendations by aligning database, API contract, and mobile types, with strict validation and enrichment support for better reliability in seeding, retrieval, and recommendation workflows.

Validation:
Contract semantic checks pass for allowed new fields and reject unknown fields.
Pipeline schema validation harness run confirms aligned behaviour on sampled products.

Checks

• All requirements of the ticket have been implemented, or I have commented on any exclusions
• Unit tests have been added or updated for any backend changes (if applicable)
• I have reviewed the Files Changed tab and verified it only contains relevant changes (comment if unsure about any)
• This PR has been reviewed and approved

Screenshots

[s223503101]

the new metadata / enrichmentMetadata / dates / tags (API+DB) and cart-oriented productJson (DB) move you toward DB011, but it is not fully aligned until you either add enrichment, tags, and (if required) productJson to the API + Product, or document that enrichment / productJson / tags are intentionally omitted on the wire and fix enrichment.tags vs tags in indexes and the ProductMetadata split.
Thank you
Ocean

[maninderjk]

Changes Made:

1. Fixed enrichment.tags Index Bug:

   • Corrected schema from enrichment.tags (doesn't exist) → tags (actual field)
   • Clarified indexing strategy: wire-eligible vs DB-only indexes

2. Documented Intentional Field Omissions:

   • productJson, tags, enrichment are DB-only by design (not on wire)
   • Added [WIRE-SENT] vs [DB-ONLY] markers to all schema files
   • Rationale: payload optimization, server-side tracking, mobile reconstruction

3. Clarified ProductMetadata Split:

   • metadata: Data provenance (enrichmentSource, timestamp, quality)
   • enrichmentMetadata: Recommendation scoring (score, reasonTags, similarity)
   • Both sent on wire; intentionally separate for different use cases

Documentation:

• Added _design_notes to DB schema, API contract, and mapping layer
• Created database/DB011_SCHEMA_ALIGNMENT.md: authoritative three-layer architecture guide
• Updated all source files with design rationale