RESPONSE SCHEMA
Small records.
Clear meanings.
An explicit field map for the three local examples. This is a proposed application contract, not a universal provider schema.
Shared conventions
Every fixture includes sample: true. All URLs in the example data point to this site. Position values and observation labels are synthetic; they are not live performance evidence.
| Field | Type | Meaning |
|---|---|---|
sample | boolean | Always true in these fixtures. Do not remove the sample label and present the data as measured. |
query / keyword / task | string | The illustrative question or topic for this particular record. |
status / limitations | string / array | An explicit statement about the sample and the absence of live operations. |
SERP example
| Field | Type | Meaning |
|---|---|---|
context.country | string | The requested example country, US. It is not a verified observation location. |
context.language | string | The requested example language, en. |
organic_results | array | A synthetic list of result records. |
position | integer | A made-up one-based example position, not a Google ranking. |
title / url | string | A local guide title and destination used to demonstrate the record shape. |
Keyword example
| Field | Type | Meaning |
|---|---|---|
device / country | string | Illustrative context values; no device session was observed. |
observations | array | Two synthetic records labeled Sample A and Sample B. |
label | string | A sample label, not a timestamp. A real system should use its observed time. |
position | integer | Synthetic values used to explore the shape of an observation history. |
LLM evidence example
| Field | Type | Meaning |
|---|---|---|
sources | array | Illustrative source records, not results of a live retrieval. |
id | string | A stable identifier used by claim_refs. |
passage | string | An illustrative context string, not a fetched quotation. |
claim_refs | array | Identifiers that should resolve to records in sources. |
limitations | array | The explicit absence of a live retrieval or model call. |
Extend the contract deliberately
A live adapter should add source identity, observation time, requested and confirmed context, coverage, and a well-defined outcome. Keep provider-specific fields outside the shared core until their meanings are documented. Validate destination URLs and render externally influenced strings as text.
Empty results, a missing optional field, and a failed request should remain separate outcomes. Never infer a rank or search-volume estimate from a missing value.