{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "@context": [
    "https://schemas.meta-aiml.org/v3.0.0/context.jsonld"
  ],
  "@id": "https://schemas.meta-aiml.org/v3.0.0/components/rating_review_format.json",
  "@type": [
    "Thing",
    "ComponentSchema"
  ],
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "Rating and Review Format Component",
  "description": "Ratings, reviews, and feedback structures",
  "type": "object",
  "$defs": {
    "AggregateRating": {
      "type": "object",
      "title": "Aggregate Rating",
      "description": "Aggregated rating from multiple reviews",
      "properties": {
        "ratingValue": {
          "type": "number",
          "minimum": 0,
          "maximum": 5
        },
        "reviewCount": {
          "type": "integer",
          "minimum": 0
        },
        "ratingCount": {
          "type": "integer",
          "minimum": 0
        },
        "bestRating": {
          "type": "number",
          "default": 5
        },
        "worstRating": {
          "type": "number",
          "default": 1
        },
        "ratingDistribution": {
          "type": "object",
          "properties": {
            "fiveStars": {
              "type": "integer"
            },
            "fourStars": {
              "type": "integer"
            },
            "threeStars": {
              "type": "integer"
            },
            "twoStars": {
              "type": "integer"
            },
            "oneStar": {
              "type": "integer"
            }
          }
        }
      },
      "required": [
        "ratingValue",
        "reviewCount"
      ]
    },
    "Review": {
      "type": "object",
      "title": "Review",
      "description": "Individual review",
      "properties": {
        "reviewRating": {
          "type": "number",
          "minimum": 1,
          "maximum": 5
        },
        "reviewHeadline": {
          "type": "string"
        },
        "reviewBody": {
          "type": "string"
        },
        "author": {
          "type": "string"
        },
        "datePublished": {
          "type": "string",
          "format": "date-time"
        },
        "reviewPlatform": {
          "type": "string",
          "enum": [
            "airbnb",
            "amazon",
            "booking_com",
            "capterra",
            "facebook",
            "g2",
            "glassdoor",
            "google",
            "internal",
            "tripadvisor",
            "trustpilot",
            "yelp"
          ]
        },
        "isVerified": {
          "type": "boolean"
        },
        "helpfulCount": {
          "type": "integer"
        }
      },
      "required": [
        "reviewRating",
        "reviewBody"
      ]
    },
    "ReviewCollection": {
      "type": "object",
      "title": "Review Collection",
      "description": "Collection of reviews with metadata",
      "properties": {
        "aggregateRating": {
          "$ref": "#/$defs/AggregateRating"
        },
        "reviews": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Review"
          }
        },
        "reviewPlatforms": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "validationMetadata": {
    "schemaVersion": "3.0.0",
    "phase": "phase_1",
    "status": "draft",
    "lastValidated": "2026-02-19",
    "validator": "META-AIML QA"
  },
  "semanticAnnotations": {
    "type": "object",
    "description": "Semantic guidance on rating and review data in META-AIML v3.",
    "properties": {
      "aggregationPolicy": {
        "type": "string",
        "const": "aggregateRating should reflect cross-platform averages when possible. Single-platform ratings should note source."
      },
      "trustSignals": {
        "type": "string",
        "const": "reviewCount is a primary trust signal for AI parsers. Higher counts with balanced scores indicate authentic data."
      },
      "schemaOrgAlignment": {
        "type": "string",
        "const": "AggregateRating maps to schema.org/AggregateRating. ReviewItem maps to schema.org/Review. Use schema.org fields for maximum interoperability."
      }
    }
  },
  "governanceMetadata": {
    "type": "object",
    "properties": {
      "componentVersion": {
        "type": "string",
        "const": "3.0.0"
      },
      "stabilityLevel": {
        "type": "string",
        "const": "stable"
      },
      "usageGuidelines": {
        "type": "array",
        "const": [
          "ratingValue must be between worstRating and bestRating (SDK validates).",
          "reviewCount should be the total number of reviews, not displayed count.",
          "reviewPlatforms should list all sources included in aggregateRating.",
          "Do not include personally identifiable information in review schemas."
        ]
      }
    }
  },
  "examples": {
    "type": "array",
    "examples": [
      {
        "scenario": "Restaurant aggregate rating",
        "modules": {
          "reviews": {
            "aggregateRating": {
              "ratingValue": 4.5,
              "reviewCount": 342,
              "bestRating": 5,
              "worstRating": 1
            },
            "reviewPlatforms": [
              "google",
              "yelp",
              "tripadvisor"
            ]
          }
        }
      },
      {
        "scenario": "SaaS platform with user satisfaction score",
        "modules": {
          "reviews": {
            "aggregateRating": {
              "ratingValue": 4.2,
              "reviewCount": 1250,
              "bestRating": 5,
              "worstRating": 1
            },
            "reviewPlatforms": [
              "g2",
              "capterra",
              "trustpilot"
            ]
          }
        }
      }
    ]
  },
  "$id": "https://schemas.meta-aiml.org/v3.0.0/components/rating_review_format.json"
}