The sighting file

A recording is a plain JSON file. Nothing in it is a binary blob, an id into a database, or a reference to this site — you can write one by hand, generate one from your own archive, or diff two of them in a code review.

Every excerpt below is read-only, and each knows the format: put the caret inside an object and press Ctrl+Space (⌥+I on a Mac) to list every key that could go there, with what the model says of each.

The observation#

Several observers: the case#

Each observer has a recording of their own, and a recording does not say which case it belongs to: an account stands on its own. What shows them together is the case, which names them: the case.json of an RR0 dossier, which states the case's title, date and classification, and lists everything that happened in it as events. Its events of type sighting are its accounts, each pointing at one observer's recording:

{
  "id": "ChilesWhitted",
  "title": "Chiles et Whitted",
  "time": "1948-07-24 02:45",
  "events": [
    { "type": "event", "eventType": "sighting", "url": "observer-chiles.json" },
    { "type": "event", "eventType": "sighting", "url": "observer-whitted.json" }
  ]
}

Give it to <rr0-sighting src> or to the player, and each observer can be picked from a list. One recording can be given directly, with no case, but a case with one sighting works the same way and names what it shows. Try it with case-chiles-whitted.json (play it).

Saying it in more than one language#

A recording is handed from one reader to another, so every field an author writes can hold one string per language instead of one: description, a shape's or a decor object's title, and a milestone's label and note.

{
  "description": {
    "fr": "Tout le compte rendu de Lonnie Zamora, d'un seul tenant…",
    "en": "Lonnie Zamora's whole account, of a piece…"
  }
}

Keys are language tags as a browser gives them (fr, en, pt-BR), and none of them is required. A plain string stays perfectly valid and means “in whatever language it was written in” — which every recording made before this is. A reader whose languages are none of the ones present gets what the file DOES have rather than an empty field: a missing translation must never turn something the observer said into something they did not.

Which language a reader gets is their browser's, unless the page says otherwise: a lang on the element itself, or on anything around it, is taken first — an article that declares its own language has already stated what language its reader is reading it in. The browser's list is what follows, so declaring one forces a choice without throwing away the others.

The editor shows one language, the reader's own, and writing back touches only that one — so opening a file in the other language and typing is how a translation gets added, and one author cannot delete another's.

What was seen#

timeline.keyframes is a list of { t, shapes }, t in milliseconds from the start. Each shape carries a sourceId — several shapes can share one timeline (the phenomenon, a trailing flame, a second light) — and a shape:

{
  "kind": "oval",
  "bounds": { "x": 0, "y": 0, "width": 0, "height": 0 },
  "color": "#39ff14",
  "angle": 0,
  "transparency": 0,
  "haloScale": 1.5,
  "brightness": 0,
  "blur": 0,
  "selected": false,
  "title": "the phenomenon",
  "angular": { "widthDeg": 1.2, "heightDeg": 0.4 },
  "aim": { "azimuthDeg": 353.6, "altitudeDeg": 0.6 }
}

aim places it, angular sizes it. bounds is those two projected onto the fixed 640×360 canvas at the pose's own heading and field of view, through the recording's own instrument; it is re-derived on load, so a file survives a change of canvas, of field of view, of instrument, or of where the observer was looking. If the pixels and the angles ever disagree, the angles win: moving bounds in a file does nothing while aim is there. A file written by hand can leave bounds out entirely.

timeline.order is the back-to-front paint order, timeline.groups the grouped source ids. Both optional.

Everything around it#

A decor object is stated in metres, like everything that is not the phenomenon:

What it was: interpretations#

A recording states angles, and a body in metres is never part of what was seen. It is a claim about it, and it is tested by standing it in the scene and looking at it from where the observer stood: it casts its shadow, the ground can hide it, and its outline is measured against what the observer said at every instant. An interpretation is shown alone, as the world it claims; asked to compare (the ◌ button, or compare-account on <rr0-sighting>), the player draws everything the observer saw beside it as dashed outlines and lists how far off the direction is and how many times wider and taller each body looks, in red when an observer could not have been that far off.

The observer's own reading goes in the recording, as interpretation. Someone else's reading is not part of the account: it is another sighting, listed in the case (see below). A account whose observer said what it was is drawn in the round, as they said; one that says nothing in metres is drawn as the angles it states. The player offers it and each analyst's interpretation, one at a time.

{
  "interpretation": {
    "title": "A craft standing on its legs",
    "bodies": [{
      "id": "craft",
      "explains": ["ufo-1"],
      "model": { "id": "ellipsoid" },
      "track": [
        { "t": 52000, "eastM": -571.6, "northM": -965.5, "onGround": true,
          "sizeM": { "widthM": 3.36, "lengthM": 3.36, "heightM": 1.73 },
          "appearance": { "color": "#e8e6df", "albedo": 0.7 } },
        { "t": 83000, "azimuthDeg": 195.9, "altitudeDeg": 4.1, "distanceM": 44 }
      ]
    }]
  }
}

Another reading: an interpretation is another sighting#

Someone else's reading of an account (an analyst's, an investigator's, a comparison made to test it) is not part of the account: it is another observation, the one that took place as its author holds it. So it is listed in the case like the original, as an event of type sighting, marked as a reading by interpretationOf, and has a recording of its own at url:

{
  "id": "McMinnville1950",
  "events": [
    { "type": "event", "eventType": "sighting", "id": "trent", "title": "Paul Trent", "url": "observer-mcminnville.json" },
    { "type": "event", "eventType": "sighting",
      "interpretationOf": "trent",
      "time": "2013-06",
      "by": [{ "people": "CousynAntoine" }, { "people": "LouangeFrancois" }],
      "title": "A model on a thread under the line",
      "url": "interpretation-mcminnville-2.json" }
  ]
}

The recording at url is a recording like any other. It shares the place, the time and the observer's pose of the account it reads, so that a body placed from the observer, or in metres from where they stood, means the same in both; it draws no shape of its own (an empty timeline); and it holds the bodies in its own interpretation, described above. A body's explains names the shapes of the account.

{
  "version": 1,
  "id": "1950-05-11-TrentPaul-interpretation-2",
  "time": { "year": 1950, "month": 5, "day": 11, "hour": 19, "minute": 45 },
  "utcOffsetHours": -7,
  "place": [{ "value": { "lat": 45.104167, "lng": -123.330556 } }],
  "observerTrack": { "keyframes": [{ "t": 0, "pose": { "lat": 45.104167, "lng": -123.330556, "headingDeg": 41.3, "pitchDeg": 14.85, "fovDeg": 33.4 } }] },
  "tags": ["interpretation"],
  "timeline": { "keyframes": [], "order": [], "groups": [] },
  "interpretation": {
    "title": "A model on a thread under the line",
    "bodies": [{
      "id": "model",
      "explains": ["ufo-1"],
      "model": { "id": "disc" },
      "track": [
        { "t": 0, "eastM": -52, "northM": 118, "altitudeAboveGroundM": 7.5,
          "sizeM": { "widthM": 0.3, "lengthM": 0.3, "heightM": 0.1 } }
      ]
    }]
  }
}

The player lists the case's observers from the events with no interpretationOf and offers each reading beside the account it names, one at a time (the ◌ button measures it against the account). A recording standing alone has no reading but its own interpretation. The older form, an event of type interpretation naming the recording in sighting with its bodies inline or in a file at url, is still read. The editor opens a case: its picker above the render lists the accounts and the readings, each opening as the recording it is, with a button to add a reading (a new recording that shares the account's place, time and pose, and an event for it), one to delete it, and one to export the case and every recording added or changed as a zip. Try it with case-mcminnville.json (play it, edit it).

The weather, and its clouds#

A weather keyframe states the sky's conditions at one moment of the recording's clock; between two keyframes every number is blended, and precipitation type and storm are held. It carries:

Each layer of cloudLayers is a deck of clouds at a real height, and stays itself from one keyframe to the next:

An individual cloud in instances is one cloud of its layer that the file places exactly, because the account did: the one the phenomenon went behind, the one that was there and nowhere else. It is drawn as one of its layer's own — the same texture, the same threshold — told apart from its neighbours by nothing but where it stands and how big it is, and it stands even when the layer's coverage is nought. It rides the layer's wind like the rest, and it hides a phenomenon it passes in front of.

{
  "weather": {
    "cloudLayers": [
      {
        "id": "low", "type": "cumulus",
        "baseM": 1500, "thicknessM": 800,
        "coverage": 0.55, "sizeM": 1400, "density": 1, "darkness": 0.15,
        "instances": [
          { "id": "the-one", "eastM": 0, "northM": 4200,
            "baseM": 1500, "thicknessM": 800,
            "widthM": 1900, "depthM": 1300, "rotationDeg": 12, "density": 1 }
        ]
      },
      { "id": "high", "type": "cirrus", "baseM": 8000, "thicknessM": 400,
        "coverage": 0.2, "sizeM": 2200, "density": 0.35, "iceCrystalAlignment": 0.65 }
    ],
    "precipitationType": "none", "precipitationIntensity": 0,
    "windDirectionDeg": 90, "windSpeed": 5, "storm": false
  }
}

A recording whose weather was looked up (it has a weatherSource) holds the record's answer, not a link to it: ERA5 gives the low, middle and high bands as three layers named record-low, record-mid and record-high, the low base estimated from the spread between temperature and dew point, the other two at 3 500 m and 8 000 m. Their type is unknown (cirrus for the high one), their size and density are drawing assumptions: a reanalysis knows how much of each band was covered, not what the clouds looked like. Ask the record again from the editor and the layers are rewritten; edit a layer by hand and the recording becomes the author's, the source dropped.

Where each value comes from#

Any value in a recording can be written bare, or wrapped with where it came from:

{
  "durationSeconds": {
    "value": 15,
    "basis": "derived",
    "rationale": "13 to 18 s in the investigator's synthesis; the middle taken"
  }
}

basis is stated (the observer said it, and what a bare value means), derived (worked out from what they said plus something checkable: a road's width, a map, a measured drawing; rationale gives the working) or assumed (chosen so the reconstruction has a value at all, on nothing the observer said). The list of assumed values is the list of what to go back to the observer or the file for, which is why it is worth writing even when nothing else is.

Checking a file#

The format is also published as a JSON Schema, generated from the same types as the player: every key it knows, what each may hold, and the words a closed list accepts. A misspelt key or an unknown value fails it. It says nothing about what may be left out, which is a question of meaning this page answers. To see the result, open the file in the player, from a link, or from your disk with the pictures and models it names. The player checks it the same way on loading, and says what it could not play as written behind a ⚠ over the picture: a key nothing reads, a word outside its list, and what it had to make up because a shape's first keyframe left it out (a field held from the keyframe before is the rule above, not a problem).

A whole file#

The smallest recording that still states something — one silent oval crossing the sky over twelve seconds, on a real date at a real place. Everything else in the format is optional, and everything below is doing work:

{
  "version": 1,
  "description": "The smallest recording that still states something: one silent orange oval, a degree and a half wide, crossing the south-western sky from left to right over twelve seconds.",
  "time": { "year": 2024, "month": 8, "day": 12, "hour": 22, "minute": 30 },
  "durationSeconds": 12,
  "utcOffsetHours": 2,
  "place": [{ "lat": 45.19, "lng": 5.72, "name": "Grenoble, Isère, France" }],
  "timeline": {
    "keyframes": [
      {
        "t": 0,
        "shapes": [
          {
            "sourceId": "ufo-1",
            "shape": {
              "kind": "oval",
              "bounds": { "x": 150, "y": 150, "width": 10, "height": 3 },
              "angular": { "widthDeg": 1.6, "heightDeg": 0.5 },
              "color": "#ff8c1a",
              "angle": 0,
              "transparency": 0,
              "haloScale": 1.2,
              "selected": false
            }
          }
        ]
      },
      {
        "t": 12000,
        "shapes": [
          {
            "sourceId": "ufo-1",
            "shape": {
              "kind": "oval",
              "bounds": { "x": 480, "y": 130, "width": 10, "height": 3 },
              "angular": { "widthDeg": 1.6, "heightDeg": 0.5 },
              "color": "#ff8c1a",
              "angle": 0,
              "transparency": 0,
              "haloScale": 1.2,
              "selected": false
            }
          }
        ]
      }
    ]
  },
  "observerTrack": {
    "keyframes": [
      {
        "t": 0,
        "pose": { "lat": 45.19, "lng": 5.72, "elevationM": 0, "headingDeg": 215, "pitchDeg": 20, "fovDeg": 60 }
      }
    ]
  },
  "soundTrack": { "keyframes": [{ "t": 0, "sound": { "kind": "none", "volume": 0, "pitchHz": 100 } }] }
}

To change it and see it play, paste it into the editor, which completes on every key the format has, offers the words each one accepts, and says what the model says about it.

It is /demo-data/example-minimal.json on this site, so you can fetch it, and play it before changing anything. Note that angular and bounds both appear: the angle is what the file MEANS, and the pixels are re-derived from it on load — write the angle, and let a wrong guess at the pixels be corrected for you.

Larger ones to read#

Every demo on this site is a plain file you can open. These four are the ones worth reading to see how a real recording is put together:

Four rules that decide what a file means#

• Discrete fields are held, continuous ones are blended. A shape left out of a later keyframe stays as it was, and so does any field a keyframe leaves out of a shape it does restate: a keyframe that only gives a new aim moves the shape and keeps everything else (restating bounds without aim or angular is taken as moving it by its pixels); one whose first keyframe is at five seconds is already painted, in that state, from zero. To make something stop being visible, keyframe it at transparency: 1.
• Angles only. No real size and no real distance is stored anywhere. Metres are derived, as inequalities, from what the phenomenon was stated to pass behind or in front of (decor[].occludesSourceIds).
• Declared outranks deduced. occludesSourceIds records statements by the observer. Nothing in this format can deduce them: it describes an appearance on a field of view, not a position in space.
• Absent is not zero. No sound track means nobody was asked; kind: "none" means the observer reported hearing nothing. The same distinction runs through the weather and the ice cloud.

This page is the reference for the format. The reasoning behind each field is in the doc comments of its type, which the excerpts above complete with, and in the source.