JSON Schema

The AIPC JSON Schema defines the structure of every contract-wrapped API response. It is the machine-readable source of truth for the protocol.

Top-level structure

Every AIPC response must conform to this root schema:

{
  "$schema": "https://aipc.dev/schema/v0.1.0/response.json",
  "type": "object",
  "required": ["aipc_version", "provider", "contract", "payload"],
  "properties": {
    "aipc_version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$"
    },
    "provider": { "$ref": "#/$defs/Provider" },
    "contract": { "$ref": "#/$defs/Contract" },
    "payload": {
      "type": "object",
      "additionalProperties": true
    }
  }
}

Provider

The provider object identifies the data source:

{
  "type": "object",
  "required": ["id", "name", "contract_version"],
  "properties": {
    "id":               { "type": "string" },
    "name":             { "type": "string" },
    "authority":        { "type": "string" },
    "contract_version": { "type": "string" },
    "contact":          { "type": "string", "format": "email" },
    "terms_url":        { "type": "string", "format": "uri" },
    "logo": {
      "type": "object",
      "properties": {
        "url":            { "type": "string", "format": "uri" },
        "display":        { "enum": ["required", "optional"] },
        "min_height_px":  { "type": "integer", "minimum": 1 }
      }
    }
  }
}

Contract

The contract object contains all presentation rules. Required fields are disclosures, display_rules, attribution, freshness, and fail_behavior:

{
  "type": "object",
  "required": ["disclosures", "display_rules", "attribution", "freshness", "fail_behavior"],
  "properties": {
    "disclosures":             { "type": "array", "items": { "$ref": "#/$defs/Disclosure" } },
    "display_rules":           { "type": "array", "items": { "$ref": "#/$defs/DisplayRule" } },
    "attribution":             { "$ref": "#/$defs/Attribution" },
    "freshness":               { "$ref": "#/$defs/Freshness" },
    "tone":                    { "$ref": "#/$defs/ToneDirective" },
    "conditional_rules":       { "type": "array", "items": { "$ref": "#/$defs/ConditionalRule" } },
    "fail_behavior":           { "enum": ["suppress", "warn", "partial", "log"] },
    "minimum_compliance_level": { "enum": ["L1", "L2", "L3"] },
    "minimum_consumer_enforcement": { "enum": ["L1", "L2", "L3"] }
  }
}

Key sub-schemas

Each contract section has its own schema definition. See the individual concept pages for detailed documentation:

• Disclosure — id, text, verbatim, scope, placement, priority
• DisplayRule — scope, label, format, context_required, suppress_if
• Attribution — required, text, verbatim, placement, link
• Freshness — generated_at, valid_until, stale_behavior, expired_behavior
• ToneDirective — framing, prohibited_framings, prohibited_phrases, editorial_restrictions
• ConditionalRule — id, condition, then

Validation

You can validate any AIPC response against the schema using standard JSON Schema validators:

import Ajv from 'ajv';
import aipcSchema from '@aipc/schema/v0.1.0/response.json';

const ajv = new Ajv();
const validate = ajv.compile(aipcSchema);

const valid = validate(response);
if (!valid) {
  console.error(validate.errors);
}