{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://www.monocrawl.com/schemas/tiktok/user-audience.json","title":"tiktok/user-audience data fields","description":"Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee.","type":"object","properties":{"platform":{"type":["string","null"],"description":"tiktok"},"locations":{"type":"array","items":{"type":"object","properties":{"country":{"type":["string","null"],"description":"Country name."},"country_code":{"type":["string","null"],"description":"Source country code."},"count":{"type":["number","null"],"description":"Source-reported country count; unknown sampling method."},"percentage":{"type":["number","null"],"description":"Source percentage only, 0–100; null when absent. Its denominator is not independently verified."},"returned_count_share_percentage":{"type":["number","null"],"description":"Calculated percentage of returned_count_total only; not a whole-audience percentage."}},"additionalProperties":true,"allOf":[{"anyOf":[{"required":["country"],"properties":{"country":{"type":["string"],"description":"Country name.","minLength":1}}},{"required":["country_code"],"properties":{"country_code":{"type":["string"],"description":"Source country code.","minLength":1}}},{"required":["percentage"],"properties":{"percentage":{"type":["number"],"description":"Source percentage only, 0–100; null when absent. Its denominator is not independently verified."}}},{"required":["returned_count_share_percentage"],"properties":{"returned_count_share_percentage":{"type":["number"],"description":"Calculated percentage of returned_count_total only; not a whole-audience percentage."}}}]}]}},"returned_count_total":{"type":["number","null"],"description":"Sum of returned country counts, or null if any count is missing or invalid."},"sampling":{"type":"object","properties":{"share_basis":{"type":["string","null"],"description":"returned_country_counts"},"methodology":{"type":["string","null"],"description":"Unknown when null."},"sampled_at":{"type":["string","null"],"description":"Unknown when null."},"note":{"type":["string","null"],"description":"Sampling limitations."}},"additionalProperties":true},"_warnings":{"type":"array","items":{"type":"string"},"description":"Collection limitations or component warnings. Read before interpreting coverage."}},"additionalProperties":true,"required":["locations"],"x-contract-version":"2026-09-22","x-validation-scope":"Required success payload structure; optional fields and source completeness remain separate.","examples":[{"platform":"tiktok","locations":[{"country":"United Kingdom","country_code":"GB","count":30,"percentage":null,"returned_count_share_percentage":100}],"returned_count_total":30,"sampling":{"share_basis":"returned_country_counts","methodology":null,"sampled_at":null}}]}