# Scrolld Story Format 1.0

Release version: `1.0.0`

Wire schema version: `1.0`

## Purpose

SSF is a JSON format for a living data story whose visible claims remain traceable to data or an external source. A document is portable: it does not depend on Scrolld infrastructure, private APIs, or a specific renderer.

## Conformance

An SSF 1.0 document conforms when:

1. it validates against `schema/ssf-1.0.schema.json`;
2. the canonical validator returns `valid: true`;
3. every chart has non-empty inline data or a `binding_id` resolving to a declared data binding;
4. every claim trace resolves through a declared binding, valid inline-data rows, or a non-empty source;
5. all section and chart vocabulary values belong to their closed release sets; and
6. no undeclared properties are present.

The JSON Schema defines the closed structural contract. The validator adds cross-reference and row-bound checks that JSON Schema cannot express portably.

## Document

The root is a JSON object. Required members are:

- `ssf`: the wire version, exactly `"1.0"`;
- `id`: a stable non-empty document identifier;
- `title`: a non-empty title;
- `description`: a human-readable description;
- `generated_by`: provider, model or deterministic compiler identity, and ISO-8601 generation time;
- `sections`: at least one ordered section.

`schema_version`, when present, is exactly `"1.0"`. Optional document provenance, bindings, locale, theme, version, and public-safe brand fields are defined by the schema.

## Sections

The closed section vocabulary is `text`, `chart`, `stats`, `table`, `callout`, `quote`, and `cta`. Each section has a stable `id` and its type-specific required payload. CTA links, when present, use HTTPS.

Charts use one of the patterns frozen in the JSON Schema. A renderer may render a known pattern differently, but it must not silently treat an unknown pattern as a known one.

## Bindings, claims, and provenance

A data binding has a unique `binding_id` and a non-empty `source`. A chart may resolve through a binding or non-empty inline `data`.

A claim has text and a trace. A trace is resolvable when it contains at least one of:

- a `binding_id` declared by the document;
- one or more non-negative row indexes, within the chart’s inline data when the claim belongs to a chart section; or
- a non-empty external `source`.

Provenance is factual metadata, not an endorsement signal. Consumers must preserve it when transforming a document.

## Versioning

The release version follows semantic versioning. The wire version changes only for an incompatible document contract. Consumers must pin a release manifest or exact artifact hash; `latest` is not a conformance input. SSF 0.9 is an internal historical read format and is not part of this public 1.0 release.

The canonical manifest is signed with the release namespace `scrolld-ssf-release`. Consumers should verify the detached SSH signature against `release/allowed_signers` and confirm the pinned owner key independently before trusting the file hashes.

## Security

Conformance does not make embedded prose or data safe for every rendering context. Consumers must escape text, enforce URL policies, cap input size and nesting, and apply their own authorization and content-security controls. This release’s validator rejects non-HTTPS CTA targets and malformed closed shapes; it does not fetch URLs or execute content.