SVIS Models¶
The canonical definitions are in survey_scribe.models.svis and are re-exported
from survey_scribe. See the SVIS Field Guide for complete
field tables and application-policy boundaries.
svis ¶
Survey Variable Information Schema (SVIS) legacy-compatible models.
DataType ¶
Bases: str, Enum
Simplified data type used for harmonization.
StudyType ¶
Bases: str, Enum
Survey instrument classification.
UnitLevel ¶
AnswerCategory ¶
Bases: BaseModel
One answer option for a categorical variable.
code
class-attribute
instance-attribute
¶
code: int | str = Field(
description="Value stored in the raw microdata file."
)
label
class-attribute
instance-attribute
¶
label: str = Field(
description="Human-readable answer label."
)
is_missing
class-attribute
instance-attribute
¶
is_missing: bool = Field(
default=False,
description="Whether the code represents a non-substantive missing response.",
)
NumericRange ¶
Bases: BaseModel
Valid value range for a numeric variable.
min_value
class-attribute
instance-attribute
¶
min_value: float | None = Field(
default=None, description="Minimum valid value."
)
max_value
class-attribute
instance-attribute
¶
max_value: float | None = Field(
default=None, description="Maximum valid value."
)
notes
class-attribute
instance-attribute
¶
notes: str | None = Field(
default=None,
description="Context about range interpretation.",
)
SurveyVariable ¶
Bases: BaseModel
Structured description of one questionnaire variable.
raw_name
class-attribute
instance-attribute
¶
raw_name: str = Field(
description="Variable name used in raw microdata."
)
label
class-attribute
instance-attribute
¶
label: str | None = Field(
default=None,
description="Short human-readable variable label.",
)
question_text
class-attribute
instance-attribute
¶
question_text: str | None = Field(
default=None,
description="Question text preserved from the questionnaire.",
)
data_type
class-attribute
instance-attribute
¶
data_type: DataType = Field(
description="Harmonization-oriented variable type."
)
categories
class-attribute
instance-attribute
¶
categories: list[AnswerCategory] | None = Field(
default=None,
description="Complete answer options for categorical variables.",
)
numeric_range
class-attribute
instance-attribute
¶
numeric_range: NumericRange | None = Field(
default=None,
description="Documented valid range for numeric variables.",
)
universe
class-attribute
instance-attribute
¶
universe: str | None = Field(
default=None,
description="Population asked the question.",
)
skip_condition_raw
class-attribute
instance-attribute
¶
skip_condition_raw: str | None = Field(
default=None,
description="Unmodified source routing or skip instruction.",
)
module
class-attribute
instance-attribute
¶
module: str | None = Field(
default=None,
description="Questionnaire section or module.",
)
unit_of_analysis
class-attribute
instance-attribute
¶
unit_of_analysis: UnitLevel = Field(
default=UnitLevel.individual,
description="Entity described by the variable.",
)
source_page
class-attribute
instance-attribute
¶
source_page: int | None = Field(
default=None,
description="Zero-indexed source page for review provenance.",
)
extraction_confidence
class-attribute
instance-attribute
¶
extraction_confidence: float = Field(
ge=0.0,
le=1.0,
description="LLM self-assessed confidence in the accuracy of this extraction. Score the whole record, not individual fields. 1.0 = all fields clear and unambiguous. 0.9 = one minor uncertainty (e.g. label is slightly paraphrased). 0.7 = notable uncertainty but overall reliable. Below 0.7 = significant doubt; set needs_review=True. 0.0 = the LLM is guessing.",
)
needs_review
class-attribute
instance-attribute
¶
needs_review: bool = Field(
default=False,
description="Whether human review is required.",
)
notes
class-attribute
instance-attribute
¶
notes: str | None = Field(
default=None,
description="Extraction uncertainty or context.",
)
SurveySVIS ¶
Bases: BaseModel
Complete SVIS for one survey instrument.
survey_id
class-attribute
instance-attribute
¶
survey_id: str = Field(
description="Stable COUNTRYISO3_YEAR_ACRONYM identifier."
)
country_code
class-attribute
instance-attribute
¶
country_code: str = Field(
description="ISO3 survey country code."
)
survey_name
class-attribute
instance-attribute
¶
survey_name: str = Field(
description="Official survey name."
)
study_type
class-attribute
instance-attribute
¶
study_type: StudyType | None = Field(
default=None, description="Survey classification."
)
data_collection_mode
class-attribute
instance-attribute
¶
data_collection_mode: str | None = Field(
default=None,
description="Collection mode such as CAPI, paper, or mixed.",
)
language
class-attribute
instance-attribute
¶
language: str | None = Field(
default=None,
description="Primary questionnaire language.",
)
variables
class-attribute
instance-attribute
¶
variables: list[SurveyVariable] = Field(
description="Variables in stable source-document order."
)
source_file
class-attribute
instance-attribute
¶
source_file: str = Field(
description="Original questionnaire filename."
)
source_format
class-attribute
instance-attribute
¶
source_format: str = Field(
description="Source format such as pdf or xlsx."
)
extraction_date
class-attribute
instance-attribute
¶
extraction_date: date = Field(
description="Date on which extraction ran."
)
extraction_notes
class-attribute
instance-attribute
¶
extraction_notes: str | None = Field(
default=None,
description="Document-level extraction diagnostics.",
)