The GigCharts vocabulary

The namespace

A .gigchart file carries a pointer to the published JSON-LD context, which declares this namespace as its @vocab. So a chart is linked data as it sits on disk — no conversion step:

{
  "@context": "https://www.gigcharts.app/context/gigchart.jsonld",
  "@type": "gc:Chart",
  "id": "urn:uuid:5b1e6e1a-2f3c-4a7b-9d21-6c9a1e3f7d02",
  "format": "gigchart",
  "version": 12,
  "song": {
    "@type": "schema:MusicComposition",
    "properties": { "title": "House of the Rising Sun", "artist": "Traditional" },
    "annotations": [
      { "kind": "cue", "text": "slower", "target": { "kind": "line", "stanza": 0, "line": 1 } }
    ]
  }
}

Expanded, that is:

<urn:uuid:5b1e6e1a-…>
    a                     gc:Chart ;
    gc:format             "gigchart" ;
    gc:formatVersion      10 ;
    gc:song               [ a               schema:MusicComposition ;
                            schema:name     "House of the Rising Sun" ;
                            schema:byArtist "Traditional" ;
                            gc:annotations  [ a          gc:cue ;
                                              gc:text    "slower" ;
                                              gc:target  [ a gc:line ; gc:stanza 0 ; gc:line 1 ] ] ] .

An open namespace

Because the context sets @vocab, every key in a .gigchart mints an IRI in this namespace — the ~200 typesetting settings and annotation fields included, not only the terms defined below. Nothing in the file is dropped on expansion.

This document defines the structural core: the chart, the composition link, the classes behind every kind, and the identifier properties. The key-by-key meaning of everything else is the job of the format specification, which is written and kept current against the code. Two copies of that would mean one of them is quietly wrong, so there is one: if a term you are looking at is not listed here, look it up on /format.

Classes

Annotation kinds

The context aliases an annotation's kind key to @type, so every annotation node expands with the class named by its own kind token — a cue annotation is a gc:cue. The local names are lowercase because they are the file's tokens verbatim; a vocabulary that renamed them would be defining terms no document uses.

What each kind can target, and which fields it carries, is on /format.

Target kinds

The same kind alias applies inside an annotation's target, so a target is a typed node too. No target token is also an annotation token, so the two sets never collide.

Properties

The schema.org alignment

A song's identity metadata is not GigCharts' to invent — it is a schema:MusicComposition, and the context maps it onto schema.org terms so a consumer that has never heard of GigCharts still reads the parts that matter:

Everything else — duration, the MusicBrainz identifiers, and the whole chart body below properties — is gc:, because schema.org has no term for it and borrowing a near-miss would be worse than minting an honest one.

Known simplifications

Two places where the mapping is looser than it looks. Both are stated rather than hidden, because a consumer that trusts the alignment deserves to know where it bends.

• Names where nodes belong. artist, music, lyrics, album — the credit fields — carry a plain name string, while schema:byArtist, schema:composer, schema:lyricist and schema:inAlbum expect a node (a Person, MusicGroup or MusicAlbum). The chart holds what its author typed: a name, not an entity. Where the author picked the credit from metadata autocomplete, the resolvable identity travels beside it as gc:mbArtist and friends, and that is the node-shaped one.
• duration is not schema:duration. The file holds a display string (3:45); schema:duration's range is an ISO-8601 duration (PT3M45S). Rather than assert a value that fails its own range, the term is gc:duration.

Stability

The vocabulary is published under CC BY 4.0. The .gigchart format is open and unencumbered: read it, write it, build on it.