diff --git a/.changeset/creative-standards-protocol.md b/.changeset/creative-standards-protocol.md new file mode 100644 index 000000000..6c2aa62ee --- /dev/null +++ b/.changeset/creative-standards-protocol.md @@ -0,0 +1,11 @@ +--- +"adcontextprotocol": minor +--- + +Add Creative Standards Protocol for brand guideline compliance. + +Provides four tasks: +- `list_creative_features`: Discover available creative compliance features +- `get_creative_standards`: Retrieve creative execution guidelines +- `check_creative`: Evaluate a single creative asset +- `validate_creative_delivery`: Batch validate creatives diff --git a/docs.json b/docs.json index 58153f374..36eb56257 100644 --- a/docs.json +++ b/docs.json @@ -101,6 +101,21 @@ } ] }, + { + "group": "Creative Standards Protocol", + "pages": [ + "docs/governance/creative-standards/index", + { + "group": "Tasks", + "pages": [ + "docs/governance/creative-standards/tasks/list_creative_features", + "docs/governance/creative-standards/tasks/get_creative_standards", + "docs/governance/creative-standards/tasks/check_creative", + "docs/governance/creative-standards/tasks/validate_creative_delivery" + ] + } + ] + }, { "group": "Curation Protocol", "pages": [ diff --git a/docs/governance/creative-standards/index.mdx b/docs/governance/creative-standards/index.mdx new file mode 100644 index 000000000..5ba5755a0 --- /dev/null +++ b/docs/governance/creative-standards/index.mdx @@ -0,0 +1,114 @@ +--- +title: Creative Standards Protocol +sidebarTitle: Overview +description: Evaluate creative execution against brand guidelines +--- + +# Creative Standards Protocol + +The Creative Standards Protocol enables AI agents to evaluate creative assets against brand execution guidelines. Unlike Content Standards (which evaluates where ads run), Creative Standards evaluates how the creative itself adheres to brand guidelines. + +## Use Cases + +- **Logo usage compliance**: Verify logos meet size, clear space, and placement requirements +- **Color palette adherence**: Check that creatives use approved brand colors +- **Typography compliance**: Ensure fonts and text styling follow brand guidelines +- **Messaging consistency**: Evaluate taglines and copy against approved messaging +- **Visual style adherence**: Check imagery, photography style, and visual elements +- **Co-branding requirements**: Verify partner brand usage meets guidelines + +## Architecture + +Creative Standards follows the same agent + token pattern as other governance protocols: + +``` +┌─────────────────┐ ┌──────────────────────────┐ +│ Orchestrator │────▶│ Creative Standards │ +│ (AI Agent) │ │ Agent │ +└─────────────────┘ │ (Brand/Agency Service) │ + │ └──────────────────────────┘ + │ │ + │ ▼ + │ ┌──────────────────────────┐ + │ │ Brand Guidelines │ + │ │ (Design System, Assets) │ + │ └──────────────────────────┘ + │ + ▼ +┌─────────────────┐ +│ Brand Manifest │ +│ (Discovery) │ +└─────────────────┘ +``` + +## Tasks + +The Creative Standards Protocol provides four tasks: + +| Task | Purpose | +|------|---------| +| [list_creative_features](/docs/governance/creative-standards/tasks/list_creative_features) | Discover available creative compliance features | +| [get_creative_standards](/docs/governance/creative-standards/tasks/get_creative_standards) | Retrieve creative execution guidelines | +| [check_creative](/docs/governance/creative-standards/tasks/check_creative) | Evaluate a single creative asset | +| [validate_creative_delivery](/docs/governance/creative-standards/tasks/validate_creative_delivery) | Batch validate delivered creatives | + +## Feature Types + +Creative features follow the same type system as property and content features: + +### Binary Features +Pass/fail checks with clear criteria: +- `logo_present`: Is the brand logo included? +- `approved_tagline`: Does the copy use an approved tagline? +- `click_url_valid`: Does the clickthrough URL work? + +### Quantitative Features +Numeric values within acceptable ranges: +- `logo_clear_space_px`: Minimum clear space around logo (pixels) +- `text_contrast_ratio`: WCAG contrast ratio compliance +- `logo_min_size_px`: Minimum logo dimensions + +### Categorical Features +Values from defined sets: +- `color_palette`: Which approved palette is used (primary, secondary, seasonal) +- `typography_family`: Font family from brand approved list +- `imagery_style`: Photography style (lifestyle, product, abstract) + +## Integration with Brand Manifest + +The [Brand Manifest](/docs/creative/brand-manifest) can reference a Creative Standards agent for automated compliance checking: + +```json +{ + "brand_id": "acme_corp", + "governance": { + "creative_standards_agent": { + "url": "https://creative-compliance.acme.com", + "standards_id": "acme_global_2024" + } + } +} +``` + +## Example Flow + +```mermaid +sequenceDiagram + participant O as Orchestrator + participant CS as Creative Standards Agent + participant BM as Brand Manifest + + O->>BM: Discover creative standards agent + BM-->>O: Return agent URL + standards_id + O->>CS: list_creative_features() + CS-->>O: Available features + O->>CS: check_creative(creative_asset) + CS-->>O: Feature results (passed/failed) +``` + +## Relationship to Other Protocols + +- **Content Standards**: Evaluates where ads run (content safety) +- **Creative Standards**: Evaluates how creatives look (brand compliance) +- **Property Governance**: Publisher-side inventory characteristics +- **Brand Manifest**: Discovery layer that can link to all governance agents diff --git a/docs/governance/creative-standards/tasks/check_creative.mdx b/docs/governance/creative-standards/tasks/check_creative.mdx new file mode 100644 index 000000000..9a415ab68 --- /dev/null +++ b/docs/governance/creative-standards/tasks/check_creative.mdx @@ -0,0 +1,174 @@ +--- +title: check_creative +sidebarTitle: check_creative +description: Evaluate a single creative asset against brand guidelines +--- + +# check_creative + +Evaluate a single creative asset against brand guidelines. Returns per-feature evaluation results indicating compliance status. + +## Request + +```json +{ + "standards_id": "acme_global_2024", + "creative": { + "creative_id": "creative_abc123", + "format_id": { + "agent_url": "https://creative.adcontextprotocol.org", + "id": "display_300x250" + }, + "assets": [ + { + "asset_id": "hero_image", + "url": "https://cdn.example.com/creative_abc123/hero.png", + "content_type": "image/png" + } + ], + "metadata": { + "headline": "Transform Your Business", + "tagline": "ACME - Innovation at Scale", + "cta_text": "Learn More" + } + }, + "feature_ids": ["logo_present", "color_palette", "typography_family"] +} +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `standards_id` | string | Yes | Standards configuration to evaluate against | +| `creative` | object | Yes | Creative asset to evaluate | +| `creative.creative_id` | string | No | Identifier for the creative | +| `creative.format_id` | object | No | Creative format specification | +| `creative.assets` | array | Yes | Asset files to evaluate | +| `creative.metadata` | object | No | Text content and metadata | +| `feature_ids` | array | No | Specific features to check (defaults to all) | + +## Response + +```json +{ + "summary": { + "total_features": 5, + "passed_features": 3, + "failed_features": 1, + "warning_features": 1 + }, + "results": [ + { + "feature_id": "logo_present", + "status": "passed", + "message": "Brand logo detected in creative" + }, + { + "feature_id": "logo_clear_space_px", + "status": "warning", + "value": 15, + "message": "Logo clear space is 15px, minimum recommended is 20px", + "suggestion": "Increase clear space around logo to at least 20px" + }, + { + "feature_id": "color_palette", + "status": "passed", + "value": "primary", + "message": "Creative uses primary brand color palette" + }, + { + "feature_id": "typography_family", + "status": "passed", + "value": "brand_sans", + "message": "Creative uses approved ACME Sans font family" + }, + { + "feature_id": "approved_tagline", + "status": "failed", + "message": "Tagline 'Innovation at Scale' is not in approved tagline list", + "suggestion": "Use an approved tagline such as 'Innovation Delivered' or 'Scale with Confidence'" + } + ] +} +``` + +### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `summary` | object | Aggregate counts | +| `summary.total_features` | integer | Total features evaluated | +| `summary.passed_features` | integer | Features that passed | +| `summary.failed_features` | integer | Features that failed | +| `summary.warning_features` | integer | Features with warnings | +| `results` | array | Per-feature results | +| `results[].feature_id` | string | Which feature was evaluated | +| `results[].status` | string | `passed`, `failed`, `warning`, or `unevaluated` | +| `results[].value` | any | The evaluated value (type depends on feature) | +| `results[].message` | string | Human-readable explanation | +| `results[].suggestion` | string | Recommended action if failed/warning | + +## Feature Status Values + +| Status | Meaning | +|--------|---------| +| `passed` | Creative meets the requirement | +| `failed` | Creative violates the requirement | +| `warning` | Creative is marginally compliant | +| `unevaluated` | Feature could not be evaluated | + +## Creative Asset Structure + +The `creative.assets` array should include all relevant files: + +```json +{ + "assets": [ + { + "asset_id": "main_image", + "url": "https://cdn.example.com/main.png", + "content_type": "image/png" + }, + { + "asset_id": "logo", + "url": "https://cdn.example.com/logo.svg", + "content_type": "image/svg+xml" + }, + { + "asset_id": "video", + "url": "https://cdn.example.com/spot.mp4", + "content_type": "video/mp4" + } + ] +} +``` + +## Metadata for Text Evaluation + +Include text content in `creative.metadata` for messaging checks: + +```json +{ + "metadata": { + "headline": "Transform Your Business", + "subheadline": "Enterprise solutions that scale", + "tagline": "Innovation Delivered", + "cta_text": "Get Started", + "legal_text": "Terms and conditions apply. See website for details." + } +} +``` + +## Error Response + +```json +{ + "errors": [ + { + "code": "ASSET_UNAVAILABLE", + "message": "Could not fetch asset at https://cdn.example.com/main.png" + } + ] +} +``` diff --git a/docs/governance/creative-standards/tasks/get_creative_standards.mdx b/docs/governance/creative-standards/tasks/get_creative_standards.mdx new file mode 100644 index 000000000..33b84d5c5 --- /dev/null +++ b/docs/governance/creative-standards/tasks/get_creative_standards.mdx @@ -0,0 +1,109 @@ +--- +title: get_creative_standards +sidebarTitle: get_creative_standards +description: Retrieve creative execution guidelines +--- + +# get_creative_standards + +Retrieve the creative execution guidelines for a specific standards configuration. Returns brand guidelines, asset requirements, and evaluation policies. + +## Request + +```json +{ + "standards_id": "acme_global_2024" +} +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `standards_id` | string | Yes | Identifier for the standards configuration to retrieve | + +## Response + +```json +{ + "standards_id": "acme_global_2024", + "version": "2.3.0", + "effective_date": "2024-01-15T00:00:00Z", + "scope": { + "brands": ["ACME Corp"], + "countries": ["US", "CA", "GB"], + "channels": ["display", "video", "native"], + "products": ["enterprise", "consumer"], + "description": "Global brand standards for ACME Corp enterprise and consumer products" + }, + "logo_policy": "The ACME logo must appear in all creatives at minimum 48px width with 20px clear space on all sides. Use the primary logo on light backgrounds, reversed logo on dark backgrounds.", + "color_policy": "Use primary brand colors (ACME Blue #0052CC, ACME Gray #42526E) for main elements. Secondary palette may be used for accents. Seasonal palettes require approval.", + "typography_policy": "Headlines use ACME Sans Bold. Body copy uses ACME Sans Regular at minimum 12px. Never use more than 2 font weights per creative.", + "imagery_policy": "Photography should feature real people in authentic situations. No stock photos with obvious staging. Product shots should show actual product in use context.", + "messaging_policy": "All creatives must include an approved tagline or value proposition. Claims must be substantiated. Competitive comparisons require legal review.", + "required_elements": [ + "Brand logo", + "Approved tagline or value proposition", + "Clear call-to-action" + ], + "prohibited_elements": [ + "Competitor logos or mentions", + "Unsubstantiated claims", + "Non-brand colors as primary elements", + "Stock photography with watermarks" + ] +} +``` + +### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `standards_id` | string | Identifier for this configuration | +| `version` | string | Version of this standards configuration | +| `effective_date` | string | When this version became effective | +| `scope` | object | What this configuration applies to | +| `scope.brands` | array | Brand names covered | +| `scope.countries` | array | ISO 3166-1 alpha-2 country codes | +| `scope.channels` | array | Advertising channels | +| `scope.products` | array | Product lines or categories | +| `logo_policy` | string | Natural language logo usage guidelines | +| `color_policy` | string | Natural language color guidelines | +| `typography_policy` | string | Natural language typography guidelines | +| `imagery_policy` | string | Natural language imagery guidelines | +| `messaging_policy` | string | Natural language messaging guidelines | +| `required_elements` | array | Elements that must be present | +| `prohibited_elements` | array | Elements that must not appear | + +## Scope-Based Selection + +Creative standards can vary by: + +- **Country**: Regional variations in brand presentation +- **Channel**: Display vs. video vs. native requirements +- **Product**: Different product lines may have distinct brand expressions +- **Campaign**: Special campaigns may have temporary variations + +Request the appropriate `standards_id` based on the creative's intended use. + +## Policy Prompts + +The policy fields (`logo_policy`, `color_policy`, etc.) use natural language descriptions rather than keyword lists. This enables: + +- **AI evaluation**: Language models can interpret guidelines contextually +- **Nuanced judgments**: Handle edge cases that rule-based systems miss +- **Human readability**: Same policies work for human reviewers +- **Easy updates**: Marketing teams can update policies without technical changes + +## Error Response + +```json +{ + "errors": [ + { + "code": "STANDARDS_NOT_FOUND", + "message": "Standards configuration 'unknown_id' not found" + } + ] +} +``` diff --git a/docs/governance/creative-standards/tasks/list_creative_features.mdx b/docs/governance/creative-standards/tasks/list_creative_features.mdx new file mode 100644 index 000000000..6055875dc --- /dev/null +++ b/docs/governance/creative-standards/tasks/list_creative_features.mdx @@ -0,0 +1,120 @@ +--- +title: list_creative_features +sidebarTitle: list_creative_features +description: Discover available creative compliance features +--- + +# list_creative_features + +Discover what creative compliance features this agent can evaluate. Features represent specific aspects of brand guideline compliance that can be checked. + +## Request + +```json +{ + "standards_id": "acme_global_2024" // Optional: filter to specific standards +} +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `standards_id` | string | No | Filter features available for a specific standards configuration | + +## Response + +```json +{ + "features": [ + { + "feature_id": "logo_present", + "name": "Logo Present", + "description": "Verifies the brand logo is included in the creative", + "type": "binary", + "severity": "block" + }, + { + "feature_id": "logo_clear_space_px", + "name": "Logo Clear Space", + "description": "Minimum clear space around the logo in pixels", + "type": "quantitative", + "range": { "min": 20 }, + "severity": "warn" + }, + { + "feature_id": "color_palette", + "name": "Color Palette", + "description": "Which approved brand color palette is used", + "type": "categorical", + "allowed_values": ["primary", "secondary", "seasonal_q4"], + "severity": "warn" + }, + { + "feature_id": "typography_family", + "name": "Typography", + "description": "Font family used in the creative", + "type": "categorical", + "allowed_values": ["brand_sans", "brand_serif", "brand_display"], + "severity": "warn" + }, + { + "feature_id": "text_contrast_ratio", + "name": "Text Contrast Ratio", + "description": "WCAG contrast ratio for text legibility", + "type": "quantitative", + "range": { "min": 4.5 }, + "severity": "warn" + } + ] +} +``` + +### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `features` | array | List of available features | +| `features[].feature_id` | string | Unique identifier for the feature | +| `features[].name` | string | Human-readable name | +| `features[].description` | string | What this feature evaluates | +| `features[].type` | string | One of: `binary`, `quantitative`, `categorical` | +| `features[].range` | object | For quantitative features: min/max values | +| `features[].allowed_values` | array | For categorical features: valid values | +| `features[].severity` | string | Default severity when feature fails: `block`, `warn`, `info` | + +## Feature Types + +### Binary Features +Pass/fail checks: +- `logo_present`: Brand logo is included +- `approved_tagline`: Uses an approved brand tagline +- `legal_disclaimer`: Required legal text is present +- `click_url_valid`: Clickthrough URL is accessible + +### Quantitative Features +Numeric thresholds: +- `logo_clear_space_px`: Minimum pixels around logo +- `logo_min_width_px`: Minimum logo width +- `text_contrast_ratio`: WCAG contrast ratio +- `animation_duration_sec`: Max animation length + +### Categorical Features +Values from defined sets: +- `color_palette`: primary, secondary, seasonal variants +- `typography_family`: approved font families +- `imagery_style`: lifestyle, product, abstract, etc. +- `cta_style`: primary, secondary, text-only + +## Error Response + +```json +{ + "errors": [ + { + "code": "INVALID_STANDARDS_ID", + "message": "Standards configuration 'unknown_id' not found" + } + ] +} +``` diff --git a/docs/governance/creative-standards/tasks/validate_creative_delivery.mdx b/docs/governance/creative-standards/tasks/validate_creative_delivery.mdx new file mode 100644 index 000000000..22987265a --- /dev/null +++ b/docs/governance/creative-standards/tasks/validate_creative_delivery.mdx @@ -0,0 +1,193 @@ +--- +title: validate_creative_delivery +sidebarTitle: validate_creative_delivery +description: Batch validate delivered creatives against brand guidelines +--- + +# validate_creative_delivery + +Batch validate delivered creatives against brand guidelines. Use this for post-campaign compliance auditing or to validate a library of creatives. + +## Request + +```json +{ + "standards_id": "acme_global_2024", + "creatives": [ + { + "creative_id": "creative_001", + "assets": [ + { + "asset_id": "main", + "url": "https://cdn.example.com/creative_001/main.png", + "content_type": "image/png" + } + ], + "metadata": { + "headline": "Transform Your Business", + "tagline": "Innovation Delivered" + } + }, + { + "creative_id": "creative_002", + "assets": [ + { + "asset_id": "main", + "url": "https://cdn.example.com/creative_002/main.png", + "content_type": "image/png" + } + ], + "metadata": { + "headline": "Scale with Confidence", + "tagline": "ACME Enterprise" + } + } + ], + "feature_ids": ["logo_present", "color_palette", "approved_tagline"], + "include_passed": false +} +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `standards_id` | string | Yes | Standards configuration to validate against | +| `creatives` | array | Yes | Creative assets to validate (max 1,000) | +| `creatives[].creative_id` | string | Yes | Unique identifier for each creative | +| `creatives[].assets` | array | Yes | Asset files for the creative | +| `creatives[].metadata` | object | No | Text content and metadata | +| `feature_ids` | array | No | Specific features to evaluate (defaults to all) | +| `include_passed` | boolean | No | Include passed creatives in results (default: true) | + +## Response + +```json +{ + "summary": { + "total_creatives": 2, + "passed_creatives": 1, + "failed_creatives": 1, + "total_features": 6, + "passed_features": 5, + "failed_features": 1 + }, + "results": [ + { + "creative_id": "creative_002", + "features": [ + { + "feature_id": "logo_present", + "status": "passed" + }, + { + "feature_id": "color_palette", + "status": "passed", + "value": "primary" + }, + { + "feature_id": "approved_tagline", + "status": "failed", + "message": "Tagline 'ACME Enterprise' is not in approved list", + "suggestion": "Use 'ACME - Enterprise Solutions' instead" + } + ] + } + ] +} +``` + +### Response Fields + +| Field | Type | Description | +|-------|------|-------------| +| `summary` | object | Aggregate counts across all creatives | +| `summary.total_creatives` | integer | Total creatives evaluated | +| `summary.passed_creatives` | integer | Creatives passing all features | +| `summary.failed_creatives` | integer | Creatives with at least one failure | +| `summary.total_features` | integer | Total feature evaluations | +| `summary.passed_features` | integer | Feature evaluations that passed | +| `summary.failed_features` | integer | Feature evaluations that failed | +| `results` | array | Per-creative evaluation results | +| `results[].creative_id` | string | Which creative was evaluated | +| `results[].features` | array | Feature results for this creative | + +## Batch Processing + +For large creative libraries: + +- Maximum 1,000 creatives per request +- Process in batches for larger sets +- Use `include_passed: false` to reduce response size when only failures matter +- Use `feature_ids` to focus on specific compliance aspects + +## Use Cases + +### Post-Campaign Audit +Validate all creatives that ran during a campaign: + +```json +{ + "standards_id": "acme_global_2024", + "creatives": [...], // All creatives from campaign + "include_passed": true // Full audit report +} +``` + +### Pre-Flight Check +Validate creatives before launch: + +```json +{ + "standards_id": "acme_global_2024", + "creatives": [...], // Creatives pending approval + "include_passed": false // Only show problems +} +``` + +### Compliance Monitoring +Regular checks of active creative library: + +```json +{ + "standards_id": "acme_global_2024", + "creatives": [...], // Random sample or full library + "feature_ids": ["logo_present", "approved_tagline"] // Focus areas +} +``` + +## Error Response + +```json +{ + "errors": [ + { + "code": "BATCH_TOO_LARGE", + "message": "Request contains 1500 creatives, maximum is 1000" + } + ] +} +``` + +## Partial Failures + +If some creatives fail to evaluate, results include both successful evaluations and errors: + +```json +{ + "summary": { + "total_creatives": 100, + "passed_creatives": 95, + "failed_creatives": 3, + "error_creatives": 2 + }, + "results": [...], + "errors": [ + { + "creative_id": "creative_099", + "code": "ASSET_UNAVAILABLE", + "message": "Could not fetch main asset" + } + ] +} +``` diff --git a/static/schemas/source/creative-standards/check-creative-request.json b/static/schemas/source/creative-standards/check-creative-request.json new file mode 100644 index 000000000..01e5bd4b7 --- /dev/null +++ b/static/schemas/source/creative-standards/check-creative-request.json @@ -0,0 +1,75 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/creative-standards/check-creative-request.json", + "title": "Check Creative Request", + "description": "Request parameters for evaluating a creative asset against brand guidelines", + "type": "object", + "properties": { + "standards_id": { + "type": "string", + "description": "Standards configuration to evaluate against" + }, + "creative": { + "type": "object", + "description": "Creative asset to evaluate", + "properties": { + "creative_id": { + "type": "string", + "description": "Identifier for the creative" + }, + "format_id": { + "$ref": "/schemas/core/format-id.json", + "description": "Creative format specification" + }, + "assets": { + "type": "array", + "description": "Asset files to evaluate", + "items": { + "type": "object", + "properties": { + "asset_id": { + "type": "string", + "description": "Identifier for this asset" + }, + "url": { + "type": "string", + "format": "uri", + "description": "URL to fetch the asset" + }, + "content_type": { + "type": "string", + "description": "MIME type of the asset" + } + }, + "required": ["url"] + } + }, + "metadata": { + "type": "object", + "description": "Text content and metadata for evaluation", + "properties": { + "headline": { "type": "string" }, + "subheadline": { "type": "string" }, + "tagline": { "type": "string" }, + "cta_text": { "type": "string" }, + "legal_text": { "type": "string" } + }, + "additionalProperties": { "type": "string" } + } + }, + "required": ["assets"] + }, + "feature_ids": { + "type": "array", + "items": { "type": "string" }, + "description": "Specific features to check (defaults to all)" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["standards_id", "creative"] +} diff --git a/static/schemas/source/creative-standards/check-creative-response.json b/static/schemas/source/creative-standards/check-creative-response.json new file mode 100644 index 000000000..21d12c0b3 --- /dev/null +++ b/static/schemas/source/creative-standards/check-creative-response.json @@ -0,0 +1,93 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/creative-standards/check-creative-response.json", + "title": "Check Creative Response", + "description": "Response payload with per-feature evaluation results", + "type": "object", + "oneOf": [ + { + "type": "object", + "description": "Success response", + "properties": { + "summary": { + "type": "object", + "description": "Summary counts of feature evaluations", + "properties": { + "total_features": { "type": "integer" }, + "passed_features": { "type": "integer" }, + "failed_features": { "type": "integer" }, + "warning_features": { "type": "integer" }, + "unevaluated_features": { "type": "integer" } + }, + "required": ["total_features", "passed_features", "failed_features"] + }, + "results": { + "type": "array", + "description": "Per-feature evaluation results", + "items": { + "type": "object", + "properties": { + "feature_id": { + "type": "string", + "description": "Which feature was evaluated" + }, + "status": { + "type": "string", + "enum": ["passed", "failed", "warning", "unevaluated"], + "description": "Evaluation status" + }, + "value": { + "description": "The evaluated value (type depends on feature)" + }, + "message": { + "type": "string", + "description": "Human-readable explanation" + }, + "rule_id": { + "type": "string", + "description": "Which rule triggered this result" + }, + "suggestion": { + "type": "string", + "description": "Recommended action if failed" + } + }, + "required": ["feature_id", "status"] + } + }, + "errors": { + "not": {}, + "description": "Field must not be present in success response" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["summary", "results"] + }, + { + "type": "object", + "description": "Error response", + "properties": { + "errors": { + "type": "array", + "items": { "$ref": "/schemas/core/error.json" } + }, + "summary": { + "not": {}, + "description": "Field must not be present in error response" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["errors"] + } + ] +} diff --git a/static/schemas/source/creative-standards/get-creative-standards-request.json b/static/schemas/source/creative-standards/get-creative-standards-request.json new file mode 100644 index 000000000..aee7614a8 --- /dev/null +++ b/static/schemas/source/creative-standards/get-creative-standards-request.json @@ -0,0 +1,20 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/creative-standards/get-creative-standards-request.json", + "title": "Get Creative Standards Request", + "description": "Request parameters for retrieving creative execution guidelines", + "type": "object", + "properties": { + "standards_id": { + "type": "string", + "description": "Identifier for the standards configuration to retrieve" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["standards_id"] +} diff --git a/static/schemas/source/creative-standards/get-creative-standards-response.json b/static/schemas/source/creative-standards/get-creative-standards-response.json new file mode 100644 index 000000000..2a231912d --- /dev/null +++ b/static/schemas/source/creative-standards/get-creative-standards-response.json @@ -0,0 +1,120 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/creative-standards/get-creative-standards-response.json", + "title": "Get Creative Standards Response", + "description": "Response payload with creative execution guidelines", + "type": "object", + "oneOf": [ + { + "type": "object", + "description": "Success response", + "properties": { + "standards_id": { + "type": "string", + "description": "Identifier for this standards configuration" + }, + "version": { + "type": "string", + "description": "Version of this standards configuration" + }, + "effective_date": { + "type": "string", + "format": "date-time", + "description": "When this version became effective" + }, + "scope": { + "type": "object", + "description": "What this standards configuration applies to", + "properties": { + "brands": { + "type": "array", + "items": { "type": "string" }, + "description": "Brand names covered" + }, + "countries": { + "type": "array", + "items": { "type": "string" }, + "description": "ISO 3166-1 alpha-2 country codes" + }, + "channels": { + "type": "array", + "items": { "type": "string" }, + "description": "Advertising channels" + }, + "products": { + "type": "array", + "items": { "type": "string" }, + "description": "Product lines or categories" + }, + "description": { + "type": "string", + "description": "Human-readable scope description" + } + } + }, + "logo_policy": { + "type": "string", + "description": "Natural language logo usage guidelines" + }, + "color_policy": { + "type": "string", + "description": "Natural language color palette guidelines" + }, + "typography_policy": { + "type": "string", + "description": "Natural language typography guidelines" + }, + "imagery_policy": { + "type": "string", + "description": "Natural language imagery and photography guidelines" + }, + "messaging_policy": { + "type": "string", + "description": "Natural language messaging and copy guidelines" + }, + "required_elements": { + "type": "array", + "items": { "type": "string" }, + "description": "Elements that must be present in creatives" + }, + "prohibited_elements": { + "type": "array", + "items": { "type": "string" }, + "description": "Elements that must not appear in creatives" + }, + "errors": { + "not": {}, + "description": "Field must not be present in success response" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["standards_id", "version"] + }, + { + "type": "object", + "description": "Error response", + "properties": { + "errors": { + "type": "array", + "items": { "$ref": "/schemas/core/error.json" } + }, + "standards_id": { + "not": {}, + "description": "Field must not be present in error response" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["errors"] + } + ] +} diff --git a/static/schemas/source/creative-standards/list-creative-features-request.json b/static/schemas/source/creative-standards/list-creative-features-request.json new file mode 100644 index 000000000..b7827914b --- /dev/null +++ b/static/schemas/source/creative-standards/list-creative-features-request.json @@ -0,0 +1,19 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/creative-standards/list-creative-features-request.json", + "title": "List Creative Features Request", + "description": "Request parameters for discovering creative compliance features", + "type": "object", + "properties": { + "standards_id": { + "type": "string", + "description": "Filter features available for a specific standards configuration" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + } +} diff --git a/static/schemas/source/creative-standards/list-creative-features-response.json b/static/schemas/source/creative-standards/list-creative-features-response.json new file mode 100644 index 000000000..f0d2a1c94 --- /dev/null +++ b/static/schemas/source/creative-standards/list-creative-features-response.json @@ -0,0 +1,92 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/creative-standards/list-creative-features-response.json", + "title": "List Creative Features Response", + "description": "Response payload with available creative compliance features", + "type": "object", + "oneOf": [ + { + "type": "object", + "description": "Success response", + "properties": { + "features": { + "type": "array", + "description": "Available features for creative compliance evaluation", + "items": { + "type": "object", + "properties": { + "feature_id": { + "type": "string", + "description": "Unique identifier for this feature" + }, + "name": { + "type": "string", + "description": "Human-readable feature name" + }, + "description": { + "type": "string", + "description": "What this feature evaluates" + }, + "type": { + "type": "string", + "enum": ["binary", "quantitative", "categorical"], + "description": "Feature type" + }, + "range": { + "type": "object", + "description": "For quantitative features, the valid range", + "properties": { + "min": { "type": "number" }, + "max": { "type": "number" } + } + }, + "allowed_values": { + "type": "array", + "description": "For categorical features, the allowed values", + "items": { "type": "string" } + }, + "severity": { + "type": "string", + "enum": ["block", "warn", "info"], + "description": "Default severity when this feature fails" + } + }, + "required": ["feature_id", "name", "type"] + } + }, + "errors": { + "not": {}, + "description": "Field must not be present in success response" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["features"] + }, + { + "type": "object", + "description": "Error response", + "properties": { + "errors": { + "type": "array", + "items": { "$ref": "/schemas/core/error.json" } + }, + "features": { + "not": {}, + "description": "Field must not be present in error response" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["errors"] + } + ] +} diff --git a/static/schemas/source/creative-standards/validate-creative-delivery-request.json b/static/schemas/source/creative-standards/validate-creative-delivery-request.json new file mode 100644 index 000000000..ef7a8ce0d --- /dev/null +++ b/static/schemas/source/creative-standards/validate-creative-delivery-request.json @@ -0,0 +1,63 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/creative-standards/validate-creative-delivery-request.json", + "title": "Validate Creative Delivery Request", + "description": "Request parameters for batch validating creatives against brand guidelines", + "type": "object", + "properties": { + "standards_id": { + "type": "string", + "description": "Standards configuration to validate against" + }, + "creatives": { + "type": "array", + "description": "Creative assets to validate (max 1,000)", + "maxItems": 1000, + "items": { + "type": "object", + "properties": { + "creative_id": { + "type": "string", + "description": "Unique identifier for this creative" + }, + "assets": { + "type": "array", + "description": "Asset files for this creative", + "items": { + "type": "object", + "properties": { + "asset_id": { "type": "string" }, + "url": { "type": "string", "format": "uri" }, + "content_type": { "type": "string" } + }, + "required": ["url"] + } + }, + "metadata": { + "type": "object", + "description": "Text content and metadata", + "additionalProperties": { "type": "string" } + } + }, + "required": ["creative_id", "assets"] + } + }, + "feature_ids": { + "type": "array", + "items": { "type": "string" }, + "description": "Specific features to evaluate (defaults to all)" + }, + "include_passed": { + "type": "boolean", + "default": true, + "description": "Include passed creatives in results" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["standards_id", "creatives"] +} diff --git a/static/schemas/source/creative-standards/validate-creative-delivery-response.json b/static/schemas/source/creative-standards/validate-creative-delivery-response.json new file mode 100644 index 000000000..15f08d7b2 --- /dev/null +++ b/static/schemas/source/creative-standards/validate-creative-delivery-response.json @@ -0,0 +1,93 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/creative-standards/validate-creative-delivery-response.json", + "title": "Validate Creative Delivery Response", + "description": "Response payload with per-creative feature results and summary statistics", + "type": "object", + "oneOf": [ + { + "type": "object", + "description": "Success response", + "properties": { + "summary": { + "type": "object", + "description": "Summary counts across all creatives", + "properties": { + "total_creatives": { "type": "integer" }, + "passed_creatives": { "type": "integer" }, + "failed_creatives": { "type": "integer" }, + "error_creatives": { "type": "integer" }, + "total_features": { "type": "integer" }, + "passed_features": { "type": "integer" }, + "failed_features": { "type": "integer" } + }, + "required": ["total_creatives", "passed_creatives", "failed_creatives"] + }, + "results": { + "type": "array", + "description": "Per-creative evaluation results", + "items": { + "type": "object", + "properties": { + "creative_id": { + "type": "string", + "description": "Which creative was evaluated" + }, + "features": { + "type": "array", + "description": "Feature results for this creative", + "items": { + "type": "object", + "properties": { + "feature_id": { "type": "string" }, + "status": { + "type": "string", + "enum": ["passed", "failed", "warning", "unevaluated"] + }, + "value": {}, + "message": { "type": "string" }, + "suggestion": { "type": "string" } + }, + "required": ["feature_id", "status"] + } + } + }, + "required": ["creative_id", "features"] + } + }, + "errors": { + "not": {}, + "description": "Field must not be present in success response" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["summary", "results"] + }, + { + "type": "object", + "description": "Error response", + "properties": { + "errors": { + "type": "array", + "items": { "$ref": "/schemas/core/error.json" } + }, + "summary": { + "not": {}, + "description": "Field must not be present in error response" + }, + "context": { + "$ref": "/schemas/core/context.json" + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": ["errors"] + } + ] +} diff --git a/static/schemas/source/index.json b/static/schemas/source/index.json index 2056c90ce..aa7251b75 100644 --- a/static/schemas/source/index.json +++ b/static/schemas/source/index.json @@ -562,6 +562,51 @@ } } }, + "creative-standards": { + "description": "Creative Standards protocol task request/response schemas for brand guideline compliance", + "tasks": { + "list-creative-features": { + "request": { + "$ref": "/schemas/creative-standards/list-creative-features-request.json", + "description": "Request parameters for discovering creative compliance features" + }, + "response": { + "$ref": "/schemas/creative-standards/list-creative-features-response.json", + "description": "Response payload with available creative features" + } + }, + "get-creative-standards": { + "request": { + "$ref": "/schemas/creative-standards/get-creative-standards-request.json", + "description": "Request parameters for retrieving creative execution guidelines" + }, + "response": { + "$ref": "/schemas/creative-standards/get-creative-standards-response.json", + "description": "Response payload with creative execution guidelines" + } + }, + "check-creative": { + "request": { + "$ref": "/schemas/creative-standards/check-creative-request.json", + "description": "Request parameters for evaluating a creative asset against brand guidelines" + }, + "response": { + "$ref": "/schemas/creative-standards/check-creative-response.json", + "description": "Response payload with per-feature evaluation results" + } + }, + "validate-creative-delivery": { + "request": { + "$ref": "/schemas/creative-standards/validate-creative-delivery-request.json", + "description": "Request parameters for batch validating creatives" + }, + "response": { + "$ref": "/schemas/creative-standards/validate-creative-delivery-response.json", + "description": "Response payload with batch validation results" + } + } + } + }, "adagents": { "description": "Authorized sales agents file format specification", "$ref": "/schemas/adagents.json",