@simonecoelhosfo/optimizely-mcp-server
Version:
Optimizely MCP Server for AI assistants with integrated CLI tools
1,135 lines • 108 kB
JavaScript
/**
* Model-Friendly Entity Templates with Ref Pattern
* @description Machine-parsable templates using JSON Schema format with adopt-or-create ref helpers
*
* Key improvements over traditional templates:
* - Single source of truth per template
* - Standard JSON Schema format
* - Ref pattern for flexible entity references
* - Token-efficient (~200-300 tokens vs ~2000+)
* - Complete working examples
*
* @author Optimizely MCP Server
* @version 2.0.0
*/
/**
* Model-Friendly Templates by Entity Type
*/
export const MODEL_FRIENDLY_TEMPLATES = {
// =============================================================================
// FLAG TEMPLATE - Feature Experimentation
// =============================================================================
flag: {
template_id: "flag_v1",
entity_type: "flag",
schema: 1,
platform: "feature",
complexity_score: 5,
description: "Create a feature flag with optional variables and A/B test",
critical_rules: [
"default_value MUST match variable type exactly",
"Traffic allocation MUST sum to exactly 10000",
"Flag key MUST use snake_case (no spaces)",
"⚠️ INCLUDING variables TRIGGERS RULESET CREATION - for simple on/off flags, use ONLY key, name, and description"
],
usage_guidance: {
simple_flag: {
description: "For basic on/off toggles without configuration",
structure: "Include ONLY key, name, and description",
warning: "Do NOT include variables or ab_test fields"
},
targeted_delivery: {
description: "For flags with configuration but no experimentation",
structure: "Include variables but NOT ab_test",
note: "This creates a ruleset with a single 'on' variation"
},
ab_test_flag: {
description: "For flags with experimentation",
structure: "Include both variables AND ab_test",
note: "This creates full A/B test infrastructure with metrics"
}
},
fields: {
key: {
type: "string",
description: "Unique flag identifier using snake_case",
required: true,
examples: { valid: "checkout_flow_v2", invalid: "checkout flow" }
},
name: {
type: "string",
description: "Display name for the flag",
required: true,
examples: { sample: "Checkout Flow Redesign" }
},
description: {
type: "string",
description: "Flag purpose and context",
required: false
},
variables: {
type: "array",
description: "Variable definitions for dynamic configuration",
required: false,
items: {
type: "object",
properties: {
key: {
type: "string",
required: true,
description: "Variable identifier using snake_case"
},
type: {
enum: ["string", "boolean", "integer", "double", "json"],
required: true,
descriptions: {
string: "Text values - default_value: \"sample_text\"",
boolean: "True/false values - default_value: \"false\"",
integer: "Whole numbers - default_value: \"42\"",
double: "Decimal numbers - default_value: \"9.99\"",
json: "JSON strings - default_value: \"{\\\"key\\\": \\\"value\\\"}\""
}
},
default_value: {
type: "string",
required: true,
description: "MUST be a string that matches variable type. Examples: \"false\" (boolean), \"42\" (integer), \"9.99\" (double), \"text\" (string), \"{\\\"key\\\": \\\"value\\\"}\" (json)"
},
description: { type: "string", required: false }
}
},
examples: {
string_variable: { key: "button_text", type: "string", default_value: "Buy Now", description: "CTA button text" },
boolean_variable: { key: "feature_enabled", type: "boolean", default_value: "false", description: "Enable new feature" },
integer_variable: { key: "discount_percent", type: "integer", default_value: "15", description: "Percentage discount" },
double_variable: { key: "shipping_rate", type: "double", default_value: "9.99", description: "Shipping cost" },
json_variable: { key: "ui_config", type: "json", default_value: "{\"theme\": \"dark\", \"size\": \"large\"}", description: "UI configuration" }
}
},
ab_test: {
type: "object",
description: "A/B test configuration with traffic allocation",
required: false,
properties: {
environment: { $ref: "EnvironmentRef" },
variations: {
type: "array",
description: "Test variations with variable values",
items: {
type: "object",
properties: {
key: {
type: "string",
required: true,
description: "Variation identifier (e.g., 'control', 'treatment')"
},
name: {
type: "string",
required: true,
description: "Display name for variation"
},
variable_values: {
type: "object",
description: "Use your actual variable keys as properties. ALL values MUST be strings for Feature Experimentation API.",
examples: {
string_vars: { button_text: "Buy Now", headline: "Special Offer" },
boolean_vars: { feature_enabled: "true", show_banner: "false" },
integer_vars: { discount_percent: "15", max_items: "10" },
double_vars: { shipping_rate: "9.99", tax_rate: "0.08" },
json_vars: { ui_config: "{\"theme\": \"dark\", \"size\": \"large\"}" }
}
}
}
}
},
traffic_allocation: {
type: "object",
description: "Basis points allocation (10000 = 100%). Use variation keys as properties. MUST sum to exactly 10000.",
examples: {
single_variation: { treatment: 10000 },
two_variations: { control: 5000, treatment: 5000 },
three_variations: { control: 3333, variation_1: 3333, variation_2: 3334 },
four_variations: { control: 2500, var_a: 2500, var_b: 2500, var_c: 2500 }
}
},
metrics: {
type: "array",
items: { $ref: "MetricRef" }
},
audience: { $ref: "AudienceRef" }
}
}
},
ref_patterns: {
environment: "{ ref: { key: 'production' } }",
metric_existing: "{ ref: { key: 'purchase_completed' } }",
metric_create: "{ ref: { auto_create: true, template: { key: 'signup', name: 'User Signup' } } }",
audience_existing: "{ ref: { id: 12345 } }",
audience_create: "{ ref: { auto_create: true, template: { name: 'Mobile Users', conditions: '[...]' } } }"
},
example_filled: {
key: "checkout_redesign",
name: "Checkout Redesign Test",
description: "Testing new checkout flow with multiple variable types",
variables: [
{
key: "button_text",
type: "string",
default_value: "Buy Now",
description: "CTA button text"
},
{
key: "express_checkout_enabled",
type: "boolean",
default_value: "false",
description: "Enable one-click checkout feature"
},
{
key: "discount_percent",
type: "integer",
default_value: "10",
description: "Percentage discount to display"
},
{
key: "shipping_rate",
type: "double",
default_value: "9.99",
description: "Shipping cost calculation"
},
{
key: "ui_config",
type: "json",
default_value: "{\"theme\": \"modern\", \"animation\": \"fade\", \"layout\": \"compact\"}",
description: "UI configuration object"
}
],
ab_test: {
environment: { ref: { key: "production" } },
variations: [
{
key: "control",
name: "Original",
variable_values: {
button_text: "Buy Now",
express_checkout_enabled: "false",
discount_percent: "10",
shipping_rate: "9.99",
ui_config: { "theme": "classic", "animation": "none", "layout": "standard" }
}
},
{
key: "treatment",
name: "Enhanced Experience",
variable_values: {
button_text: "Complete Purchase",
express_checkout_enabled: "true",
discount_percent: "15",
shipping_rate: "7.99",
ui_config: { "theme": "modern", "animation": "fade", "layout": "compact" }
}
}
],
traffic_allocation: {
control: 5000,
treatment: 5000
},
metrics: [
{ ref: { key: "purchase_completed" } },
{
ref: {
auto_create: true,
template: {
key: "checkout_abandoned",
name: "Checkout Abandoned",
event_type: "custom"
}
}
}
]
}
},
example_everyone_targeting: {
key: "everyone_test",
name: "Test for Everyone",
description: "Simple test targeting all users without any audience restrictions",
ab_test: {
environment: { ref: { key: "development" } },
variations: [
{ key: "control", name: "A", variable_values: {} },
{ key: "treatment", name: "B", variable_values: {} }
],
traffic_allocation: { control: 5000, treatment: 5000 }
// No 'audience' field → targets everyone
}
},
example_simple: {
key: "maintenance_mode",
name: "Maintenance Mode Toggle",
description: "Enable/disable maintenance mode for the application"
// ⚠️ NOTE: No variables or ab_test - creates a basic on/off flag
// This is the simplest form of a feature flag
}
},
// =============================================================================
// EXPERIMENT TEMPLATE - Web Experimentation
// =============================================================================
experiment: {
template_id: "experiment_web_v1",
entity_type: "experiment",
schema: 1,
platform: "web",
complexity_score: 4,
description: "Create web A/B test experiment (for metrics tracking). For personalization without metrics, use personalization_experiment template.",
critical_rules: [
"Variation weights MUST sum to exactly 10000 (basis points)",
"Change type MUST be valid enum value from list below",
"Page reference required - use auto_create for new pages"
],
fields: {
name: {
type: "string",
required: true,
description: "Experiment name",
examples: { valid: "Homepage Hero Test", invalid: "" }
},
description: {
type: "string",
description: "Experiment hypothesis or purpose"
},
page: {
$ref: "PageRef",
required: true,
description: "Target page for experiment"
},
variations: {
type: "object",
description: "Variation definitions with weight allocation (10000 total)",
properties: {
control: {
type: "object",
properties: {
weight: { type: "integer", min: 0, max: 10000, required: true },
actions: { type: "array", default: [] }
}
}
},
examples: {
two_way: {
control: { weight: 5000, actions: [] },
treatment: { weight: 5000, actions: [{ changes: [{ type: "insert_html", selector: ".hero-title", value: "<h1>New Title</h1>" }] }] }
},
three_way: {
control: { weight: 3333, actions: [] },
variation_1: { weight: 3333, actions: [{ changes: [{ type: "custom_css", value: ".btn { background: red; }" }] }] },
variation_2: { weight: 3334, actions: [{ changes: [{ type: "attribute", selector: ".btn", attribute_name: "class", value: "btn-primary" }] }] }
},
four_way: {
control: { weight: 2500, actions: [] },
var_a: { weight: 2500, actions: [{ changes: [{ type: "insert_html", selector: ".cta", value: "<button>Get Started</button>" }] }] },
var_b: { weight: 2500, actions: [{ changes: [{ type: "insert_image", selector: ".hero-img", value: "https://cdn.example.com/hero-b.jpg" }] }] },
var_c: { weight: 2500, actions: [{ changes: [{ type: "custom_code", value: "console.log('Variation C tracked');" }] }] }
}
}
},
type: {
enum: ["a/b", "multivariate"],
default: "a/b",
required: true,
description: "Experiment type - use a/b for standard testing"
},
audience: {
$ref: "AudienceRef",
description: "Target audience (omit to target everyone)",
examples: {
everyone: "// Omit audience field entirely",
existing: "{ ref: { id: 12345 } }",
new: "{ ref: { auto_create: true, template: { name: 'Premium Users', conditions: '[...]' } } }"
}
},
metrics: {
type: "array",
items: { $ref: "WebMetricRef" },
description: "Success metrics to track"
}
},
ref_patterns: {
page_existing: "{ ref: { name: 'Homepage' } }",
page_create: "{ ref: { auto_create: true, template: { name: 'Landing Page', edit_url: 'https://example.com' } } }",
change_html: "{ type: 'insert_html', selector: '.hero', value: '<h1>New Title</h1>' }",
change_css: "{ type: 'custom_css', value: '.btn { background: blue; }' }",
change_js: "{ type: 'custom_code', value: 'console.log(\"variant active\");' }",
metric_event: "{ event_id: 12345, aggregator: 'unique', scope: 'visitor', winning_direction: 'increasing' }"
},
example_filled: {
name: "Homepage Hero CTA Test",
description: "Testing hero button copy and color variations",
type: "a/b",
page: {
ref: {
auto_create: true,
template: {
name: "Homepage",
edit_url: "https://www.mystore.com",
activation_type: "immediate"
}
}
},
variations: {
control: {
weight: 5000,
actions: []
},
treatment: {
weight: 5000,
actions: [{
changes: [
{
type: "insert_html",
selector: ".hero-cta",
value: "<button class='cta-btn'>Start Your Free Trial</button>"
},
{
type: "custom_css",
value: ".cta-btn { background: #ff6b35; color: white; padding: 12px 24px; }"
}
]
}]
}
},
metrics: [{
event_id: 17480030871,
aggregator: "unique",
scope: "visitor",
winning_direction: "increasing"
}]
}
},
// =============================================================================
// CAMPAIGN TEMPLATE - Web Experimentation
// =============================================================================
campaign: {
template_id: "campaign_v1",
entity_type: "campaign",
schema: 1,
platform: "web",
complexity_score: 3,
description: "Create campaign container for grouping experiments. For personalization, create campaign first, then add experiments.",
critical_rules: [
"Both 'personalization' and 'ab' campaigns support metrics",
"Type 'ab' campaigns are for A/B testing with shared metrics",
"Type 'personalization' campaigns are for audience-based experiences",
"Holdback traffic in basis points (10000 = 100%)"
],
fields: {
name: {
type: "string",
required: true,
description: "Campaign display name",
examples: { valid: "Q4 Homepage Optimization", invalid: "" }
},
description: {
type: "string",
description: "Campaign purpose or goal"
},
type: {
enum: ["ab", "personalization"],
default: "ab",
required: true,
descriptions: {
ab: "A/B test container - groups experiments with shared metrics",
personalization: "Experience container - no metrics, audience-based experiences"
},
examples: {
ab_use_cases: ["Homepage optimization", "Product page tests", "Checkout flow testing"],
personalization_use_cases: ["Geographic targeting", "User segment experiences", "Behavioral personalization"]
}
},
pages: {
type: "array",
items: { $ref: "PageRef" },
description: "Target pages for campaign"
},
experiments: {
type: "array",
items: { $ref: "ExperimentRef" },
description: "Experiments within this campaign (usually added after creation)"
},
holdback: {
type: "integer",
min: 0,
max: 10000,
default: 0,
description: "Traffic holdback percentage in basis points (1000 = 10%)"
},
metrics: {
type: "array",
items: {
type: "object",
properties: {
event_id: { type: "integer", description: "ID of the event to track" },
scope: { enum: ["visitor", "session"], default: "visitor", description: "Metric aggregation scope" },
winning_direction: { enum: ["increasing", "decreasing"], description: "Direction of improvement" }
}
},
description: "Success metrics to track for the campaign (supported for both 'ab' and 'personalization' types)"
}
},
ref_schemas: {
ExperimentRef: {
type: "object",
properties: {
ref: {
properties: {
id: { type: "number" },
name: { type: "string" }
}
}
}
}
},
example_filled: {
name: "Homepage Optimization Campaign",
description: "Testing hero section and CTA variations",
type: "ab",
pages: [
{ ref: { name: "Homepage" } }
],
holdback: 500
},
example_personalization: {
name: "Geographic Personalization",
description: "Location-based experiences",
type: "personalization",
pages: [
{ ref: { name: "Landing Page" } }
],
holdback: 0
}
},
// =============================================================================
// PERSONALIZATION EXPERIMENT TEMPLATE - Web Experimentation
// =============================================================================
personalization_experiment: {
template_id: "personalization_experiment_v1",
entity_type: "experiment",
schema: 1,
platform: "web",
complexity_score: 4,
description: "Create personalization experiment (actual experience). Must belong to personalization campaign.",
critical_rules: [
"Type MUST be 'personalization' (not 'a/b')",
"Campaign reference is REQUIRED - cannot exist without parent campaign",
"Personalization experiments focus on audience-based experiences"
],
fields: {
name: {
type: "string",
required: true,
description: "Experiment name within campaign",
examples: { valid: "SF Visitors Special Offer", invalid: "" }
},
description: {
type: "string",
description: "Personalized experience description"
},
type: {
type: "string",
const: "personalization",
required: true,
description: "Must be exactly 'personalization'"
},
campaign: {
$ref: "CampaignRef",
required: true,
description: "Parent personalization campaign reference"
},
audience: {
$ref: "AudienceRef",
description: "Target audience for personalization"
},
pages: {
type: "array",
items: { $ref: "PageRef" },
description: "Target pages for personalization"
},
variations: {
type: "object",
description: "Personalized experience variations (no metrics)",
properties: {
control: {
type: "object",
properties: {
weight: { type: "integer", min: 0, max: 10000, required: true },
actions: { type: "array", default: [] }
}
}
},
examples: {
geographic: {
control: { weight: 0, actions: [] },
sf_experience: { weight: 10000, actions: [{ changes: [{ type: "insert_html", selector: ".banner", value: "<div>SF Special!</div>" }] }] }
},
behavioral: {
default: { weight: 0, actions: [] },
vip_treatment: { weight: 10000, actions: [{ changes: [{ type: "insert_html", selector: ".header", value: "<div>Welcome back VIP!</div>" }] }] }
}
}
},
status: {
enum: ["not_started", "running", "paused"],
default: "not_started",
description: "Experiment status"
},
traffic_allocation: {
type: "integer",
min: 0,
max: 10000,
default: 10000,
description: "Traffic percentage (10000 = 100%)"
},
holdback: {
type: "integer",
min: 0,
max: 10000,
default: 0,
description: "Holdback percentage"
}
},
ref_schemas: {
CampaignRef: {
oneOf: [
{
type: "object",
properties: {
ref: {
properties: {
id: { type: "number" },
name: { type: "string" }
}
}
}
},
{
type: "object",
properties: {
ref: {
properties: {
auto_create: { type: "boolean", const: true },
template: {
properties: {
name: { type: "string", required: true },
type: { type: "string", const: "personalization", required: true }
}
}
}
}
}
}
]
}
},
example_filled: {
name: "Geographic Personalization",
description: "Location-based special offers",
type: "personalization",
campaign: {
ref: {
auto_create: true,
template: {
name: "Q1 Geo Targeting",
type: "personalization"
}
}
},
audience: {
ref: {
auto_create: true,
template: {
name: "SF Visitors",
conditions: '["and", {"type": "location", "value": "US-CA-SANFRANCISCO"}]'
}
}
},
pages: [
{ ref: { name: "Landing Page" } }
],
variations: {
control: { weight: 0, actions: [] },
sf_special: {
weight: 10000,
actions: [{
changes: [{
type: "insert_html",
selector: ".offer-banner",
value: "<div class='special'>SF Exclusive: 20% Off!</div>"
}]
}]
}
}
},
example_multiple_audiences: {
name: "Multi-Audience Personalization",
description: "Target users who are both mobile AND premium tier",
type: "personalization",
campaign: {
ref: {
id: 12345
}
},
// NEW: Multiple audiences with AND operator
audiences: [
{ ref: { id: 98765 } }, // Mobile users audience
{ ref: { id: 54321 } } // Premium tier audience
],
audiences_operator: "and", // User must be in BOTH audiences
pages: [
{ ref: { name: "Checkout Page" } }
],
variations: {
control: { weight: 0, actions: [] },
mobile_premium_experience: {
weight: 10000,
actions: [{
changes: [{
type: "insert_html",
selector: ".checkout-header",
value: "<div class='premium-mobile'>Exclusive Mobile Premium Checkout</div>"
}]
}]
}
}
}
},
// =============================================================================
// SHARED TEMPLATES
// =============================================================================
event: {
template_id: "event_v1",
entity_type: "event",
schema: 1,
platform: "both",
complexity_score: 1,
description: "Create event for tracking user actions and conversions",
critical_rules: [
"All fields are optional - event can be minimal",
"Event type determines tracking behavior",
"Properties enable advanced segmentation"
],
fields: {
key: {
type: "string",
description: "Unique event identifier (snake_case recommended)",
examples: { valid: "add_to_cart", recommended: "purchase_completed" }
},
name: {
type: "string",
description: "Human-readable display name",
examples: { valid: "Add to Cart", recommended: "Purchase Completed" }
},
event_type: {
enum: ["custom"],
default: "custom",
description: "Event type for custom events - MUST be 'custom' for user-defined events. Only 'custom' is supported for user-created events. Other types like 'click', 'pageview', 'conversion' are system-managed.",
examples: {
correct: "custom",
incorrect: "conversion" // This will be auto-corrected to "custom"
}
},
event_properties: {
type: "array",
description: "Custom tracking properties for segmentation",
items: {
type: "object",
properties: {
name: { type: "string" },
data_type: { enum: ["string", "number", "boolean"] }
}
},
examples: {
ecommerce: [
{ name: "product_id", data_type: "string" },
{ name: "price", data_type: "number" },
{ name: "is_premium", data_type: "boolean" }
]
}
}
},
example_filled: {
key: "signup_completed",
name: "User Signup",
event_type: "conversion"
},
example_with_properties: {
key: "product_purchased",
name: "Product Purchase",
event_type: "conversion",
event_properties: [
{ name: "category", data_type: "string" },
{ name: "amount", data_type: "number" }
]
}
},
audience: {
template_id: "audience_v1",
entity_type: "audience",
schema: 1,
platform: "both",
complexity_score: 2,
description: "Create an audience for targeting",
critical_rule: "CONDITIONS MUST BE JSON STRING, NOT OBJECT - #1 error cause",
fields: {
name: {
type: "string",
description: "Audience display name",
required: true,
examples: { sample: "Mobile Premium Users" }
},
conditions: {
type: "string",
description: "Targeting conditions as JSON string. Operators: and, or, not. Use JSON.stringify() if starting with object.",
required: true,
examples: {
simple_cookie: '["and", {"type": "cookies", "name": "user_type", "match_type": "exact", "value": "premium"}]',
mobile_users: '["and", {"type": "device", "value": "mobile"}]',
us_users: '["and", {"type": "location", "value": "US"}]',
mobile_us_premium: '["and", {"type": "device", "value": "mobile"}, {"type": "location", "value": "US"}, {"type": "cookies", "name": "tier", "match_type": "exact", "value": "premium"}]',
complex_nested: '["and", {"type": "device", "value": "mobile"}, ["or", {"type": "location", "value": "US"}, {"type": "location", "value": "CA"}]]',
fx_custom_attribute: '["and", {"type": "custom_attribute", "name": "User Tier", "value": "premium"}]'
},
descriptions: {
cookies: 'Format: {"type": "cookies", "name": "cookie_name", "match_type": "exists|exact|substring|regex", "value": "cookie_value"}',
device: 'Format: {"type": "device", "value": "mobile|tablet|desktop|iphone|ipad"}',
location: 'Format: {"type": "location", "value": "US|CA|UK|DE|FR|AU|JP|BR|MX|IN|CN|SANFRANCISCO|NEWYORK|LONDON"}',
browser_version: 'Format: {"type": "browser_version", "value": "ff|ie|ie8|ie9|ie10|ie11|edge|safari|gc|opera|ucbrowser"}',
platform: 'Format: {"type": "platform", "value": "ios|android|windows|mac os|linux|windows phone|blackberry"}',
language: 'Format: {"type": "language", "value": "en|es|fr|de|zh|ja|ko|pt|ru|ar|hi|it|nl|sv|pl"}',
source_type: 'Format: {"type": "source_type", "value": "direct|search|referral|campaign"}',
custom_attribute: 'Format: {"type": "custom_attribute", "name": "ATTRIBUTE_NAME", "match_type": "exact|exists|substring|gt|lt|gte|lte", "value": "target_value"} - FX uses attribute NAME, Web uses key OR name',
code: 'Format: {"type": "code", "value": "javascript_expression"}',
query: 'Format: {"type": "query", "name": "param_name", "match_type": "exists|exact|substring|regex", "value": "param_value"}'
}
}
},
example_filled: {
name: "Mobile Premium Users",
conditions: '["and", {"type": "device", "value": "mobile"}, {"type": "cookies", "name": "user_tier", "match_type": "exact", "value": "premium"}]'
}
},
attribute: {
template_id: "attribute_v1",
entity_type: "attribute",
schema: 1,
platform: "both",
complexity_score: 1,
description: "Create custom attribute for audience targeting",
critical_rules: [
"Key must be unique and use snake_case format",
"Name is display-friendly version of key",
"Used in audience conditions for targeting"
],
fields: {
key: {
type: "string",
required: true,
description: "Unique attribute identifier (snake_case, no spaces)",
examples: { valid: "subscription_tier", invalid: "subscription tier" }
},
name: {
type: "string",
description: "Human-readable display name",
examples: { recommended: "Subscription Tier", alternative: "User Type" }
},
condition_type: {
enum: ["custom_attribute", "custom_dimension"],
default: "custom_attribute",
descriptions: {
custom_attribute: "Standard custom attribute (recommended)",
custom_dimension: "Legacy custom dimension (read-only)"
}
}
},
example_filled: {
key: "user_tier",
name: "User Tier",
condition_type: "custom_attribute"
}
},
// =============================================================================
// RULESET TEMPLATE - Feature Experimentation
// =============================================================================
ruleset: {
template_id: "ruleset_basic_v1",
entity_type: "ruleset",
schema: 1,
platform: "feature",
complexity_score: 2,
description: "Update ruleset configuration for flag environment",
critical_rules: [
"Flag key and environment key must exist in project",
"Rule priorities ordered from highest to lowest",
"JSON patch operations required for updates"
],
fields: {
flag_key: {
type: "string",
required: true,
description: "Target flag identifier",
examples: { valid: "checkout_flow", recommended: "new_feature_v2" }
},
environment_key: {
type: "string",
required: true,
description: "Target environment",
examples: { common: ["production", "staging", "development"] }
},
rule_priorities: {
type: "array",
required: true,
description: "Rule keys in priority order (first = highest)",
examples: {
simple: ["all_users"],
multi_tier: ["premium_users", "standard_users"],
complex: ["vip_users", "beta_users", "regular_users"]
}
},
enabled: {
type: "boolean",
default: false,
description: "Activate/deactivate ruleset"
}
},
example_filled: {
flag_key: "feature_toggle",
environment_key: "production",
rule_priorities: ["premium_users"],
enabled: true
}
},
ruleset_advanced: {
template_id: "ruleset_advanced_v1",
entity_type: "ruleset",
schema: 1,
platform: "feature",
complexity_score: 5,
description: "Advanced ruleset with complex multi-tier targeting and mutual exclusion",
critical_rules: [
"Complex rule hierarchies require careful priority planning",
"Test staging before production rollout",
"Monitor traffic allocation and performance metrics"
],
fields: {
flag_key: {
type: "string",
required: true,
description: "Target flag identifier (advanced features)",
examples: { complex: "ai_recommendation_engine", enterprise: "personalized_checkout_v3" }
},
environment_key: {
type: "string",
required: true,
description: "Target environment",
examples: { production: "production", advanced: ["pre_production", "canary_deployment"] }
},
rule_priorities: {
type: "array",
required: true,
description: "Rule keys in priority order (complex hierarchy)",
examples: {
gradual_rollout: ["internal_team", "beta_users_10pct", "early_adopters_25pct", "full_rollout_100pct"],
user_tiers: ["vip_customers", "enterprise_users", "paid_subscribers", "trial_users", "free_users"],
geographic: ["us_west", "us_east", "europe", "asia_pacific", "rest_of_world"]
}
},
enabled: {
type: "boolean",
default: false,
description: "Activate complex ruleset (enable gradually)"
},
default_variation_key: {
type: "string",
description: "Fallback variation when no rules match",
examples: { safe: "safe_fallback", conservative: "previous_version" }
}
},
example_filled: {
flag_key: "ai_recommendations",
environment_key: "production",
rule_priorities: [
"enterprise_customers",
"beta_users_25pct",
"general_users_5pct"
],
enabled: true,
default_variation_key: "conservative_default"
}
},
// =============================================================================
// RULE TEMPLATE - Feature Experimentation
// =============================================================================
rule: {
template_id: "rule_basic_v1",
entity_type: "rule",
schema: 1,
platform: "feature",
complexity_score: 2,
description: "Create targeting rule for feature delivery",
critical_rules: [
"Rule key must be descriptive (not 'rule1' or 'temp')",
"Percentage in basis points (10000 = 100%)",
"Type determines delivery behavior"
],
fields: {
key: {
type: "string",
required: true,
description: "Unique rule identifier (snake_case)",
examples: { valid: "premium_users", recommended: "mobile_logged_in" }
},
name: {
type: "string",
required: true,
description: "Human-readable rule name",
examples: { valid: "Premium Users", recommended: "Mobile Logged-in Users" }
},
type: {
enum: ["targeted_delivery", "a/b", "multi_armed_bandit"],
required: true,
descriptions: {
targeted_delivery: "Simple delivery to audience (most common)",
"a/b": "Split test with traffic allocation",
multi_armed_bandit: "AI-optimized allocation"
}
},
audience_conditions: {
type: "array",
description: "Targeting conditions",
examples: {
simple: ["and", { "custom_attribute": "tier", "value": "premium" }],
everyone: "everyone"
}
},
percentage_included: {
type: "number",
min: 0,
max: 10000,
description: "Traffic percentage (basis points: 5000 = 50%)",
examples: {
full_rollout: 10000,
half_traffic: 5000,
small_test: 1000
}
}
},
example_filled: {
key: "premium_users",
name: "Premium Users",
type: "targeted_delivery",
audience_conditions: ["and", { "custom_attribute": "tier", "value": "premium" }],
percentage_included: 10000
}
},
rule_advanced: {
template_id: "rule_advanced_v1",
entity_type: "rule",
schema: 1,
platform: "feature",
complexity_score: 5,
description: "Complex targeting rule with multi-dimensional audience conditions",
critical_rules: [
"Start with LOW traffic allocation (100-500 basis points)",
"Include key audience dimensions in rule name",
"Test complex conditions in staging first"
],
fields: {
key: {
type: "string",
description: "Descriptive rule identifier (snake_case)",
required: true,
examples: {
valid: "enterprise_tier_north_america_mobile",
descriptive: "high_value_customers_premium_support",
cohort: "beta_testers_early_adopters_q4"
}
},
name: {
type: "string",
description: "Human-readable display name",
required: true
},
type: {
enum: ["targeted_delivery", "a/b", "multi_armed_bandit"],
description: "Rule type with behavior",
required: true,
descriptions: {
targeted_delivery: "Precise delivery to specific segments",
"a/b": "Multi-variant testing with stats",
multi_armed_bandit: "AI-optimized allocation (recommended for complex rules)"
}
},
audience_conditions: {
type: "array",
description: "Multi-dimensional targeting (nested arrays)",
examples: {
enterprise_geo: ["and", { "custom_attribute": "tier", "value": "enterprise" }, { "custom_attribute": "region", "value": "north_america" }],
behavioral: ["and", { "custom_attribute": "last_login_days", "operator": "<=", "value": "7" }, { "custom_attribute": "usage_score", "operator": ">=", "value": "80" }],
complex: ["and", ["or", { "audience_id": 12345 }, { "audience_id": 67890 }], ["not", { "custom_attribute": "beta_excluded", "value": "true" }]]
}
},
percentage_included: {
type: "number",
description: "Traffic allocation (basis points: 10000 = 100%)",
min: 0,
max: 10000,
examples: {
conservative: [100, 250, 500, 1000],
gradual: [500, 1000, 2500, 5000, 7500, 10000],
ab_test: [2500, 2500, 5000]
}
},
enabled: {
type: "boolean",
description: "Rule activation status",
default: true
}
},
example_filled: {
key: "enterprise_customers_north_america_premium",
name: "Enterprise NA Premium Features Beta",
type: "multi_armed_bandit",
audience_conditions: [
"and",
{ "custom_attribute": "account_tier", "value": "enterprise" },
{ "custom_attribute": "region", "value": "north_america" }
],
percentage_included: 500,
enabled: true
}
},
// =============================================================================
// PAGE TEMPLATE - Web Experimentation
// =============================================================================
page: {
template_id: "page_basic_v1",
entity_type: "page",
schema: 1,
platform: "web",
complexity_score: 2,
description: "Create page for web experiment targeting",
critical_rules: [
"Edit URL must include full protocol (https://)",
"Activation type determines when experiments start",
"Use 'immediate' for standard websites"
],
fields: {
name: {
type: "string",
required: true,
description: "Page display name",
examples: { valid: "Homepage", recommended: "Product Landing Page" }
},
edit_url: {
type: "string",
required: true,
description: "Full URL with protocol (https://example.com/page)",
examples: {
valid: