File extension of an annotation set

[llemeurfr]

Should a standalone annotation set have a ".json" extension, ".jsonld" extension, or should it have a specific extension, e.g. ".annotations" or ".ann"?

In Open Annotation in EPUB, the filename annotations.json is used for standalone annotations packages with resources in a zip container. No specific extension is indicated when the collection is not zipped, we suppose that .json is expected here also.

In W3C Annotation Data Model, the recommended serialization format being JSON-LD, the standard extension on an annotation file is .jsonld and the media type is application/ld+json;profile="http://www.w3.org/ns/anno.jsonld.

[HadrienGardeur]

The students import the ebook and the detached annotation file into their reading application: the annotations made by the teacher appear in the ebook.

With this use case in mind, it feels important to have something more specific than .json or .jsonld to implement the ability to sideload those files in reading applications.

Reading applications will typically do the following:

• register file extensions and/or media types
• and provide a file picker (where they filter files that can be picked based on a file extension)

[mickael-menu]

I know it's tricky to identify uniquely a publication, but should we add something in the Annotations Document to do the matching automatically? Maybe I missed it in the spec.

[HadrienGardeur]

I can confirm that uniquely identifying a publication is extremely difficult.

A TF attempted to do so during the IDPF days (I'll have to dig to find back these documents) and failed at doing so. CFI was added at the last minute to the EPUB spec family following this attempt.

[llemeurfr]

A file extension is indeed a facilitator for importing an annotation Set into a reeading app by double-clicking on a file (desktop) or tapping on a screen (mobile). If there is a consensus for defining an extension, which one is it?

.ann does not seem widely used (https://filext.com/file-extension/ANN). .annotations is really long, but seems unused.

[HadrienGardeur]

It goes beyond the sideloading use case from a file system that you're describing @llemeurfr.

On mobile:

• let's say that my app has an annotation list affordance for each publication
• I open that list and tap on import
• a native file picker is used to select a file, where all the files that do not have the proper file extension are hidden or greyed out

[mickael-menu]

I prefer .ann or maybe .anno.

[llemeurfr]

Re. importing an Annotations Set with no prior explicit association with a publication: please read https://github.com/readium/annotations?tab=readme-ov-file#21-about. At export, any identifier the reading app possesses on the publication should be written here, plus some metadata like the publication's title.
There will be no 100% success, but a clever heuristic may find a good fit in a reading system catalog (especially when the imported annotation set is exported / imported from a same or different instance of the same version of a publication).

In Thorium 3.1, we will start by associating an Annotation Set to an explicitly chosen publication (from a contextual menu on the publication cover), so that we avoid this difficulty. Import by double-click on an annotation file will be developed later.

[llemeurfr]

If we choose .ann or similar, we'll store annotations.ann in EPUB files and reference this filename from RWPM.

Are you ok with this redundant naming convention?