Iris

Type: object
A schema for publishing aggregated public opinion survey toplines and crosstabs: study metadata, a catalog of questions expressed as dimensional constructs, one or more waves of fielding, and the marginal distributions (toplines and subgroup crosstabs) those waves produced. No Additional Properties

root schema_version
Type: const
Iris version this instance follows. "dev" is the active development channel — the schema shape may change without notice. Real semver versions ("0.1.0", "1.0.0", …) ship at stable, immutable URLs under /x.y.z/.Specific value: "dev"

root study_id
Type: string
Short stable identifier for the study. Lowercase ASCII with dashes or underscores, e.g. "pew-atp-w173" or "gss-2024". Used in filenames, URLs, and cross-references.Must match regular expression: ^[a-z0-9][a-z0-9\-_]*$

root title
Type: string
Human-readable study title, e.g. "Pew ATP Wave 173 — AI and its impact". Shown in citations and dashboards.

root publisher
Type: object
The organization under whose name the study is published. For jointly branded releases (e.g. "AP-NORC Center"), use the joint brand as publisher and list the parent organizations in contributors. No Additional Properties

root publisher display_name
Type: string
Human-readable name shown in attribution contexts (citations, display tables).

root publisher url
Type: stringFormat: uri
[RECOMMENDED] Canonical homepage URL. Serves as the machine-readable identifier for the organization. Use a urn: scheme when no real URL exists (e.g. defunct orgs); omit entirely when no stable identifier is available.

root publisher roles
Type: array of string
What this organization contributed. Open vocabulary — consumers should accept unknown values. Suggested baseline (from FiveThirtyEight's historical poll taxonomy): "pollster" (firm that designed and fielded), "designer" (instrument designer when separate), "fielder" (subcontractor doing interviews), "sponsor" (client commissioning the wave), "sponsor_candidate" (candidate or campaign sponsor, for partisan polls), "funder" (separate from sponsor — e.g. foundation), "publisher" (media outlet releasing the results), "academic_partner" (affiliated research institution), "other" (anything else; describe in methodology_notes). An organization may carry multiple roles. No Additional Items

Each item of this array must be:

root publisher roles roles items
Type: string

root contributors
Type: array
Other organizations associated with the study — fielders, funders, commissioners, partners. Roles (if given) describe what each organization contributed. No Additional Items

Each item of this array must be:

root contributors Organization
Type: object
An organization associated with a study. URL, when present, is the canonical identifier: two references to the same URL denote the same organization across studies.Same definition as publisher

root methodology_notes
Type: string
Free-text notes about how the study was run: panel recruitment, mode mix, weighting targets, oversamples — anything a methodologist would want to know but that doesn't fit the structured fields below.

root source_urls
Type: array of string
Links to the authoritative published artifacts for this study — topline PDFs, methodology pages, microdata releases. Include at least one so consumers can trace numbers back to the source. No Additional Items

Each item of this array must be:

root source_urls source_urls items
Type: stringFormat: uri

root subgroup_schema
Type: object
Catalog of demographic variables used anywhere in this study's crosstabs. Declared once here; referenced from each wave's subgroups. Omit for total-sample-only studies. No Additional Properties

root subgroup_schema variables
Type: array
Demographic variables available for crosstabs in this study. No Additional Items

Each item of this array must be:

root subgroup_schema variables SubgroupVariable
Type: object
One demographic axis used in crosstabs — party identification, age bucket, census region, and so on. No Additional Properties

If the conditions in the "If" tab are respected, then the conditions in the "Then" tab should be respected. Otherwise, the conditions in the "Else" tab should be respected.

root subgroup_schema variables variables items if
Type: object

root subgroup_schema variables variables items if kind
Type: const
Specific value: "numeric"
root subgroup_schema variables variables items else
Type: object

The following properties are required:

  • values

root subgroup_schema variables variables items id
Type: string
Short machine identifier for the variable, e.g. "party_id" or "age_bucket". Referenced by each subgroup's filters.

root subgroup_schema variables variables items label
Type: string
[RECOMMENDED] Human-readable name, e.g. "Partisan identification with leaners".

root subgroup_schema variables variables items kind
Type: enum (of string) Default: "categorical"
Use "categorical" for discrete values (parties, regions); "numeric" for measured quantities (income, age in years). Most crosstab variables are categorical because their values have already been bucketed.

Must be one of:

  • "categorical"
  • "numeric"

root subgroup_schema variables variables items values
Type: array of object
Possible values the variable can take. Each has a code and a display label; rolled-up categories also list the raw codes they combine. Required when kind is "categorical" (the default); may be omitted when kind is "numeric" since there is no enumerable set. No Additional Items

Each item of this array must be:

root subgroup_schema variables variables items values values items
Type: object
No Additional Properties

root subgroup_schema variables variables items values values items code

Canonical code for this value. Strings for semantic codes ("dem", "urban"); integers when the pollster's codebook uses them.

root subgroup_schema variables variables items values values items label
Type: string
[RECOMMENDED] Display label shown in crosstab headers.

root subgroup_schema variables variables items values values items rollup_of
Type: array
If this value is a rollup of more granular codes (e.g. "Dem/Lean Dem" folds strong-dem, weak-dem, and lean-dem together), list the raw codes here. No Additional Items

Each item of this array must be:

root subgroup_schema variables variables items values values items rollup_of rollup_of items

root questions
Type: array
Every question reported in any wave of this study. Each question is defined once and reused across waves by id; trend lines emerge from multiple waves reporting against the same question. No Additional Items

Each item of this array must be:

root questions Question
Type: object
A question is a stem plus one or more dimensions. Each dimension is one reportable axis of response — a matrix row, a rank item, a multi-select option, or the lone dimension of a single-item question. A response_space (enum / integer_range / real_range / text) defines the set of legitimate values; it may be declared once at the question level (applying to all dimensions) or overridden per dimension. Response-space precedence when multiple are declared: dimension-within-variant > variant > dimension > question (most specific wins). No Additional Properties

root questions questions items id
Type: string
Short identifier for this question, unique within the study. Typically matches the pollster's questionnaire tag ("AI_HEARD", "Q12").

root questions questions items stem
Type: string
Shared prefix text. Empty for single-dimension questions where the full wording lives in the single dimension's text.

root questions questions items concept_refs
Type: array
Optional concept tags linking questions that measure the same underlying construct. Used two ways: (a) within a study, to bridge questions whose id was version-bumped on wording change so consumers can still derive a trend — declare a shared ref with scheme="local" (or any author-chosen namespace); (b) across studies, to federate across pollsters by matching against external vocabularies (ANES VCF codes, GSS mnemonics, Roper iPoll DOIs, DDI concept URIs). Same mechanism, different schemes. Trends within a single study are otherwise derived from matching question_id across waves ordered by field_dates — concept_refs is only needed when question_id is not stable. No Additional Items

Each item of this array must be:

root questions questions items concept_refs ConceptRef
Type: object
One (scheme, id) tuple pointing into an external or local vocabulary. Multiple refs may attach to the same question (e.g. one "local" for within-study rename-bridging, one "anes_vcf" for cross-study federation). No Additional Properties

root questions questions items concept_refs concept_refs items scheme
Type: string
Identifier of the naming scheme. Use "local" (or a study-specific namespace) for within-study linkage across renamed questions; use external-vocabulary schemes — e.g. "anes_vcf", "gss", "ess", "roper_ipoll", "ddi_concept", "cessda_topic" — for cross-pollster federation. Open vocabulary.

root questions questions items concept_refs concept_refs items id
Type: string
The identifier within that scheme. Could be a short code ("VCF0501"), a mnemonic ("polviews"), or a URI ("https://…").

root questions questions items notes
Type: string
Question-specific notes: rotation and anchor schemes, interviewer instructions, wording quirks. Anything a reader needs to interpret this question that doesn't fit the structured fields.

root questions questions items skip_notes
Type: string
Plain-English description of any skip logic ("Asked only of respondents who answered 1 or 2 to AI_HEARD"). When the question is conditional on earlier answers, this explains why the result's base.n_unweighted differs from the wave's full sample size.

root questions questions items dimensions
Type: array
One or more reportable axes of response. A single-item question has one dimension; a matrix has one per row; a ranking or multi-select has one per item. A MaxDiff question declares one dimension per item being scored.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

root questions questions items dimensions Dimension
Type: object
One reportable axis of response. For a single-item question, there is one dimension whose text carries the full wording; for a matrix, each row is a dimension; for a ranking or multi-select, each item is a dimension; for MaxDiff, each item being scored is a dimension. No Additional Properties

root questions questions items dimensions dimensions items id
Type: string
Short identifier for this dimension, unique within its question. Referenced by result.dimension_id and by any constraints.

root questions questions items dimensions dimensions items text
Type: string
For a single-dimension question, this carries the full question wording (stem is empty). For a matrix row, rank item, or MaxDiff item, this is the row/item label. May be omitted for anonymous dimensions.

root questions questions items dimensions dimensions items response_space
Type: object
Per-dimension response space. Overrides the question-level default when dimensions have different response scales.

root questions questions items dimensions dimensions items response_space oneOf EnumSpace
Type: object
A finite set of coded options — the backbone of Likert scales, forced-choice questions, and multi-select options (modelled as binary enums). No Additional Properties

root questions questions items dimensions dimensions items response_space oneOf item 0 ordered
Type: boolean Default: false
True if codes form an ordered continuum (Likert, intensity). When true, consumers may: (a) apply a monotone color scale with the declared order as canonical direction; (b) treat nets of contiguous code ranges as natural rollups; (c) interpret order-dependent stats (mean_rank, median code) as meaningful. Code.value, if supplied, should be monotone in the declared code order. False for nominal enumerations (parties, regions) where codes have no natural order.

root questions questions items dimensions dimensions items response_space oneOf item 0 codes
Type: array
Every legitimate option a respondent can pick, including non-substantive options ("Don't know", "Refused") marked with missing: true.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

root questions questions items dimensions dimensions items response_space oneOf item 0 codes Code
Type: object
One option within an enum response space, or one missing-value tag on a numeric range. No Additional Properties

root questions questions items dimensions dimensions items response_space oneOf item 0 codes codes items code

The value the pollster's data uses for this option — string ("yes", "dem") or integer (1, -2). Must be unique within the response space.

root questions questions items dimensions dimensions items response_space oneOf item 0 codes codes items label
Type: string
[RECOMMENDED] Display text shown to respondents and in published tables, e.g. "Strongly agree" or "Don't know".

root questions questions items dimensions dimensions items response_space oneOf item 0 codes codes items value
Type: number
Optional numeric value for aggregation (means, regressions). A consumer-default numeric mapping — useful for Likert scales with symmetric numeric interpretations (e.g. strongly-positive = 2, somewhat-positive = 1, neutral = 0, somewhat-negative = −1, strongly-negative = −2). Not guaranteed to be interval-scaled; consumers requiring interval-scaled interpretation should treat this as a hint and apply their own scoring.

root questions questions items dimensions dimensions items response_space oneOf item 0 codes codes items pole
Type: enum (of string)
Which end of the spectrum this code anchors. Lets consumers auto-color a chart without hand-annotating every response space. "none" means polarity is not applicable to this code (e.g. a partisan self-ID code where no direction is implied) — it does not mean the respondent declined to answer. Use missing: true for non-substantive responses.

Must be one of:

  • "positive"
  • "neutral"
  • "negative"
  • "none"

root questions questions items dimensions dimensions items response_space oneOf item 0 codes codes items missing
Type: boolean Default: false
True if this code is a non-substantive response ("Don't know", "Refused", "No answer"). Lets consumers compute an "answered" base by excluding these entries.

root questions questions items dimensions dimensions items response_space oneOf item 0 codes codes items missing_kind
Type: enum (of string)
If missing is true, which kind: "dk" (don't know), "refused", "skipped" (not shown or no answer), "no_opinion" (offered as a distinct option), or "other".

Must be one of:

  • "dk"
  • "refused"
  • "skipped"
  • "no_opinion"
  • "other"

root questions questions items dimensions dimensions items response_space oneOf item 0 codes codes items anchor_text
Type: string
Anchor phrasing shown alongside the code in a questionnaire, e.g. "Cold — 0" paired with a 0-100 feeling thermometer value.

root questions questions items dimensions dimensions items response_space oneOf item 0 nets
Type: array
Named rollups over subsets of codes (e.g. "Favorable (net)" = 1 + 2). Declared here so every published net percentage carries its construction with it. A net's members may reference raw codes or other net ids (hierarchical nets). Difference nets capture pollster artifacts like "Net Approval" = total_approve − total_disapprove. No Additional Items

Each item of this array must be:

root questions questions items dimensions dimensions items response_space oneOf item 0 nets Net
Type: object
A named rollup over codes of an enum response space. Sum nets combine the share of their members; difference nets report the signed difference between a minuend and a subtrahend net. No Additional Properties

If the conditions in the "If" tab are respected, then the conditions in the "Then" tab should be respected. Otherwise, the conditions in the "Else" tab should be respected.

root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items if
Type: object

root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items then
Type: object

The following properties are required:

  • minuend_id
  • subtrahend_id
root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items else
Type: object

The following properties are required:

  • members

root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items id
Type: string
Short identifier for the net, referenced by result.stats.nets[].id.

root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items label
Type: string
[RECOMMENDED] Display label, e.g. "Favorable (net)" or "Net approval".

root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items kind
Type: enum (of string) Default: "sum"
"sum" — the default — combines the share of the listed members. "difference" reports minuend − subtrahend (e.g. Net Approval = total_approve − total_disapprove).

Must be one of:

  • "sum"
  • "difference"

root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items members
Type: array
For sum nets: codes or other net ids that together make up this net. Each must resolve to a defined code on this response space or a net declared alongside it. String members are first looked up as net ids, then as string codes; integer members are always codes. Omit for difference nets (which use minuend_id/subtrahend_id instead).

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items members members items

root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items minuend_id
Type: string
For difference nets: id of the net to subtract from. Must reference another declared net on the same response space.

root questions questions items dimensions dimensions items response_space oneOf item 0 nets nets items subtrahend_id
Type: string
For difference nets: id of the net to subtract. Must reference another declared net on the same response space.
root questions questions items dimensions dimensions items response_space oneOf IntegerRangeSpace
Type: object
Bounded integer values. Used for rank positions (1..N), feeling thermometers (0..100), and ladder questions (Cantril 0..10). No Additional Properties

root questions questions items dimensions dimensions items response_space oneOf item 1 kind
Type: const
Specific value: "integer_range"

root questions questions items dimensions dimensions items response_space oneOf item 1 step
Type: integer Default: 1
Step between allowed values. Usually 1 (every integer in range).

Value must be greater or equal to 1

root questions questions items dimensions dimensions items response_space oneOf item 1 anchors
Type: array of object
Labelled reference points along the range, e.g. 0 = "Very cold", 50 = "Neutral", 100 = "Very warm" on a feeling thermometer. No Additional Items

Each item of this array must be:

root questions questions items dimensions dimensions items response_space oneOf item 1 anchors anchors items
Type: object
No Additional Properties

root questions questions items dimensions dimensions items response_space oneOf item 1 anchors anchors items at
Type: integer
The integer value this label attaches to.

root questions questions items dimensions dimensions items response_space oneOf item 1 anchors anchors items label
Type: string
Text shown at this point on the scale.

root questions questions items dimensions dimensions items response_space oneOf item 1 missing_codes
Type: array
Non-substantive responses ("Don't know", "Refused") shown alongside the numeric scale. Structurally identical to enum codes but stored separately because they aren't part of the numeric range. No Additional Items

Each item of this array must be:

root questions questions items dimensions dimensions items response_space oneOf item 1 missing_codes Code
Type: object
One option within an enum response space, or one missing-value tag on a numeric range.Same definition as questions_items_dimensions_items_response_space_oneOf_i0_codes_items
root questions questions items dimensions dimensions items response_space oneOf RealRangeSpace
Type: object
Bounded continuous values. Used for continuous scores like rescaled MaxDiff percentages or budget allocations with fractional amounts. No Additional Properties

root questions questions items dimensions dimensions items response_space oneOf item 2 kind
Type: const
Specific value: "real_range"

root questions questions items dimensions dimensions items response_space oneOf item 2 step
Type: number
Smallest increment between allowed values. 0.01 for percentages, 0.5 for half-points, and so on.

Value must be strictly greater than 0

root questions questions items dimensions dimensions items response_space oneOf item 2 anchors
Type: array of object
Labelled reference points along the range. No Additional Items

Each item of this array must be:

root questions questions items dimensions dimensions items response_space oneOf item 2 anchors anchors items
Type: object
No Additional Properties

root questions questions items dimensions dimensions items response_space oneOf item 2 anchors anchors items at
Type: number
The numeric value this label attaches to.

root questions questions items dimensions dimensions items response_space oneOf item 2 anchors anchors items label
Type: string
Text shown at this point on the scale.

root questions questions items dimensions dimensions items response_space oneOf item 2 missing_codes
Type: array
Non-substantive responses shown alongside the numeric scale. No Additional Items

Each item of this array must be:

root questions questions items dimensions dimensions items response_space oneOf item 2 missing_codes Code
Type: object
One option within an enum response space, or one missing-value tag on a numeric range.Same definition as questions_items_dimensions_items_response_space_oneOf_i0_codes_items
root questions questions items dimensions dimensions items response_space oneOf TextSpace
Type: object
Open-ended text responses. Rarely used in published toplines — pollsters almost always post-code verbatims into an enum for reporting — but declared here for completeness and for instrument descriptions where the uncoded form matters. No Additional Properties

root questions questions items dimensions dimensions items response_space oneOf item 3 min_length
Type: integer
Minimum character count if the pollster enforced one; leave unset otherwise.

Value must be greater or equal to 0

root questions questions items dimensions dimensions items response_space oneOf item 3 max_length
Type: integer
Maximum character count if the pollster enforced one.

Value must be greater or equal to 1

root questions questions items response_space
Type: object
Default response space applied to every dimension that does not override. If omitted, each dimension must declare its own. Superseded by variant response_space_override and dimension-within-variant overrides where present.Same definition as response_space

root questions questions items constraints
Type: array
Cross-dimension rules the question mechanics impose: ranking as a permutation, budget allocation as a sum, "None of the above" as an exclusivity. Five kinds available. Variants may override via constraints_override when a variant's dimension set differs. No Additional Items

Each item of this array must be:

root questions questions items constraints Constraint
Type: object
A cross-dimension rule imposed by the question's mechanics. Choose the kind that matches the question: permutation for full rankings, sum for budget allocations, exclusive for "None of the above", and so on.

root questions questions items constraints constraints items oneOf PermutationConstraint
Type: object
The named dimensions collectively take the values 1..N exactly once each (full ranking). No Additional Properties

root questions questions items constraints constraints items oneOf item 0 kind
Type: const
Specific value: "permutation"

root questions questions items constraints constraints items oneOf item 0 dimensions
Type: array of string
The ranked items. Each respondent assigns each dimension a distinct rank from 1 to N.

Must contain a minimum of 2 items

No Additional Items

Each item of this array must be:

root questions questions items constraints constraints items oneOf item 0 dimensions dimensions items
Type: string
root questions questions items constraints constraints items oneOf PartialRankConstraint
Type: object
Respondents rank top_k of the named dimensions; the rest are unranked. No Additional Properties

root questions questions items constraints constraints items oneOf item 1 kind
Type: const
Specific value: "partial_rank"

root questions questions items constraints constraints items oneOf item 1 dimensions
Type: array of string
Items available to rank.

Must contain a minimum of 2 items

No Additional Items

Each item of this array must be:

root questions questions items constraints constraints items oneOf item 1 dimensions dimensions items
Type: string

root questions questions items constraints constraints items oneOf item 1 top_k
Type: integer
How many items each respondent ranks; the rest are unranked.

Value must be greater or equal to 1

root questions questions items constraints constraints items oneOf SumConstraint
Type: object
The named dimensions' numeric values sum to the given constant (constant-sum or budget allocation). No Additional Properties

root questions questions items constraints constraints items oneOf item 2 kind
Type: const
Specific value: "sum"

root questions questions items constraints constraints items oneOf item 2 dimensions
Type: array of string
Items across which the sum applies.

Must contain a minimum of 2 items

No Additional Items

Each item of this array must be:

root questions questions items constraints constraints items oneOf item 2 dimensions dimensions items
Type: string

root questions questions items constraints constraints items oneOf item 2 value
Type: number
The constant the dimensions must sum to, e.g. 100 for percent-allocation questions.
root questions questions items constraints constraints items oneOf CardinalityConstraint
Type: object
At least min and at most max of the named dimensions take the target code value — typically the "selected" code in a multi-select. No Additional Properties

root questions questions items constraints constraints items oneOf item 3 kind
Type: const
Specific value: "cardinality"

root questions questions items constraints constraints items oneOf item 3 dimensions
Type: array of string
Items over which the count applies.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

root questions questions items constraints constraints items oneOf item 3 dimensions dimensions items
Type: string

root questions questions items constraints constraints items oneOf item 3 min
Type: integer
Lower bound on the count of dimensions taking target_code.

Value must be greater or equal to 0

root questions questions items constraints constraints items oneOf item 3 max
Type: integer
Upper bound on the count. Common values: 3 for "pick up to 3"; equal to the number of dimensions for unrestricted.

Value must be greater or equal to 1

root questions questions items constraints constraints items oneOf ExclusiveConstraint
Type: object
If when_dimension takes value when_code, none of the excludes dimensions may take their target code. Used for "None of the above" in multi-selects. No Additional Properties

root questions questions items constraints constraints items oneOf item 4 kind
Type: const
Specific value: "exclusive"

root questions questions items constraints constraints items oneOf item 4 when_dimension
Type: string
The sentinel dimension that, when selected, excludes the others.

root questions questions items constraints constraints items oneOf item 4 when_code

The code value on when_dimension that triggers the exclusion — typically the "selected" code.

root questions questions items constraints constraints items oneOf item 4 excludes
Type: array of string
Dimensions that must not take their selected code when the sentinel fires.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

root questions questions items constraints constraints items oneOf item 4 excludes excludes items
Type: string

root questions questions items variants
Type: array
Split-sample wording variants. When different halves of the sample see different phrasings of the same question, declare each wording as a variant here; results then reference variant_id. No Additional Items

Each item of this array must be:

root questions questions items variants Variant
Type: object
A split-sample variant. May override stem, dimensions, response_space, and constraints; unspecified fields inherit from the parent question. No Additional Properties

root questions questions items variants variants items variant_id
Type: string
Short identifier for this variant, unique within the question. Referenced by result.variant_id.

root questions questions items variants variants items label
Type: string
Display label distinguishing this wording from the others, e.g. "Form A (Pew framing)" or "with 'concerned' anchor".

root questions questions items variants variants items stem_override
Type: string
Stem text used under this variant, if it differs from the question's stem.

root questions questions items variants variants items dimensions_override
Type: array
Dimensions used under this variant, if they differ from the question's dimensions. No Additional Items

Each item of this array must be:

root questions questions items variants variants items dimensions_override Dimension
Type: object
One reportable axis of response. For a single-item question, there is one dimension whose text carries the full wording; for a matrix, each row is a dimension; for a ranking or multi-select, each item is a dimension; for MaxDiff, each item being scored is a dimension.Same definition as questions_items_dimensions_items

root questions questions items variants variants items response_space_override
Type: object
Response space used under this variant, if it differs from the question's.Same definition as response_space

root questions questions items variants variants items constraints_override
Type: array
Constraints used under this variant, if they differ from the question's. Use when a variant drops or adds dimensions referenced by a constraint (e.g. a ranking variant that removes one of the items). No Additional Items

Each item of this array must be:

root questions questions items variants variants items constraints_override Constraint
Type: object
A cross-dimension rule imposed by the question's mechanics. Choose the kind that matches the question: permutation for full rankings, sum for budget allocations, exclusive for "None of the above", and so on.Same definition as questions_items_constraints_items

root waves
Type: array
One entry per fielding occasion. Single-shot studies still use an array of one. Field dates, sample metadata, and results live on the wave; everything constant across the program lives at the study level.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

root waves Wave
Type: object
A single fielding occasion. Carries field dates, sample metadata, the subgroups reported in this wave, and the results themselves. Multiple waves in one Study form a trend. Trend-reference waves (entries carried only to support prior-wave comparisons) may omit the RECOMMENDED fields below when authoritative methodology is documented in the original release. No Additional Properties

root waves waves items wave_id
Type: string
Short identifier for the wave, e.g. "w173" or "2024-08". Unique within the study.

root waves waves items label
Type: string
Human-readable wave label, e.g. "Wave 173 — June 2025".

root waves waves items field_dates
Type: object
[RECOMMENDED] Start and end of the fielding window, in ISO 8601 (YYYY-MM-DD). For continuous panels, use the published collection window for this wave. May be omitted for trend-reference waves whose field dates are not republished in the current topline. No Additional Properties

root waves waves items field_dates start
Type: stringFormat: date

root waves waves items field_dates end
Type: stringFormat: date

root waves waves items sample
Type: object
[RECOMMENDED] Sample design, size, and weighting for this wave. May be omitted for trend-reference waves; authoritative studies should provide it. No Additional Properties

root waves waves items sample population
Type: string
[RECOMMENDED] Target population in plain language, e.g. "U.S. adults 18+" or "Registered voters in Iowa".

root waves waves items sample n
Type: integer
[RECOMMENDED] Unweighted completed interviews in this wave.

Value must be greater or equal to 1

root waves waves items sample mode
Type: array of enum (of string)
Modes of data collection. Follows AAPOR's conventional categories; Iris does not mint this taxonomy. Use "mixed" with weighting.notes for hybrid designs that don't fit cleanly. No Additional Items

Each item of this array must be:

root waves waves items sample mode mode items
Type: enum (of string)

Must be one of:

  • "online"
  • "phone_landline"
  • "phone_cell"
  • "sms"
  • "mail"
  • "in_person"
  • "mixed"
  • "other"

root waves waves items sample frame
Type: enum (of string)
Sampling frame type. Follows AAPOR's conventional distinctions between probability and nonprobability designs; Iris does not mint this taxonomy.

Must be one of:

  • "probability_abs"
  • "probability_rdd"
  • "probability_panel"
  • "nonprobability_panel"
  • "river"
  • "quota"
  • "mixed"
  • "other"

root waves waves items sample margin_of_error
Type: number
Design-effect-adjusted margin of error at 95% confidence, in percentage points, for the full sample. A wave of 5,000 U.S. adults typically reports ±1.6. Subgroup-level precision lives on Result.precision.

root waves waves items sample weighting
Type: object
Weighting procedure used to produce the reported percentages. No Additional Properties

root waves waves items sample weighting scheme
Type: enum (of string)
Weighting procedure. Follows AAPOR's conventional categories; Iris does not mint this taxonomy.

Must be one of:

  • "raking"
  • "post_stratification"
  • "propensity"
  • "none"
  • "other"

root waves waves items sample weighting variables
Type: array of string
Demographic variables used as raking or post-stratification targets, e.g. ["age", "sex", "education", "region"]. No Additional Items

Each item of this array must be:

root waves waves items sample weighting variables variables items
Type: string

root waves waves items sample weighting notes
Type: string
Free-text description of weighting benchmarks, trimming rules, or anything else a reader needs to interpret the percentages.

root waves waves items subgroups
Type: array
Crosstab cells actually reported in this wave. Each subgroup references variables declared in the study-level subgroup_schema. Full-sample results are expressed by omitting subgroup_id on the Result — no sentinel subgroup need be declared. No Additional Items

Each item of this array must be:

root waves waves items subgroups Subgroup
Type: object
A subgroup reported in this wave's crosstabs: a filter that identifies a cell like "Democrats", "women 18-29", or "respondents who answered 1 or 2 to AI_BENE". Simple subgroups use a flat filter list (AND of matches, with OR within values). Leaner-allocated or otherwise disjunctive subgroups use the nested filter form. No Additional Properties

root waves waves items subgroups subgroups items id
Type: string
Short identifier for this subgroup, e.g. "dem" or "women_18_29". Referenced by result.subgroup_id. Unique within the wave.

root waves waves items subgroups subgroups items label
Type: string
[RECOMMENDED] Display label for this subgroup in tables and charts.

root waves waves items subgroups subgroups items filters

The filter(s) that define this subgroup. Two forms are accepted: a flat array of matches (AND across entries, OR within values), or a single nested expression using all_of / any_of / match for leaner-allocated or otherwise disjunctive subgroups. Each match is either variable-based ({variable_id, values}) or question-based ({question_id, dimension_id, values}) — see SubgroupMatch.

root waves waves items subgroups subgroups items filters oneOf item 0
Type: array
Flat form. Each entry names one variable and qualifying values; entries AND together, values within an entry OR together. Equivalent to { all_of: [ match, match, … ] }. No Additional Items

Each item of this array must be:

root waves waves items subgroups subgroups items filters oneOf item 0 SubgroupMatch
Type: object
A single match leaf. Two forms: (a) variable-based — {variable_id: "age_band", values: ["18_29", "30_49"]} qualifies respondents by a declared demographic variable; (b) question-based — {question_id: "AI_BENE", dimension_id: "main", values: [1, 2]} qualifies respondents who gave one of the listed responses to a prior question, used for skip-logic-defined cohorts and conditional follow-ups. Exactly one of variable_id / question_id must be present. Values OR together within a match. No Additional Properties

root waves waves items subgroups subgroups items filters oneOf item 0 item 0 items oneOf item 0
Type: object

The following properties are required:

  • variable_id
  • values
root waves waves items subgroups subgroups items filters oneOf item 0 item 0 items oneOf item 1
Type: object

The following properties are required:

  • question_id
  • values

root waves waves items subgroups subgroups items filters oneOf item 0 item 0 items variable_id
Type: string
Id of a variable declared in the study's subgroup_schema. Mutually exclusive with question_id.

root waves waves items subgroups subgroups items filters oneOf item 0 item 0 items question_id
Type: string
Id of a question declared at the study level. Mutually exclusive with variable_id. Use when filtering by a prior-question response — e.g. "respondents who answered 1 or 2 to AI_BENE".

root waves waves items subgroups subgroups items filters oneOf item 0 item 0 items dimension_id
Type: string
Id of a dimension within the referenced question. Required when question_id names a multi-dimension question (matrix, ranking, multi-select); may be omitted for single-dimension questions, in which case the sole dimension is assumed.

root waves waves items subgroups subgroups items filters oneOf item 0 item 0 items values
Type: array
Qualifying values. For variable-based matches, values of the referenced subgroup variable. For question-based matches, codes on the referenced dimension's response space. Multiple values form a disjunction.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

root waves waves items subgroups subgroups items filters oneOf item 0 item 0 items values values items

root waves waves items subgroups subgroups items filters oneOf SubgroupFilter
Type: object
A boolean combination of subgroup matches. Exactly one of all_of / any_of / match must be populated. Used for filters that cannot be expressed as a flat AND of single-variable matches — e.g. "Dem or Lean Dem" = party=D OR (party=I AND lean=D). No Additional Properties

root waves waves items subgroups subgroups items filters oneOf item 1 oneOf item 0
Type: object

The following properties are required:

  • all_of
root waves waves items subgroups subgroups items filters oneOf item 1 oneOf item 1
Type: object

The following properties are required:

  • any_of
root waves waves items subgroups subgroups items filters oneOf item 1 oneOf item 2
Type: object

The following properties are required:

  • match

root waves waves items subgroups subgroups items filters oneOf item 1 all_of
Type: array
Every child must hold.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

root waves waves items subgroups subgroups items filters oneOf item 1 all_of SubgroupFilterNode
Type: object
Either a leaf match or a nested filter combinator. A leaf is a bare SubgroupMatch; a nested node wraps its match in a SubgroupFilter.

root waves waves items subgroups subgroups items filters oneOf item 1 all_of all_of items oneOf SubgroupMatch
Type: object
A single match leaf. Two forms: (a) variable-based — {variable_id: "age_band", values: ["18_29", "30_49"]} qualifies respondents by a declared demographic variable; (b) question-based — {question_id: "AI_BENE", dimension_id: "main", values: [1, 2]} qualifies respondents who gave one of the listed responses to a prior question, used for skip-logic-defined cohorts and conditional follow-ups. Exactly one of variable_id / question_id must be present. Values OR together within a match.Same definition as waves_items_subgroups_items_filters_oneOf_i0_items
root waves waves items subgroups subgroups items filters oneOf item 1 all_of all_of items oneOf SubgroupFilter
Type: object
A boolean combination of subgroup matches. Exactly one of all_of / any_of / match must be populated. Used for filters that cannot be expressed as a flat AND of single-variable matches — e.g. "Dem or Lean Dem" = party=D OR (party=I AND lean=D).Same definition as waves_items_subgroups_items_filters_oneOf_i1

root waves waves items subgroups subgroups items filters oneOf item 1 any_of
Type: array
At least one child must hold.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

root waves waves items subgroups subgroups items filters oneOf item 1 any_of SubgroupFilterNode
Type: object
Either a leaf match or a nested filter combinator. A leaf is a bare SubgroupMatch; a nested node wraps its match in a SubgroupFilter.Same definition as waves_items_subgroups_items_filters_oneOf_i1_all_of_items

root waves waves items subgroups subgroups items n_unweighted
Type: integer
Unweighted count of respondents in this subgroup.

Value must be greater or equal to 0

root waves waves items subgroups subgroups items n_weighted
Type: number
Weighted count of respondents in this subgroup, if the pollster reports one.

Value must be greater or equal to 0

root waves waves items subgroups subgroups items parent_subgroup_id
Type: string
Id of the parent subgroup this one partitions, if any. Omit when the parent is the full sample. Enables pct_of_parent to be interpreted.

root waves waves items subgroups subgroups items pct_of_parent
Type: number
Share of the parent subgroup represented by this subgroup — e.g. in exit polls, "voters ages 18–29 made up 14% of all voters". Requires parent_subgroup_id.

Value must be greater or equal to 0 and lesser or equal to 100

root waves waves items results
Type: array
Published marginal distributions for this wave — one entry per (question, dimension, variant, subgroup) slice. No Additional Items

Each item of this array must be:

root waves waves items results Result
Type: object
One published marginal: the distribution of responses on a single dimension, within one (question, variant, subgroup) slice, in this wave. No Additional Properties

root waves waves items results results items question_id
Type: string
Id of the question this result reports on. Must match a question declared at the study level.

root waves waves items results results items dimension_id
Type: string
Id of the dimension within that question that this result marginalizes over.

root waves waves items results results items variant_id
Type: string
If the question has split-sample variants, which one this result belongs to. Omit for the canonical form.

root waves waves items results results items subgroup_id
Type: string
Id of the subgroup this result is filtered to. Omit for full-sample results — there is no sentinel id for the full sample, absence is the signal.

root waves waves items results results items base
Type: object
The slice over which this result's percentages are computed — unified object carrying base kind, counts, and optional notes. No Additional Properties

root waves waves items results results items base kind
Type: enum (of string)
Which denominator convention. "all" = full subgroup including DK/refused/etc.; "answered" = excludes entries marked missing: true (those entries are then typically absent from the distribution); "custom" = any other filter — describe in notes.

Must be one of:

  • "all"
  • "answered"
  • "custom"

root waves waves items results results items base n_unweighted
Type: integer
Unweighted count of respondents in the base.

Value must be greater or equal to 0

root waves waves items results results items base n_weighted
Type: number
Weighted count of respondents in the base, if the pollster reports one.

Value must be greater or equal to 0

root waves waves items results results items base notes
Type: string
Free-text description of the base. Required for kind="custom"; ignored for the others.

root waves waves items results results items precision
Type: object
Subgroup-level precision — margin of error, design effect, confidence level — for the percentages in this result. Supplements the wave-level sample.margin_of_error, which applies to the full sample. No Additional Properties

root waves waves items results results items precision margin_of_error
Type: number
Design-effect-adjusted margin of error in percentage points, at the confidence level given by ci_level (default 0.95). Applies to the subgroup and base this result reports on.

root waves waves items results results items precision design_effect
Type: number
Design effect (Deff or Kish's design factor) on the subgroup's estimates. A Deff of 1.0 indicates a simple random sample; larger values indicate variance inflation from weighting.

Value must be strictly greater than 0

root waves waves items results results items precision ci_level
Type: number
Confidence level used to compute margin_of_error and any distribution-entry ci bounds, e.g. 0.95 for 95%.

Value must be strictly greater than 0 and strictly lesser than 1

root waves waves items results results items precision method
Type: string
How the precision was computed — e.g. "taylor_linearized", "jackknife", "bootstrap", "normal_approximation". Open vocabulary.

root waves waves items results results items distribution
Type: object
The percentages themselves. Choose the kind that matches the dimension: "categorical" (one entry per code, entries sum to ~100%), "multi_select" (entries are per-option % selected, may sum to >100%), "numeric" (summary stats and/or bins over an integer/real range), or "best_worst" (MaxDiff aggregates per scored item).

root waves waves items results results items distribution oneOf CategoricalDistribution
Type: object
Marginal distribution over the codes of an enum response space. Use kind="categorical" when the dimension is a single pick and entries sum to ~100% (modulo rounding); use kind="multi_select" to report a select-all-that-apply battery under one dimension whose response_space codes are the options — entries are per-option % selected and may sum to >100%. The N-binary-dimensions form of multi-select remains canonical; multi_select is a compact alternative for high-cardinality batteries. No Additional Properties

root waves waves items results results items distribution oneOf item 0 kind
Type: enum (of string)
"categorical" — entries are mutually exclusive code shares summing to ~100%. "multi_select" — entries are per-option % selected and may sum to >100%. The "% selected" reading is the signal for downstream consumers.

Must be one of:

  • "categorical"
  • "multi_select"

root waves waves items results results items distribution oneOf item 0 weighting
Type: enum (of string) Default: "weighted"
Whether the pct values are weighted or unweighted. Most pollster topline percentages are weighted; commercial crosstabs often run significance tests on unweighted cell counts. Default is "weighted" — set explicitly when publishing unweighted.

Must be one of:

  • "weighted"
  • "unweighted"

root waves waves items results results items distribution oneOf item 0 entries
Type: array of object
One entry per reported code. For kind="categorical", cover every non-missing code (plus any missing codes still in the denominator under base.kind="all"). For kind="multi_select", one entry per option with pct = % selected. No Additional Items

Each item of this array must be:

root waves waves items results results items distribution oneOf item 0 entries entries items
Type: object
No Additional Properties

root waves waves items results results items distribution oneOf item 0 entries entries items pct
Type: number
Percentage of the base for this code — % choosing it (categorical) or % selecting it (multi_select). When pollsters report "<1", publishers typically round to 1; document the convention used in methodology_notes. Interpretation (weighted vs. unweighted) is governed by the enclosing distribution's weighting flag.

Value must be greater or equal to 0 and lesser or equal to 100

root waves waves items results results items distribution oneOf item 0 entries entries items count
Type: object
Respondent counts for this cell, if published. No Additional Properties

root waves waves items results results items distribution oneOf item 0 entries entries items count unweighted
Type: integer
Unweighted count of respondents contributing to this cell.

Value must be greater or equal to 0

root waves waves items results results items distribution oneOf item 0 entries entries items count weighted
Type: number
Weighted count, if published.

Value must be greater or equal to 0

root waves waves items results results items distribution oneOf item 0 entries entries items ci
Type: object
Confidence bounds on pct. Pair with enclosing result.precision.ci_level. No Additional Properties

root waves waves items results results items distribution oneOf item 0 entries entries items ci lower
Type: number
Lower confidence bound on the percentage.

root waves waves items results results items distribution oneOf item 0 entries entries items ci upper
Type: number
Upper confidence bound on the percentage.
root waves waves items results results items distribution oneOf NumericDistribution
Type: object
Marginal distribution over a numeric response space (integer_range or real_range). May report summary statistics, a binned histogram, or both. Missing-code shares are reported separately. No Additional Properties

root waves waves items results results items distribution oneOf item 1 kind
Type: const
Specific value: "numeric"

root waves waves items results results items distribution oneOf item 1 weighting
Type: enum (of string) Default: "weighted"
Whether summary stats and bin pcts are weighted or unweighted. Default "weighted".

Must be one of:

  • "weighted"
  • "unweighted"

root waves waves items results results items distribution oneOf item 1 summary
Type: object
Summary statistics over the numeric responses. No Additional Properties

root waves waves items results results items distribution oneOf item 1 summary mean
Type: number
Mean value over respondents in the base.

root waves waves items results results items distribution oneOf item 1 summary sd
Type: number
Standard deviation.

root waves waves items results results items distribution oneOf item 1 summary min
Type: number
Smallest value observed — not the scale's declared minimum.

root waves waves items results results items distribution oneOf item 1 summary max
Type: number
Largest value observed.

root waves waves items results results items distribution oneOf item 1 bins
Type: array of object
Histogram buckets, each reporting the share of respondents whose answer fell in that range. Useful when the pollster publishes a distribution plot but not raw microdata. No Additional Items

Each item of this array must be:

root waves waves items results results items distribution oneOf item 1 bins bins items
Type: object
No Additional Properties

root waves waves items results results items distribution oneOf item 1 bins bins items from
Type: number
Lower bound of the bin (inclusive).

root waves waves items results results items distribution oneOf item 1 bins bins items to
Type: number
Upper bound of the bin.

root waves waves items results results items distribution oneOf item 1 bins bins items inclusive_end
Type: boolean Default: false
True if the upper bound is inclusive; false (default) if exclusive.

root waves waves items results results items distribution oneOf item 1 bins bins items label
Type: string
Display label, e.g. "Under 25" or "Very warm (81–100)".

root waves waves items results results items distribution oneOf item 1 bins bins items pct
Type: number
Percentage of the base in this bin.

Value must be greater or equal to 0 and lesser or equal to 100

root waves waves items results results items distribution oneOf item 1 bins bins items count_unweighted
Type: integer
Unweighted count in this bin, if published.

Value must be greater or equal to 0

root waves waves items results results items distribution oneOf item 1 missing
Type: array of object
Share of respondents who gave a non-substantive answer. Each entry references one of the response space's missing_codes. No Additional Items

Each item of this array must be:

root waves waves items results results items distribution oneOf item 1 missing missing items
Type: object
No Additional Properties

root waves waves items results results items distribution oneOf item 1 missing missing items pct
Type: number
Share of the base represented by this missing code.

Value must be greater or equal to 0 and lesser or equal to 100

root waves waves items results results items distribution oneOf BestWorstDistribution
Type: object
MaxDiff / best-worst scaling aggregate for one scored item. In a MaxDiff question each dimension_id identifies one item; a Result of this kind reports one item's aggregate. Iris v1 covers the published-table shape (counts and simple rescaled scores). HB-estimated individual-level utilities (mean/SD/RLH) and anchored-MaxDiff outputs (pct_respondents_above, etc.) are deliberately out of scope — they are Sawtooth-platform-specific and not commonly published in public opinion toplines. No Additional Properties

root waves waves items results results items distribution oneOf item 2 kind
Type: const
Specific value: "best_worst"

root waves waves items results results items distribution oneOf item 2 method
Type: enum (of string)
How the aggregate was produced. "counts" = raw best_count / worst_count / appearances, no scoring. "bw_score" = counts plus a computed best-minus-worst score (often normalized by appearances). "hb" = hierarchical-Bayes estimated; Iris only carries the published summary here, not individual-level utilities.

Must be one of:

  • "counts"
  • "bw_score"
  • "hb"

root waves waves items results results items distribution oneOf item 2 weighting
Type: enum (of string) Default: "weighted"
Whether the reported aggregates are weighted or unweighted.

Must be one of:

  • "weighted"
  • "unweighted"

root waves waves items results results items distribution oneOf item 2 appearances
Type: integer
Number of times this item appeared across choice sets shown to respondents in the base.

Value must be greater or equal to 0

root waves waves items results results items distribution oneOf item 2 best_count
Type: integer
Number of times this item was picked as best across all choice sets.

Value must be greater or equal to 0

root waves waves items results results items distribution oneOf item 2 worst_count
Type: integer
Number of times this item was picked as worst across all choice sets.

Value must be greater or equal to 0

root waves waves items results results items distribution oneOf item 2 bw_score
Type: number
Best-minus-worst score. Often normalized by appearances and published on a −100 to +100 scale or standardized; describe the convention in methodology_notes.

root waves waves items results results items distribution oneOf item 2 rescaled_pct
Type: number
Rescaled probability score on a 0–100 scale, interpretable as the probability this item is selected best from a typical choice set. The most commonly cited MaxDiff headline number.

Value must be greater or equal to 0 and lesser or equal to 100

root waves waves items results results items distribution oneOf item 2 rank
Type: integer
Rank of this item among all scored items under this method (1 = highest).

Value must be greater or equal to 1

root waves waves items results results items distribution oneOf item 2 se
Type: number
Standard error of the item's reported score, if published.

Value must be greater or equal to 0

root waves waves items results results items distribution oneOf item 2 ci
Type: object
Confidence bounds on rescaled_pct or bw_score, as produced. No Additional Properties

root waves waves items results results items stats
Type: object
Precomputed statistics — nets, mean ranks — that the pollster published alongside the raw distribution. No Additional Properties

root waves waves items results results items stats mean_rank
Type: number
Mean rank across respondents for a single dimension of a ranking question. Lower means more preferred.

root waves waves items results results items stats top_share
Type: number
Share of respondents who ranked this dimension first (for rankings) or picked it (for most-important / most-concerning questions).

Value must be greater or equal to 0 and lesser or equal to 100

root waves waves items results results items stats nets
Type: array of object
Precomputed net percentages, one per net declared on the response space. Each entry's id references a net defined on response_space.nets[]; the display label lives there. No Additional Items

Each item of this array must be:

root waves waves items results results items stats nets nets items
Type: object
No Additional Properties

root waves waves items results results items stats nets nets items id
Type: string
Id of the net being reported. Must match a net id declared on the response space.

root waves waves items results results items stats nets nets items pct
Type: number
The net percentage — the combined share (for sum nets) or signed difference (for difference nets).

root waves waves items notes
Type: string
Wave-specific notes that don't fit the structured fields: oversample details, field events, deviations from the study's standard methodology.