VLDS v1.0

Overview and Design Philosophy

VLDS specifies one lesson: the smallest unit a learner practises. A lesson is an ordered set of items. Each item pairs a cue in the language the learner already reads with the phrase to produce in the language being learned, given once per dialect the lesson teaches, plus an optional pronunciation aid and optional audio. VLDS is the content layer only. How lessons are packaged, distributed, discovered, or scheduled for review is out of scope and belongs to other layers.

Four principles decide every field:

• Language-agnostic. Nothing in the format is specific to one language or one dialect axis. Dialects are declared as data, so North and South are the Welsh pack's choices, not the format's grammar. A language with no dialect axis declares a single dialect.
• Audio-first, but degrading to text. Speaking is the point, so audio is a first-class field with its own licence, provenance, and text alternative. A missing clip is never an error; it degrades to text.
• Open and attributable by construction. Every clip and every ingested text declares an SIL- or Creative-Commons-open licence, and the attribution a downstream reuser legally needs travels with the data rather than being left to a separate file.
• Offline and independent. A lesson is a plain, self-describing JSON document. Rendering it requires no service, no account, and no runtime dependency on the Veydrin Order or anyone else.

Scope

VLDS covers the content of one lesson: its identity, the language and dialects it teaches, its items, and the text, pronunciation, and audio of each item. It is intended for beginner-to-advanced spoken-language curricula, community-authored courses, and offline apps.

VLDS does not try to be:

• A packaging or registry format. Grouping lessons into a downloadable language pack, versioning that pack, and describing a registry of packs is the job of the VODS envelope and its cymanfa.pack extension, not VLDS. A lesson references no pack; a pack references lessons.
• An assessment format. Scoring, item response theory, and test delivery are the domain of 1EdTech QTI 3.0. VLDS items are practice prompts, not scored questions.
• A learning-record or metadata format. What a learner did is xAPI / cmi5; catalogue metadata for discovery is LOM / Dublin Core. VLDS carries neither learner data nor discovery metadata.
• A scheduling algorithm. When to review an item is a spaced-repetition concern (for example FSRS), held by the consuming application, not the lesson.
• A phonology or lexical database. VLDS points at IPA and at upstream lexical records; it does not define them.

Relationship to existing standards (informative)

VLDS is a content standard whose nearest neighbours are complementary, not competitive. A lesson can be packaged for a learning-management system as Common Cartridge and integrated over LTI 1.3; practice events can be emitted as xAPI 2.0 (IEEE 9274.1.1-2023); catalogue records can be expressed in LOM or Dublin Core; scored variants can be authored in QTI 3.0. VLDS deliberately does not absorb any of these. It is the small, portable, offline unit they can each wrap.

The Lesson Object

A VLDS document is one lesson object.

No other top-level keys are permitted, except underscore-prefixed annotations.

Dialects and Voices

Dialect

A dialect is one variety of the target language the lesson teaches. The set is declared once at the top of the lesson and referenced by id in each item.

Voice

A voice is a named speaker or synthetic voice. Declaring voices lets a lesson offer the same phrase in more than one voice and lets a consumer let the learner choose.

Item and Variant

Item

An item is one thing to practise: a cue, and the target-language variant for each declared dialect.

Variant

A variant is the phrase to say in one dialect, with its pronunciation and audio.

Audio Clip

An audio clip is a single recording or synthesis of a phrase, carrying everything a lawful, accessible, honest reuse needs: the source, the licence, the attribution, a text alternative, and whether a human or a machine produced it.

Attribution

The attribution object (used by clips and by ingested text) is name (required), and optional url and title. name credits a person, pseudonym, or organization; see the privacy note in §10.

Full Example

A one-item Welsh lesson teaching North and South, in a female voice, with synthetic audio marked provisional. It validates against the VLDS v1.0 schema. lang_map values are maps of BCP 47 tag to an NFC string; the open-licence enum is the SPDX allow-list (CC0 and the CC-BY / CC-BY-SA versions only, never NonCommercial or NoDerivatives).

{
  "vlds_version": "1.0",
  "id": "seed-01",
  "language": "cy",
  "title": { "en": "Greetings and small talk", "cy": "Cyfarch a sgwrsio" },
  "dialects": [
    { "id": "north", "tag": "cy-x-north", "label": { "en": "North", "cy": "Gogledd" } },
    { "id": "south", "tag": "cy-x-south", "label": { "en": "South", "cy": "De" } }
  ],
  "voices": [ { "id": "female", "gender": "female" } ],
  "items": [
    {
      "id": "bore-da",
      "cue": { "en": "good morning" },
      "register": "colloquial",
      "shared": {
        "text": "bore da",
        "pronunciation": { "respell": "BOR-eh dah", "ipa": "/ˈbɔrɛ daː/" },
        "audio": {
          "female": {
            "src": "lessons/audio/seed-01/bore-da-female.mp3",
            "license": "CC0-1.0",
            "source_type": "synthetic",
            "generated_by": "piper cy_north 1.0",
            "provisional": true
          }
        }
      }
    }
  ]
}

Here bore da is identical in both dialects, so a single shared variant covers north and south rather than repeating them under targets. An item whose wording differs by dialect gives one entry per dialect id under targets instead.

Extension Mechanism

VLDS is deliberately closed: no undeclared keys are allowed anywhere, so a typo is an error rather than silently ignored data. The one escape is annotation. Any object MAY carry keys whose names begin with an underscore (_). These are private annotations, not part of the wire format.

• A conforming consumer MUST ignore any underscore-prefixed key it does not recognise, and MUST NOT let its presence or absence change how the lesson is interpreted.
• Annotations carry no interoperability guarantee. Two producers MAY use the same _note for different purposes; a consumer MUST NOT rely on an annotation authored by a different producer.
• Meaning that must be interoperable does not belong in an annotation. It belongs in a MINOR version of this specification (§9), proposed through the revision procedure, so it is typed and governed rather than ad hoc.

Versioning and Compatibility

The version is vlds_version, a MAJOR.MINOR string. v1.0 is the first release.

• MINOR bumps add optional fields or relax a constraint in a way that every prior conforming document still validates. A consumer MUST accept any document whose MAJOR it recognises, ignoring fields introduced by a MINOR it does not know. Evolution is additive-forever within a MAJOR: a MINOR revision MUST NOT break a conforming implementation of an earlier MINOR.
• MAJOR bumps are reserved for a change that cannot be made additively. A MAJOR revision is a new schema at a new $id; it does not retroactively invalidate v1 documents.
• The wire keys are frozen for the 1.x line. New capability arrives as new optional keys, never by repurposing or renaming an existing one.

Security and Privacy Considerations

Untrusted content

A lesson is data from a potentially untrusted author, especially a community-contributed or downloaded one. A consumer MUST treat every string (text, cue, transcript, labels, notes) as untrusted input and MUST NOT render it as markup or evaluate it. src and source are author-supplied URIs: a consumer SHOULD constrain src to expected schemes and origins before fetching, and MUST fail safe (degrade to text) on a clip that does not load, rather than blocking the lesson.

Personal data in attribution

The attribution.name field, and a personal generated_by or url, can carry a real person's name and a link to them. This is the only personal data VLDS defines, and it is present by design, because open-licence attribution legally requires it. Authors SHOULD prefer a pseudonym or an organization where a contributor wishes it, and consumers republishing lessons MUST preserve attribution rather than stripping or altering it. VLDS carries no learner data of any kind: it is content, not a record of anyone's activity.

Resource limits

A consumer SHOULD bound the size and item count of a lesson it will load, so a hostile document cannot exhaust memory.

Known Limitations

• Respelling is source-language-biased. pronunciation.respell is a "sounds-like" aid written for one source language (in the reference pack, English), and it is not keyed by source language the way cue is. ipa is the language-neutral field; a future MINOR may key respell by source language.
• Register is an open string. To let any language name its own registers, register is a free string rather than a closed enum, with formal and colloquial as recommended, LexInfo-mapped defaults. The cost is that two packs can spell the same register differently; interoperability relies on the recommended values.
• No embedded content credentials. Provenance is asserted by source_type and generated_by, not cryptographically signed. A future MINOR may add an optional C2PA content-credentials reference for tamper-evident provenance; v1.0 does not carry one.
• Some rules are validator-only. Dialect coverage (P4), voice-key validity (P5), NFC (P3), and conditional attribution span fields or normalization the JSON Schema cannot fully express. A conforming validator MUST apply them; the schema alone is necessary but not sufficient.
• Draft status. One reference implementation exists. Until a second, independent one does, VLDS is a draft (§1).

Conformance

An implementation claims VLDS v1.0 conformance as a Producer, a Consumer, or both. The machine-readable schema at vlds-v1.0.schema.json checks structure; the criteria below add the cross-field and normalization rules a schema cannot express. Each criterion has a stable identifier.

Producer, a tool that emits VLDS

• P1
  Version. Output MUST set vlds_version to a "1.x" string.
• P2
  Required structure. Output MUST include id, a BCP 47 language, title, a non-empty dialects array, and a non-empty items array, and MUST NOT include an undeclared key except an underscore annotation.
• P3
  NFC. Every human-readable string (titles, cues, labels, variant text, transcripts) MUST be in Unicode Normalization Form C.
• P4
  Dialect coverage. For each item, every declared dialect MUST be covered by a targets entry or by the item's shared variant.
• P5
  Voice keys. When voices is declared, every key of every audio map MUST be one of the declared voice ids.
• P6
  Attribution. Any text or clip whose license is a CC-BY variant MUST carry attribution with a non-empty name.
• P7
  Provenance. Every audio clip MUST declare source_type; synthetic clips SHOULD set provisional true until human-reviewed, and a modified clip MUST carry a modification_note.
• P8
  Open licences only. Every license MUST be an SPDX id on the allow-list (CC0, or a CC-BY / CC-BY-SA version). NonCommercial and NoDerivatives licences MUST NOT appear.

Consumer, a tool that reads VLDS

• C1
  Major-version tolerance. A consumer MUST accept any lesson whose vlds_version major it recognises, ignoring unknown fields from a later MINOR and all underscore annotations.
• C2
  Transcript fallback. When an audio clip has no transcript, the consumer MUST use the variant text as the clip's text alternative.
• C3
  Graceful audio absence. A missing or unreachable clip MUST degrade to text and MUST NOT fail the lesson.
• C4
  Dialect resolution. For a chosen dialect, the consumer MUST resolve an item's variant from targets[dialect] or, failing that, the item's shared variant.
• C5
  Reject the invalid. A consumer MUST reject a lesson that omits a required field or violates a Producer MUST that a validator can check (P2 through P6).

Test vectors

Conformance vectors accompany this specification in the examples/ directory beside the schema: a set of valid lessons that every consumer MUST accept, and invalid lessons (a missing required field, an uncovered dialect, an undeclared voice key, a CC-BY clip with no attribution, a non-NFC string, a NonCommercial licence) that every conforming validator MUST reject, one per criterion above. The reference implementation exercises these vectors in its VLDS conformance suite.

Glossary

References

Normative

Informative

Changelog