Metadata-Driven Data Model
Initiative: Metadata-Driven Data Model
The Bet
We believe a pre-defined metadata schema will reduce data inconsistency because it enforces a single source of truth across all APEX initiatives.
Background
Currently, initiative frontmatter fields are loosely validated — PMs define free-form fields that may diverge across teams and products. This creates inconsistency when querying, reporting, or feeding initiative context into AI tools like the PRD generator and apex-update-initiative skill.
The goal of this initiative is to build a canonical metadata database that every APEX initiative can draw from when being created. This ensures every initiative speaks the same language, enabling accurate filtering, dashboarding, and AI-assisted generation.
Defined Metadata Field Categories
Per docs/feature-details.md, the pre-defined metadata set covers six categories:
| # | Field | Purpose | Example Values |
|---|---|---|---|
| 1 | Segment | Customer segment the initiative targets | Big Brands, Multi-Property, Independent |
| 2 | Asset Type | Hotel/property type the initiative applies to | Airport, Extended Stay, Casino, Resorts, Traditional Hotels |
| 3 | Hotel Class | Service tier classification | Full Service, Limited Service |
| 4 | User Persona | External user roles who benefit | Property RM, DORM, Cluster RM, VP of RM, CCO, Brand Manager, Director of Group Sales |
| 5 | Internal Users | Duetto internal roles who interact with the feature | Customer Success, Data Scientists, App Developer, Product Manager |
| 6 | Capability Category / Capability | Feature domain + specific capability (hierarchical — selecting a category filters to its capabilities) | e.g. Category: Pricing → Capability: Rate Recommendations |
This structured metadata set will be used to populate initiative frontmatter at creation time (via /apex-initiative) and to power cross-initiative filtering, dashboards, and PRD context enrichment.
Success Metrics
| Metric | Baseline | Target | Measurement |
|---|---|---|---|
| Initiative data consistency rate | TBD | >90% schema-valid | validate.py pass rate across all products |
| Time to populate initiative frontmatter | TBD | -30% | PM self-report + git timestamp analysis |
| PRD generation quality score | TBD | +20% | Peer review rating on generated PRDs |
| Metadata field coverage per initiative | TBD | 100% of the 6 categories populated | Frontmatter audit across all products |
| Capability category + capability pairing accuracy | TBD | >95% valid parent-child pairs | Schema validation of hierarchical capability field |
Experiments Planned
- Survey PMs on which metadata fields they find most/least useful (interview-based)
- Prototype a metadata options picker in the
apex-initiativeskill and measure completion time - Measure downstream PRD quality with structured vs. free-form initiative context
Timeline
| Phase | Duration | Activities |
|---|---|---|
| Discovery | 2 weeks | PM interviews, audit of existing initiative fields |
| Experiments | 3 weeks | Prototype metadata picker, A/B PRD quality test |
| Decision | 1 week | Go/no-go on canonical schema definition |