# Open Lyric Alignment JSON representation 0.1

## 1. Media type and encoding

The provisional media type is `application/ola+json`. Standalone files SHOULD
use the suffix `.ola.json`.

An OLA JSON 0.1 document MUST be one RFC 8259 object encoded as strict UTF-8
without a byte-order mark. Comments, trailing commas, invalid UTF-8, and
duplicate object member names are forbidden. String values are preserved
exactly; a parser MUST NOT trim, case-fold, or normalize lyric text.

The JSON Schema is
[`schema/ola-0.1.schema.json`](schema/ola-0.1.schema.json).

## 2. Property and enum naming

Property names use lower camel case exactly as shown in the model, for example
`documentId`, `defaultLanguage`, `isPrimary`, `separatorAfter`,
`timelineMappings`, `resolvedRange`, and `noteLinkIds`.

Enum values are lower kebab case:

- line breaks: `none`, `line`, `paragraph`;
- word positions: `single`, `begin`, `middle`, `end`;
- origins: `automatic`, `manual`, `imported`;
- review states: `unreviewed`, `accepted`, `needs-review`, `rejected`;
- anchor edges: `start`, `end`; and
- anchor strengths: `advisory`, `hard`.

Integer enum values are forbidden.

## 3. Canonical 64-bit integers

Every signed 64-bit OLA value is a canonical decimal JSON string, including:

- document `revision`;
- note event indexes, ordinals, ticks, and durations;
- note-context delta ticks;
- positions in ranges, anchors, boundaries, and mappings; and
- signed anchor offsets.

Canonical forms contain no leading plus, leading zero, decimal point, exponent,
or surrounding whitespace. Valid examples are `"0"`, `"2530"`, and
`"-8000"`. `"01"`, `"+1"`, and the JSON number `1` are invalid.

Values must fit a signed 64-bit integer. Positions, revisions, note indexes,
ticks, ordinals, occurrences, and durations are additionally non-negative.
Signed offsets and note-context deltas may be negative.

Ordinary 32-bit fields such as track index, MIDI channel, pitch,
ticks-per-quarter-note, sample rate, and same-location occurrence are JSON
numbers.

## 4. Canonical object shape

The reference serializer writes all non-null model properties. Empty arrays,
empty maps, `false`, zero-valued enums, and zero-valued numbers are retained.
Nullable properties are omitted when null.

The top-level serialized members are:

```text
format, version, documentId, revision, defaultLanguage?, voices, lanes,
targets, alignmentSets, timelineMappings, provenance, extensions
```

The exact header values are:

```json
{
  "format": "open-lyric-alignment",
  "version": "0.1"
}
```

The JSON Schema requires the canonical collections even when they are empty.
The only collection that must be non-empty semantically is `lanes`; every lane
also has at least one line and every line at least one cue.

## 5. Additive properties and extensions

Every model object may carry unknown additive properties. A decoder preserves
them at that object's JSON level; there is no literal `additionalProperties`
member. Unknown additive values are optional forward data and MUST NOT override
the meaning of defined 0.1 fields.

The top-level `extensions` object is distinct. Each key is an absolute URI and
each value is arbitrary JSON. It is the namespace for deliberate optional
capabilities. Unknown extensions are ignored semantically and preserved when
possible.

## 6. References and semantic validation

JSON Schema validates representation shape but cannot establish every semantic
rule. A semantic validator also checks:

- global ID uniqueness and reference resolution;
- cue and boundary ownership by the alignment set lane;
- local note-link references;
- target unit agreement and range ordering;
- mapping point requirements;
- anchor evidence;
- MIME-independent text and token restrictions; and
- binding-specific hash and locator rules.

The fixtures distinguish schema-invalid documents from documents that are
structurally valid JSON but semantically invalid.

## 7. Version behavior

An OLA JSON 0.1 reader checks `format` and `version` before using the document as
an authority. A different format or unsupported version is rejected, not
guessed. A container may retain its bytes opaquely and use an independent
fallback.

Unknown additive properties and optional URI-namespaced extensions in an exact
0.1 document are preserved and ignored. They cannot introduce semantics that a
0.1 reader is required to understand. A future version that requires a new
capability must define an explicit required-capability negotiation rule.

## 8. Hashes and JSON bytes

OLA JSON 0.1 does not require canonical property order or whitespace. Semantic
equality is independent of serialization. A binding that hashes JSON bytes
hashes the exact strict UTF-8 bytes it carries.

Changing whitespace or property order therefore changes the payload hash and
requires a new transport envelope. It does not require a semantic revision when
all model values remain unchanged.

## 9. Reference resource limits

The reference codec enforces:

| Resource | Limit |
|---|---:|
| JSON bytes | 4 MiB |
| JSON depth | 64 |
| ID characters | 128 |
| Short text characters | 1,024 |
| Cue text characters | 16,384 |
| Voices / lanes | 256 each |
| Lines | 16,384 |
| Cues / placements / boundaries | 65,536 each |
| Targets / timeline mappings | 64 each |
| Alignment sets | 256 |
| Note links | 131,072 |
| Context notes per link | 32 |
| Anchors per placement | 64 |
| Timeline points | 65,536 |
| Provenance entries | 1,024 |
| References per entity | 1,024 |
| Top-level extensions | 256 |
| Additive properties per object | 128 |

Implementations may apply lower operational limits only when they fail visibly
without silently discarding data. In SMF, an unavailable OLA document falls
back to standard lyrics.

Checksums detect accidental corruption and stale bindings. They are not digital
signatures or proof of authorship.