Use the packaged schemas as the authoritative record shape. This site includes dated mirrors for inspection and tool integration; it does not maintain a separate competing schema definition.

## Schema downloads

Schemas use JSON Schema 2020-12 and record schema identifier `comuvia/0.1`. The common definitions file is needed to resolve the schemas' shared URN references. The ZIP retains the complete schema set; a generic validator must register those schema identifiers or use an appropriate resolver.

- [Download all schema files](/sdk/resources/downloads/comuvia-schemas-v0_1.zip)
- [Schema file identities and origin](/sdk/resources/schemas/manifest.json)
- [Common definitions](/sdk/resources/schemas/common.json)

| Source records | Prediction and evaluation records |
|---|---|
| [Resource snapshot](/sdk/resources/schemas/resource_snapshot.json) | [Question](/sdk/resources/schemas/question.json) |
| [Source assertion](/sdk/resources/schemas/source_assertion.json) | [Forecast](/sdk/resources/schemas/forecast.json) |
| [Interpretation](/sdk/resources/schemas/interpretation.json) | [Outcome](/sdk/resources/schemas/outcome.json) |
| [Assessment](/sdk/resources/schemas/assessment.json) | [Evaluation](/sdk/resources/schemas/evaluation.json) |
| [Artifact descriptor](/sdk/resources/schemas/artifact_descriptor.json) | |

For executable validation use the library, which checks semantic constraints as well as record structure. A generic JSON Schema validator alone is not a replacement for SDK eligibility, identity or reference checks.

## Strict parsing and named refusals

```python
import comuvia

try:
    comuvia.parse_json(b'{"p":0.7,"p":0.3}')
except comuvia.RefusalError as error:
    print(sorted(error.codes))
    for issue in error.issues:
        print(issue.pointer, issue.code, issue.message)
# ['duplicate_member']
```

`Issue.pointer` uses JSON Pointer. `validate(record)` returns a list of issues; `load_record` parses and validates, raising `RefusalError` on refusal. Ordinary I/O or type errors can still occur. Do not assume every exception is a schema refusal.

## Troubleshooting by layer

| Layer | Symptom | Appropriate action |
|---|---|---|
| Parsing | Duplicate JSON members or nonfinite numbers | Repair the producer; retain the rejected input for diagnosis when permitted |
| Schema | Required field or type issue | Consult the exact schema and issue pointer; never fabricate missing evidence |
| Identity | Expected digest differs | Compare original bytes/canonical body and handoff; do not update the expected digest just to pass |
| Store | Same revision has different content | Append a properly linked successor revision |
| Store | Writer lock unavailable | Close the other writer; avoid a second concurrent writer |
| Evaluation | `no_declared_probability` | Preserve as narrative/coverage; extraction confidence is not a substitute |
| Evaluation | `missing_required_time` or `incomplete_question` | Obtain genuine declared metadata or retain the exclusion |
| Evaluation | `conditional_scenario` | Keep as an experiment with assumptions |
| Intake | `replay_not_accepted` | Expected for synthetic replay; inspect the retained snapshot without calling it live |
| Reproduction | Mismatch or unavailable | Preserve saved evaluation and investigate pinned records/rule |

## CLI exit codes

| Code | Meaning |
|---:|---|
| 0 | Successful operation, which can include named exclusions |
| 1 | Refusal or mismatch |
| 2 | Usage error |

Use `comuvia --json ...` for structured output, but note that human text and CLI JSON layouts remain provisional in this alpha. Stable schema and reason-code promises are narrower than a fully frozen CLI presentation contract.

## Schema evolution

Package version, record schema version, store format and scoring-rule version are different identifiers. Pin them explicitly in a reproducible workflow. See [versions and support](/sdk/docs/project) for current stability commitments and the migration-guide placeholder.