Review schema

Pull-based review schema

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
     "metaData": {
        "type": "object",
        "properties": {
           "feedCategory": {
              "type": "string",
              "enum": [
                "SNAPSHOT",
                "UPDATE"
              ],
              "description": "Category for the current feed"
           },
           "feedTimestampMicros": {
             "type": "integer",
             "description": "Timestamp in microseconds, representing age of current feed"
           },
           "apiVersion": {
             "type": "string",
             "description": "Represents the desired version of the service API in a feed."
           },
           "pagination": {
             "type": "object",
             "description": "Pagination info used to retrieve the subsequent page of current feeds, will be used to fill nextToken param in url, see above pagination section for explanation",
             "properties": {
                "nextTokenParam": {
                    "type": "string"
                }
             }
           },
           "totalCount": {
             "type": "number",
             "description": "Total number of reviewItems should be included in the full feed (across all pages), used to cross check feed completeness."
           },
           "partnerFeedId": {
             "type": "string",
             "description": "Partner specific identifier for this feed, if any. This field will be logged in reports exported (eg. feed validation/status reports). Partners may use this field for easier lookup of processing result/errors given a specific feed. This field optional"
           }
      },
      "required": [
         "feedCategory",
         "feedTimestampMicros",
         "apiVersion",
         "pagination",
         "totalCount"
       ]
    },
    "reviewItems": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "serviceProviderId",
          "ratingCount",
          "reviews"
        ],
        "properties": {
          "serviceProviderId": {
            "type": "number",
            "description": "Unique identifier of a listing (a service provider)"
          },
          "ratingCount": {
            "type": "integer",
            "description": "number of verified consumer ratings"
          },
          "reviews": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "reviewId": {
                  "type": "string",
                  "description": "The unique id of the review"
                },
                "author": {
                  "type": "string",
                  "description": "Author of the review"
                },
                "reviewText": {
                  "type": "string",
                  "description": "Review text written by the author"
                },
                "rating": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 5,
                  "description": "Rating with the review text, should be an integer, minimum is 1, maximum is 5"
                },
                "serviceLocationCity": {
                  "type": "string",
                  "description": "Service location city for the review"
                },
                "serviceTimestampMicros": {
                  "type": "integer",
                  "description": "Timestamp in microseconds when the service is finished"
                },
                "reviewTimestampMicros": {
                  "type": "integer",
                  "description": "Timestamp in microseconds when the review was written"
                },
                “language”: {
                  "type": "string",
                  "description": "Language of the review text in ISO 639-1 language code. (lowercase, 2-letter)"
                },
                "category": {
                    "type": "object",
                    "description": "Service vertical and Task info of the review",
                    "properties": {
                       "categoryId": {
                          "type": "string",
                          "description": "Category Id of the review in LSA taxonomy"
                       },
                       "task": {
                           "type": "string",
                           "description": "Task Id of the review in LSA taxonomy"
                       }
                    }
                },
                "confirmedCustomer": {
                  "type": "boolean",
                  "description": "If the review comes from a confirmed customer (with a lead)"
                }
              },
              "required": [
                "reviewId",
                "rating"
              ]
            }
          }
        }
      }
    }
  },
  "required": [
    "metaData",
    "reviewItems"
  ]
}

Push-based review feed schema

The push-based version is a combined page. It is delivered in one file, with an outer wrapper responses array. Elements in the responses array use the same schema as the pull based review schema (paginated/single page).

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "responses" : {
      "type": "array",
      "description": "An array of paginated responses from a given partner",
      "items": {
          … // Element in array shares the same schema as above pull feed schema
      }
    }
  },
  "required": [
    "responses"
  ]
}