{
  "name": "Pergola Wiki field observation data dictionary",
  "version": "1.6",
  "dateModified": "2026-07-24",
  "fieldCount": 30,
  "landingPage": "https://pergola.wiki/field-observation-protocol/",
  "description": "A bilingual data dictionary for non-destructive, permissioned pergola observations. It excludes personal identifiers and does not authorize hazardous access, testing or diagnosis.",
  "records": [
    {
      "field": "record_id",
      "type": "text",
      "requirement": "required",
      "definition": "Stable, non-identifying record identifier.",
      "definitionZh": "稳定且不识别个人的记录编号。",
      "allowedValuesOrNote": "No names, addresses or contact details."
    },
    {
      "field": "record_version",
      "type": "text",
      "requirement": "required",
      "definition": "Protocol version used for the record.",
      "definitionZh": "本记录采用的协议版本。",
      "allowedValuesOrNote": "Use 1.5 for this release."
    },
    {
      "field": "observation_date_local",
      "type": "date",
      "requirement": "required",
      "definition": "Local calendar date of the observation.",
      "definitionZh": "观察发生地的本地日期。",
      "allowedValuesOrNote": "YYYY-MM-DD."
    },
    {
      "field": "observation_time_band",
      "type": "enum",
      "requirement": "required",
      "definition": "Broad local time band.",
      "definitionZh": "概括的本地时段。",
      "allowedValuesOrNote": "morning|midday|afternoon|evening|unknown"
    },
    {
      "field": "observer_role",
      "type": "enum",
      "requirement": "required",
      "definition": "Observer's relationship to the site without personal identity.",
      "definitionZh": "观察者与场地的关系，不记录个人身份。",
      "allowedValuesOrNote": "owner|occupant|installer|designer|inspector|researcher|other"
    },
    {
      "field": "consent_status",
      "type": "enum",
      "requirement": "required",
      "definition": "Whether the site owner or authorized controller permitted documentation.",
      "definitionZh": "场地所有者或获授权管理者是否允许记录。",
      "allowedValuesOrNote": "confirmed|not_confirmed"
    },
    {
      "field": "country_code",
      "type": "text",
      "requirement": "required",
      "definition": "ISO 3166-1 alpha-2 country code.",
      "definitionZh": "ISO 3166-1 alpha-2 国家代码。",
      "allowedValuesOrNote": "Example format: NZ, US, AU."
    },
    {
      "field": "region_generalized",
      "type": "text",
      "requirement": "optional",
      "definition": "State, province or broad region without a street address.",
      "definitionZh": "州、省或概括地区，不填写街道地址。",
      "allowedValuesOrNote": "Avoid exact residential location."
    },
    {
      "field": "site_context",
      "type": "enum",
      "requirement": "required",
      "definition": "Broad use context.",
      "definitionZh": "概括的使用场景。",
      "allowedValuesOrNote": "residential|commercial|hospitality|public|other"
    },
    {
      "field": "system_class",
      "type": "enum",
      "requirement": "required",
      "definition": "Visible overhead system class.",
      "definitionZh": "可见顶部系统类别。",
      "allowedValuesOrNote": "open_frame|operable_louver|fixed_roof|retractable_cover|mixed|unknown"
    },
    {
      "field": "roof_state_observed",
      "type": "enum",
      "requirement": "required",
      "definition": "Roof or cover state during observation.",
      "definitionZh": "观察时屋面或覆盖状态。",
      "allowedValuesOrNote": "open|part_open|closed|fixed|not_applicable|unknown"
    },
    {
      "field": "attachment_type",
      "type": "enum",
      "requirement": "required",
      "definition": "Relationship to another building.",
      "definitionZh": "与其他建筑的关系。",
      "allowedValuesOrNote": "freestanding|attached|mixed|unknown"
    },
    {
      "field": "primary_material_family",
      "type": "enum",
      "requirement": "required",
      "definition": "Visible primary frame material family only.",
      "definitionZh": "仅记录可见的主要框架材料类别。",
      "allowedValuesOrNote": "aluminum|steel|timber|masonry|mixed|unknown"
    },
    {
      "field": "approximate_age_band",
      "type": "enum",
      "requirement": "optional",
      "definition": "Age band based on documents or an explicitly identified estimate.",
      "definitionZh": "根据文件或明确标注的估计记录年龄区间。",
      "allowedValuesOrNote": "under_1y|1_to_5y|6_to_10y|over_10y|unknown"
    },
    {
      "field": "weather_context_source",
      "type": "text",
      "requirement": "optional",
      "definition": "Public weather-station or official alert reference.",
      "definitionZh": "公共气象站或官方预警引用。",
      "allowedValuesOrNote": "Do not observe during hazardous weather."
    },
    {
      "field": "precipitation_context",
      "type": "enum",
      "requirement": "optional",
      "definition": "Broad rain context for a safe post-event observation.",
      "definitionZh": "安全雨后观察的概括降雨背景。",
      "allowedValuesOrNote": "none|light_recent|moderate_recent|heavy_recent|unknown"
    },
    {
      "field": "shade_time_reference",
      "type": "text",
      "requirement": "optional",
      "definition": "Timestamp or time band for a shade observation.",
      "definitionZh": "阴影观察的时间戳或时段。",
      "allowedValuesOrNote": "Record orientation separately in notes."
    },
    {
      "field": "occupied_area_shaded_band",
      "type": "enum",
      "requirement": "optional",
      "definition": "Visual band, not an instrumented performance rating.",
      "definitionZh": "目测区间，不是仪器性能评级。",
      "allowedValuesOrNote": "none|under_25pct|25_to_50pct|51_to_75pct|over_75pct|unknown"
    },
    {
      "field": "drainage_outlet_condition",
      "type": "enum",
      "requirement": "optional",
      "definition": "Visible outlet condition from a safe accessible position.",
      "definitionZh": "从安全可达位置观察到的出口状况。",
      "allowedValuesOrNote": "clear|partly_obstructed|obstructed|not_visible|not_applicable"
    },
    {
      "field": "ponding_observed",
      "type": "enum",
      "requirement": "optional",
      "definition": "Visible standing water after safe access is available.",
      "definitionZh": "在可安全接近后观察到的积水。",
      "allowedValuesOrNote": "yes|no|unknown|not_applicable"
    },
    {
      "field": "overflow_or_unintended_discharge",
      "type": "enum",
      "requirement": "optional",
      "definition": "Visible overflow or discharge outside the intended path.",
      "definitionZh": "可见溢流或非预期排放。",
      "allowedValuesOrNote": "yes|no|unknown|not_applicable"
    },
    {
      "field": "visible_movement_or_damage",
      "type": "enum",
      "requirement": "required",
      "definition": "Visible deformation, looseness, cracking or damage; not a diagnosis.",
      "definitionZh": "可见变形、松动、裂缝或损伤；不构成诊断。",
      "allowedValuesOrNote": "none_seen|possible_issue|clear_issue|unknown"
    },
    {
      "field": "controls_operational_state",
      "type": "enum",
      "requirement": "optional",
      "definition": "Observed control state without dismantling equipment.",
      "definitionZh": "不拆卸设备情况下观察到的控制状态。",
      "allowedValuesOrNote": "normal|fault_indicated|not_operated|not_applicable|unknown"
    },
    {
      "field": "safety_stop_triggered",
      "type": "enum",
      "requirement": "required",
      "definition": "Whether observation stopped because a hazard or unsafe access was identified.",
      "definitionZh": "是否因发现危险或不安全通道而停止观察。",
      "allowedValuesOrNote": "yes|no"
    },
    {
      "field": "photo_reference",
      "type": "text",
      "requirement": "optional",
      "definition": "Local or repository reference, not an embedded image.",
      "definitionZh": "本地或资料库引用，不嵌入图像。",
      "allowedValuesOrNote": "Remove faces, addresses and identifying metadata."
    },
    {
      "field": "document_reference",
      "type": "text",
      "requirement": "optional",
      "definition": "Reference to a permissioned drawing, manual, authority record or report.",
      "definitionZh": "对获许可图纸、手册、主管部门记录或报告的引用。",
      "allowedValuesOrNote": "Do not upload copyrighted or confidential documents."
    },
    {
      "field": "observation_notes",
      "type": "text",
      "requirement": "required",
      "definition": "Plain-language observations separated from interpretation.",
      "definitionZh": "用普通语言记录观察，并与解释分开。",
      "allowedValuesOrNote": "State what was visible and what was not checked."
    },
    {
      "field": "limitations",
      "type": "text",
      "requirement": "required",
      "definition": "Access, visibility, weather, documentation and competence limits.",
      "definitionZh": "通道、可见性、天气、文件及能力限制。",
      "allowedValuesOrNote": "Never leave this blank."
    },
    {
      "field": "follow_up_required",
      "type": "enum",
      "requirement": "required",
      "definition": "Whether authority, manufacturer or qualified professional follow-up is needed.",
      "definitionZh": "是否需要主管部门、制造商或合格专业人员跟进。",
      "allowedValuesOrNote": "yes|no|unknown"
    },
    {
      "field": "follow_up_route",
      "type": "text",
      "requirement": "optional",
      "definition": "Named type of follow-up, without inventing a responsible person.",
      "definitionZh": "跟进类型，不虚构责任人。",
      "allowedValuesOrNote": "authority|manufacturer|engineer|fire_professional|accessibility_specialist|maintenance|other"
    }
  ]
}