# Open Visual Symptom Standard (OVS) — Specification v1.0

**Namespace:** `https://openvisual.org/schema/`  
**Status:** Draft  
**Authors:** Péter Szigeti (Entropy Vector Group S.R.L.), Dr. László Bakó Ph.D. (Sapientia Hungarian University of Transylvania)

---

## 1. Purpose

OVS is an open schema standard for describing human visual and auditory perception symptoms in structured, machine-readable form. It covers the subjective symptom experience — not the diagnosis. A patient with glaucoma, Visual Snow Syndrome, or migraine aura all have structured visual experiences that currently have no standard machine-readable representation.

The primary bottleneck in visual perception research is the translation of complex internal sensory experiences into quantifiable, comparable metrics. When patients are limited to describing their symptoms as "like TV static" or "flickering dots," researchers lack the psychophysical precision needed to correlate those experiences with specific neural mechanisms. A patient's description of "severe trailing" in one study cannot be reliably compared to "severe trailing" in another. Data cannot be pooled. Treatments cannot be compared across centres.

OVS fills this gap. It is:
- **Condition-agnostic** — describes symptoms, not diagnoses
- **Composable** — base schemas extended by condition-specific child schemas
- **Profile-based** — conditions declare which symptom types apply via named profiles
- **Interoperable** — maps to Open mHealth and future research standards
- **Implementation-neutral** — usable by any app, clinic, or research platform

The primary reference implementation is the **Visual Snow Simulator** (https://visualsnow.pages.dev), which uses OVS to generate the world's first structured digital phenotype for Visual Snow Syndrome.

---

## 2. Design Principles

1. **Describe experience, not diagnosis.** A scotoma is a scotoma whether caused by AMD, glaucoma, or migraine.
2. **Base + extension inheritance.** Every symptom type extends a common base schema. Condition-specific params are added in child schemas.
3. **Severity always normalized 0–1.** Enables cross-condition comparison and aggregation.
4. **Physical units on physical quantities.** Frequency in Hz, duration in seconds, angle in degrees. Scores are dimensionless 0–1.
5. **Profiles, not forks.** A condition profile (e.g. VSS, glaucoma) is a declared subset of OVS symptom types — not a separate schema.
6. **omH compatibility.** Every OVS data point can be wrapped in an omH data point header for research platform interoperability.

---

## 3. Schema Hierarchy

```
ovs:symptom-base                    ← root: every symptom inherits this
│
├── ovs:visual-noise                ← any persistent background visual noise
│   └── ovs:vss-snow                ← VSS-specific: grain size, pattern, color mode
│
├── ovs:field-defect                ← any reduction or loss of visual field
│   ├── ovs:scotoma                 ← localized blind/dark spots
│   ├── ovs:hemianopia              ← half-field loss (left/right/bitemporal)
│   └── ovs:tunnel-vision           ← peripheral field constriction
│
├── ovs:optical-aberration          ← light-path distortions in the optical system
│   ├── ovs:glare                   ← starburst/glare around light sources
│   ├── ovs:halo                    ← ring artifacts around lights
│   └── ovs:contrast-loss           ← reduced contrast / hazy vision
│
├── ovs:persistence                 ← image that outlasts its stimulus
│   ├── ovs:palinopsia              ← afterimages and motion trails
│   └── ovs:photopsia               ← spontaneous light flashes
│
├── ovs:hallucination               ← perception with no external stimulus
│   ├── ovs:charles-bonnet          ← geometric / structured hallucinations
│   └── ovs:migraine-aura           ← cortical spreading depression patterns
│
├── ovs:spatial-distortion          ← warping of perceived spatial geometry
│   ├── ovs:diplopia                ← double vision / image offset
│   ├── ovs:metamorphopsia          ← wavy / warped lines
│   └── ovs:oscillopsia             ← perceived environmental motion/vibration
│
├── ovs:entoptic                    ← perception of structures within the eye itself
│   ├── ovs:floaters                ← vitreous debris (PVD, myopia)
│   └── ovs:blue-field-entoptic     ← Scheerer phenomenon (leukocytes in retinal vessels)
│
├── ovs:color-perception            ← altered color discrimination
│   └── ovs:cvd                     ← color vision deficiency (congenital or acquired)
│
└── ovs:auditory                    ← auditory symptom (comorbid with visual conditions)
    └── ovs:tinnitus                ← phantom auditory perception
```

---

## 4. Base Schema — `ovs:symptom-base`

Every OVS symptom object MUST include these fields.

| Field | Type | Required | Description |
|---|---|---|---|
| `ovs_type` | string | yes | Schema type identifier, e.g. `"ovs:scotoma"` |
| `ovs_version` | string | yes | Schema version, e.g. `"1.0"` |
| `severity` | number 0–1 | yes | Normalized severity. 0 = absent, 1 = maximum |
| `enabled` | boolean | yes | Whether this symptom is active |
| `effective_time_frame` | object | yes | When this observation was made (see §5) |

---

## 5. Time Frame

All OVS observations use ISO 8601 UTC timestamps.

```json
{
  "effective_time_frame": {
    "date_time": "2026-05-30T12:00:00Z"
  }
}
```

For interval observations (e.g. a session lasting 10 minutes):

```json
{
  "effective_time_frame": {
    "time_interval": {
      "start_date_time": "2026-05-30T12:00:00Z",
      "end_date_time":   "2026-05-30T12:10:00Z"
    }
  }
}
```

---

## 6. Symptom Schemas

### 6.1 `ovs:visual-noise`

Base for any persistent background visual disturbance overlaying the visual field.

**Extends:** `ovs:symptom-base`

| Field | Type | Unit | Description |
|---|---|---|---|
| `alpha` | number 0–1 | score | Opacity of the noise layer |
| `speed` | number 0–1 | score | Animation velocity |

#### 6.1.1 `ovs:vss-snow` *(extends `ovs:visual-noise`)*

VSS-specific visual static — the defining symptom of Visual Snow Syndrome.

| Field | Type | Unit | Description |
|---|---|---|---|
| `grain_size` | number 0–1 | score | Individual grain pixel size |
| `pattern` | string | enum | `"random"` \| `"perlin"` |
| `color_mode` | string | enum | `"white"` \| `"color"` |
| `color_rgba` | string | css color | Snow tint when color_mode is `"color"` |

---

### 6.2 `ovs:field-defect`

Base for any reduction or loss of the visual field.

**Extends:** `ovs:symptom-base`

| Field | Type | Unit | Description |
|---|---|---|---|
| `opacity` | number 0–1 | score | Density of the field loss (1 = complete blackout) |

#### 6.2.1 `ovs:scotoma` *(extends `ovs:field-defect`)*

Localized area of reduced or absent vision.

| Field | Type | Unit | Description |
|---|---|---|---|
| `count` | integer ≥1 | count | Number of simultaneous scotomas |
| `positions` | array of `{x, y}` | normalized 0–1 | Center positions in visual field |
| `color_rgba` | string | css color | Fill color (typically black) |

#### 6.2.2 `ovs:hemianopia` *(extends `ovs:field-defect`)*

Loss of half the visual field.

| Field | Type | Unit | Description |
|---|---|---|---|
| `side` | string | enum | `"left"` \| `"right"` \| `"bitemporal"` |

#### 6.2.3 `ovs:tunnel-vision` *(extends `ovs:field-defect`)*

Peripheral field constriction.

| Field | Type | Unit | Description |
|---|---|---|---|
| `radius` | number 0–1 | score | Remaining central field radius (1 = full field) |
| `softness` | number 0–1 | score | Edge feathering |

---

### 6.3 `ovs:optical-aberration`

Base for light-path distortions in the eye's optical system.

**Extends:** `ovs:symptom-base`

#### 6.3.1 `ovs:glare` *(extends `ovs:optical-aberration`)*

Starburst or glare around light sources.

| Field | Type | Unit | Description |
|---|---|---|---|
| `ray_count` | integer | count | Number of starburst rays |
| `size_fraction` | number 0–1 | score | Glare radius relative to screen |
| `color_rgba` | string | css color | Glare tint |

#### 6.3.2 `ovs:halo` *(extends `ovs:optical-aberration`)*

Ring artifacts around light sources.

| Field | Type | Unit | Description |
|---|---|---|---|
| `rainbow` | boolean | — | Whether halo shows spectral colors |
| `near_ring` | boolean | — | Secondary near-field ring visible |

#### 6.3.3 `ovs:contrast-loss` *(extends `ovs:optical-aberration`)*

Reduced contrast sensitivity / hazy vision.

| Field | Type | Unit | Description |
|---|---|---|---|
| `strength` | number 0–1 | score | Degree of contrast reduction |

---

### 6.4 `ovs:persistence`

Base for images that outlast their stimulus.

**Extends:** `ovs:symptom-base`

#### 6.4.1 `ovs:palinopsia` *(extends `ovs:persistence`)*

Trailing or ghost afterimages of moving or stationary objects.

| Field | Type | Unit | Description |
|---|---|---|---|
| `subtype` | string | enum | `"illusory"` \| `"hallucinatory"` |
| `trail_layers` | integer | count | Number of ghost trail copies |
| `trail_alpha` | number 0–1 | score | Trail opacity |
| `trail_fade_rate` | number 0–1 | score | Exponential decay per frame |
| `ghost_count` | integer | count | Number of persistent ghost copies |
| `ghost_alpha` | number 0–1 | score | Ghost opacity |
| `ghost_life_sec` | number | s | Ghost lifetime in seconds |

#### 6.4.2 `ovs:photopsia` *(extends `ovs:persistence`)*

Spontaneous flashes of light with no external source.

*(No additional fields beyond base — severity captures flash frequency/intensity.)*

---

### 6.5 `ovs:hallucination`

Base for structured perceptions with no external stimulus.

**Extends:** `ovs:symptom-base`

#### 6.5.1 `ovs:charles-bonnet` *(extends `ovs:hallucination`)*

Geometric or structured hallucinations in visually impaired patients.

*(No additional fields beyond base — severity captures vividness/frequency.)*

#### 6.5.2 `ovs:migraine-aura` *(extends `ovs:hallucination`)*

Cortical spreading depression visual patterns.

| Field | Type | Unit | Description |
|---|---|---|---|
| `subtype` | string | enum | `"scotoma"` \| `"fortification"` |
| `duration_sec` | number | s | Typical aura episode duration |

---

### 6.6 `ovs:spatial-distortion`

Base for warping of perceived spatial geometry.

**Extends:** `ovs:symptom-base`

#### 6.6.1 `ovs:diplopia` *(extends `ovs:spatial-distortion`)*

Double vision — perception of two offset images.

| Field | Type | Unit | Description |
|---|---|---|---|
| `direction_deg` | number | deg | Offset angle of the duplicate image |
| `rotation_deg` | number | deg | Rotation of the duplicate |

#### 6.6.2 `ovs:metamorphopsia` *(extends `ovs:spatial-distortion`)*

Straight lines appearing curved or wavy (characteristic of macular disease).

| Field | Type | Unit | Description |
|---|---|---|---|
| `wave_speed` | number | score | Speed of the warp animation |

#### 6.6.3 `ovs:oscillopsia` *(extends `ovs:spatial-distortion`)*

Perceived environmental vibration or shaking (vestibular-related).

*(No additional fields beyond base.)*

---

### 6.7 `ovs:entoptic`

Base for perception of structures within the eye itself.

**Extends:** `ovs:symptom-base`

#### 6.7.1 `ovs:floaters` *(extends `ovs:entoptic`)*

Vitreous debris perceived as moving shapes. Common in PVD, myopia, VSS.

| Field | Type | Unit | Description |
|---|---|---|---|
| `count` | integer | count | Number of floater particles |
| `min_size` | number 0–1 | score | Minimum floater size |
| `max_size` | number 0–1 | score | Maximum floater size |
| `shape` | string | enum | `"circle"` \| `"worm"` \| `"cluster"` |
| `brownian_strength` | number 0–1 | score | Random drift intensity |

#### 6.7.2 `ovs:blue-field-entoptic` *(extends `ovs:entoptic`)*

Scheerer phenomenon — perception of leukocytes moving through retinal capillaries.

| Field | Type | Unit | Description |
|---|---|---|---|
| `count` | integer | count | Number of perceived dots |
| `movement` | string | enum | `"squiggly"` \| `"flow"` |
| `dot_size` | number 0–1 | score | Perceived dot size |

---

### 6.8 `ovs:color-perception`

Base for altered color discrimination.

**Extends:** `ovs:symptom-base`

#### 6.8.1 `ovs:cvd` *(extends `ovs:color-perception`)*

Color vision deficiency — congenital or acquired.

| Field | Type | Unit | Description |
|---|---|---|---|
| `subtype` | string | enum | `"protanopia"` \| `"deuteranopia"` \| `"tritanopia"` \| `"achromatopsia"` |

---

### 6.9 `ovs:auditory`

Base for auditory symptoms. Included because tinnitus is a comorbid symptom of VSS and several retinal/neurological conditions.

**Extends:** `ovs:symptom-base`

#### 6.9.1 `ovs:tinnitus` *(extends `ovs:auditory`)*

Phantom auditory perception.

| Field | Type | Unit | Description |
|---|---|---|---|
| `subtype` | string | enum | `"pure_tone"` \| `"buzz"` \| `"pulsatile"` |
| `base_frequency` | number | Hz | Dominant perceived frequency |
| `volume` | number 0–1 | score | Perceived loudness |
| `fm_depth` | number | Hz | Frequency modulation depth |
| `pulse_rate` | number | Hz | Pulse/beat rate for pulsatile type |

---

## 7. Condition Profiles

A **profile** is a named, versioned set of OVS symptom types relevant to a specific condition. Profiles do not change the schema — they declare which symptom types are expected, which are primary, and which are optional comorbidities.

### 7.1 VSS Profile (`ovs-profile:vss`)

Visual Snow Syndrome — a neurological condition causing persistent visual disturbances.

**Primary symptoms (always present in VSS):**
- `ovs:vss-snow` — the defining symptom
- `ovs:blue-field-entoptic` — almost universal in VSS
- `ovs:photopsia` — common

**Common comorbidities (present in many VSS patients):**
- `ovs:palinopsia`
- `ovs:floaters`
- `ovs:tinnitus`
- `ovs:glare`
- `ovs:halo`

**Occasional (subset of VSS patients):**
- `ovs:diplopia`
- `ovs:oscillopsia`
- `ovs:migraine-aura`

### 7.2 Glaucoma Profile (`ovs-profile:glaucoma`)

**Primary:**
- `ovs:tunnel-vision`
- `ovs:contrast-loss`

**Common:**
- `ovs:scotoma`
- `ovs:glare`

### 7.3 AMD Profile (`ovs-profile:amd`)

**Primary:**
- `ovs:scotoma` (central)
- `ovs:metamorphopsia`

**Common:**
- `ovs:contrast-loss`
- `ovs:charles-bonnet`

### 7.4 Migraine Profile (`ovs-profile:migraine`)

**Primary:**
- `ovs:migraine-aura`
- `ovs:photopsia`

**Common:**
- `ovs:oscillopsia`
- `ovs:tinnitus`

### 7.5 Cataract Profile (`ovs-profile:cataract`)

**Primary:**
- `ovs:glare`
- `ovs:halo`
- `ovs:contrast-loss`

### 7.6 PVD Profile (`ovs-profile:pvd`)

**Primary:**
- `ovs:floaters`
- `ovs:photopsia`

---

## 8. OVS Session Document

A complete OVS session document captures one patient observation session.

```json
{
  "ovs_version": "1.0",
  "session_id": "uuid-v4",
  "recorded_at": "2026-05-30T12:00:00Z",
  "profile": "ovs-profile:vss",
  "subject_id": "VS-3A7F21",
  "symptoms": [
    {
      "ovs_type": "ovs:vss-snow",
      "ovs_version": "1.0",
      "enabled": true,
      "severity": 0.72,
      "grain_size": 0.4,
      "speed": 0.3,
      "alpha": 0.6,
      "pattern": "random",
      "color_mode": "white",
      "effective_time_frame": { "date_time": "2026-05-30T12:00:00Z" }
    },
    {
      "ovs_type": "ovs:tinnitus",
      "ovs_version": "1.0",
      "enabled": true,
      "severity": 0.45,
      "subtype": "pure_tone",
      "base_frequency": 4000,
      "volume": 0.3,
      "fm_depth": 200,
      "pulse_rate": 2.0,
      "effective_time_frame": { "date_time": "2026-05-30T12:00:00Z" }
    }
  ],
  "wellbeing": {
    "anxiety":    { "value": 6, "scale": 10 },
    "energy":     { "value": 4, "scale": 10 },
    "depression": { "value": 3, "scale": 10 },
    "stress":     { "value": 5, "scale": 10 },
    "sleep_hours": 6.5,
    "note": "Bad day, screen time triggered snow."
  }
}
```

---

## 9. Relationship to Open mHealth

OVS is not a replacement for omH — it is a domain-specific standard that maps to omH for research platform interoperability.

| OVS | omH equivalent |
|---|---|
| `ovs:tinnitus.base_frequency` | `{ value: 4000, unit: "Hz" }` |
| `ovs:tinnitus.volume` | `{ value: 0.3, unit: "score" }` |
| session `recorded_at` | omH `effective_time_frame` |
| `subject_id` | omH `user_id` in header |
| `ovs:vss-snow` | custom omH schema (no existing equivalent) |

The OVS → omH converter maps each `symptoms[]` entry to one omH data point, with the OVS schema type used as the omH `schema_id.name`.

---

## 10. Relationship to VSS Simulator Export (v6)

The VSS Simulator app export format (documented in `vss_export_schema_v6.json`) is an **implementation** of OVS. The mapping is:

| VSS Export field | OVS schema type |
|---|---|
| `visualStatic` | `ovs:vss-snow` |
| `floaters` | `ovs:floaters` |
| `blueField` | `ovs:blue-field-entoptic` |
| `lightAnomalies.aura` | `ovs:migraine-aura` or `ovs:scotoma` |
| `lightAnomalies.photopsia` | `ovs:photopsia` |
| `lightAnomalies.glare` | `ovs:glare` |
| `lightAnomalies.halo` | `ovs:halo` |
| `lightAnomalies.contrastLoss` | `ovs:contrast-loss` |
| `lightAnomalies.cvd` | `ovs:cvd` |
| `lightAnomalies.hemianopia` | `ovs:hemianopia` |
| `lightAnomalies.tunnelVision` | `ovs:tunnel-vision` |
| `lightAnomalies.charlesBonnet` | `ovs:charles-bonnet` |
| `distortions.vibration` | `ovs:oscillopsia` |
| `distortions.diplopia` | `ovs:diplopia` |
| `distortions.palinopsia` | `ovs:palinopsia` |
| `distortions.wavyVision` | `ovs:metamorphopsia` |
| `tinnitus` | `ovs:tinnitus` |
| `wellbeing` | OVS session `wellbeing` block |

The app export format uses camelCase and ARGB integers for implementation reasons (Kotlin/Android conventions). The OVS canonical format uses snake_case and CSS colors, following web standards.

---

## 11. Versioning

OVS schemas are versioned independently. The root namespace is `https://openvisual.org/schema/`. Each schema type has its own version:

- `ovs:symptom-base@1.0`
- `ovs:vss-snow@1.0`
- `ovs:tinnitus@1.0`
- etc.

A document declares the versions it uses per symptom entry via `ovs_version`.

---

## 12. Neurophysiological Rationale

The OVS schema design reflects known or hypothesised neural substrates of visual perception disorders. This section provides clinical context for why symptom parameters are separated into independent domains rather than collapsed into a single severity score.

### 12.1 Why parameter separation matters

Distinct visual parameters likely map to distinct neural substrates:

- **Visual static temporal frequency** (ST-04 speed) may correlate with localised disinhibition in primary visual cortex (V1), reflecting cortical hyperexcitability — the leading mechanistic hypothesis for VSS (Schankin et al., 2014; Eren et al., 2020)
- **Palinopsia** (DS-05–17) likely reflects processing anomalies in MT/V5 motion areas and higher visual association cortex, distinct from static generators
- **Blue field entoptic** (BF-01–08) is retinal in origin — tracking it separately from cortically-generated static is essential for distinguishing peripheral from central contributions
- **Tinnitus** (TI-01–06) comorbidity with VSS (~80% of patients) implicates broad thalamocortical networks and cross-sensory gating deficits, not isolated visual cortex pathology
- **Oscillopsia** (DS-01) has vestibular and cerebellar involvement distinct from visual cortex hyperexcitability

### 12.2 EEG correlation targets

OVS session documents, when paired with EEG recordings, enable:

1. **Psychophysical baseline establishment** — a patient tunes the simulator until it matches their internal percept; the resulting OVS parameters provide a numerical representation of their subjective state
2. **SSVEP targeting** — OVS ST-04 (visual static speed) can generate precisely calibrated Steady-State Visually Evoked Potential stimuli matched to an individual's symptom profile
3. **Longitudinal state correlation** — OVS severity fields (0–1 normalized) enable direct correlation with EEG band power over time
4. **Alpha/gamma ratio** — the hyperexcitability indicator (alpha suppression + gamma elevation) predicted by thalamocortical dysrhythmia theory can be directly correlated with ST-01 (static intensity) and TI-03 (tinnitus volume)

### 12.3 Neuro-phenotype clustering

High-resolution OVS parameter vectors enable machine learning approaches to VSS subtype identification. Hypothesised phenotypes based on existing literature:

- **Phenotype A** — high ST-04 (fast static) + elevated TI-02 (high-frequency tinnitus) + sleep-linked exacerbation → cortical hyperexcitability subtype
- **Phenotype B** — dominant DS-05 (palinopsia) + low ST-01 (mild static) + vascular history → motion-processing / higher visual area subtype  
- **Phenotype C** — prominent BF-02 (high entoptic count) + DS-01 (oscillopsia) + anxiety correlation → thalamocortical network / arousal subtype

These phenotypes cannot be identified without the parameter granularity OVS provides.

---

## 13. Standardisation Pathway

OVS is structured to ISO/IEC drafting conventions to facilitate a future formal standardisation pathway if clinical adoption warrants it. The parameter codes (ST-01, FL-02, etc.) are stable, language-neutral citation labels designed to remain valid across schema versions and implementation changes.

A formal ISO standard for "Digital Simulation and Quantification of Visual Perception Disturbances" would provide medical device manufacturers, researchers, and software developers with a unified specification. OVS 1.0 is the candidate input to such a process.

At this stage, OVS is an open community standard — adoption is voluntary, conformance is self-declared, and there is no certification process. Partial implementation is supported: a system may implement a subset of symptom domains as long as it declares which domains are covered.

---

## 14. License

OVS schemas and specification are published under the **Creative Commons Attribution 4.0 International (CC BY 4.0)** license. Reference implementations (converter, validator) are MIT licensed.

## 15. References

- Schankin CJ, et al. (2014). Persistent positive visual phenomenon in migraine. *Cephalalgia*.
- Eren O, et al. (2020). Visual Snow Syndrome: Contribution to the Understanding of Brain Connectivity. *Frontiers in Neurology*.
- Kondziella D, et al. (2020). Prevalence of visual snow syndrome in the UK. *European Journal of Neurology*.
- Open mHealth Schema Design Principles. https://www.openmhealth.org/documentation/