EXIF and XMP metadata

Catalog reads your files’ metadata on import and lets you complete it. By default, it never writes into your files: your changes go into the catalogue and into an XMP sidecar placed next to the file, which Bridge, Lightroom and Capture One read back. Writing into the file itself is an explicit choice, confirmed each time.

Everything goes through macOS frameworks (ImageIO): Catalog uses no external program.

What Catalog reads

On import (and when you click Read the file again in the inspector), Catalog reads:

• technical data: dimensions, orientation, colour profile and model, camera, lens, focal length, aperture, shutter speed, ISO, capture date, GPS;
• descriptive fields, in IPTC as well as XMP: title, description, creator, rights, keywords, hierarchical keywords (Lightroom), rating, colour label, creation date, GPS coordinates;
• all other EXIF, TIFF, IPTC, GPS and XMP properties, visible in the inspector under All metadata.

If there is a sidecar next to the file — IMG_0001.xmp (Adobe convention) or IMG_0001.CR2.xmp — its descriptive fields take precedence over the file’s, whether it was written by Catalog or by another program. When several files of the folder have the same name, IMG_0001.xmp is read for the RAW only (see The XMP sidecar).

A new import of the folder reads a file already read field by field: technical data follows the file; a descriptive field (title, description, keywords, creator, rights, rating, label, capture date, coordinates) changed in Catalog since the previous read is kept, and a field you did not touch takes the new value of the file or its sidecar, for example a title changed in Lightroom. For this, Catalog keeps with the metadata a record of what the last read gave. A file read before version 0.19.1 has no such record yet: at the first new import it keeps all its descriptive fields, then the rule applies. Read the file again takes every field from the file and its sidecar.

The capture date

The capture date is the time the camera showed when the photo was taken, shown as it is: Catalog converts it neither to your Mac’s time zone nor to universal time. A photo taken at 10:20 in Paris shows 10:20, wherever you open the library.

• EXIF does not say which time zone the camera was in: the date is stored without one, 2024-05-01T10:20:30.
• When the file gives its offset (recent cameras write it), it is kept: 2024-05-01T10:20:30+02:00. The time shown is still the camera’s.
• A date from an XMP sidecar or from Lightroom is kept as written.
• The Captured sorts follow the camera’s time, whatever the form of the date.

Versions before 0.20.0 stored the camera’s time as a universal time (2024-05-01T10:20:30.000Z) and showed it shifted. The update corrects these dates in the library and changes nothing else. It rewrites neither your files nor your sidecars: the corrected date reaches an XMP only at the next save you ask for. The offset of a file that gives one comes back at its next read (Read the file again, or a new import of the folder).

Editing a file’s metadata

1. Choose the file in the grid.
2. In the inspector, click Edit….
3. Fill in the fields, choose where to save, then Save (⌘S).

The fields:

• Title, Description, Creator, Rights;
• Keywords — type them separated by commas, then Return; each keyword becomes a token, removable with one click. While you type, Thesaurus: offers the thesaurus terms that start like the word typed (by their label or a synonym); a click adds the term’s label. A keyword that is a term or a synonym of the thesaurus is marked with a book; the others are free, and the Add to thesaurus menu (or a right-click on the token) makes one a top-level term of the thesaurus;
• Rating — from 1 to 5 stars (a click on the chosen star clears the rating). With VoiceOver, the rating is a single control (“Rating, 3 stars”), adjusted with VO-↑ and VO-↓;
• Capture date — in ISO 8601 format: 2024-05-01 or 2024-05-01T10:20:30;
• Latitude and Longitude — in decimal degrees; a decimal comma is accepted.

Hierarchical keywords and the colour label read in the file are not edited here, but they are kept.

If the file is the reference image of a work and you change its Title, the editor offers after saving Update the work (the work takes the new title) or Keep the work’s title. Nothing is offered for a cleared title (see The work’s title and the image’s).

Default creator and rights

Settings › Files › Default creator and rights gives a creator and rights to a file that has none, for instance “Example Studio” and “© {{year}} Example Studio”. {{year}} becomes the year the photo was taken, or the current year if it has no capture date. They are applied:

• when a folder is imported, as Catalog reads the metadata: in the catalogue only, neither the file nor its sidecar changes;
• in the editor, whose empty Creator and Rights fields open filled in, with the note “Empty creator or rights: offered by Settings › Files, saved only with Save.” Cancel keeps nothing.

A creator or rights already there are never replaced.

Indexing (who, what, where, when, how, why)

Below the descriptive fields, the Indexing part describes what the photograph shows in six questions: Who (people, groups), What (subject, object, scene), Where (place, city, country), When (date, period, season), How (technique, viewpoint) and Why (context, occasion). Each answer is free text; answer only the questions that matter.

Indexing is saved with the rest by Save, but in the catalogue only, whatever the “Save to” choice: it is written neither to the sidecar nor to the file. Clearing all six answers removes the file’s indexing.

The inspector shows it (Indexing section, read only), or “Not indexed yet”. Quick search, and advanced search in Everywhere, find a file by a word of its indexing (see Quick search).

Indexing is entered file by file: the editor changes one file at a time.

Checks

Catalog checks the fields as you type and refuses to save while a problem is shown:

• a title longer than 64 characters, rights longer than 128, a creator longer than 256, a description longer than 2,000, a keyword longer than 64: “is too long for IPTC (Bridge and Lightroom would truncate it)”;
• a control (invisible) character in a text;
• a rating outside 0 to 5, a latitude outside −90 to 90, a longitude outside −180 to 180;
• a date not in ISO 8601 format.

Restoring a version

The editor’s Versions part lists the file’s recorded versions (see Versions), newest first. The one the catalogue holds as the current state is marked Current; the others have a Restore this version… button.

A version, in Catalog, is a SHA-256 fingerprint and a size: Catalog keeps no copy of your files’ bytes. Restoring a version therefore does not rewrite the file; it makes that version the file’s current state in the catalogue, once the file on disk holds its bytes again — for example after putting it back from your archive (Obscura Vault) or a backup.

After the confirmation (“Restore version n?”, Restore button), Catalog:

1. reads the file on disk and computes its fingerprint; if these are not the version’s bytes, it refuses and changes nothing: “The file on disk does not hold the bytes of version n… First put the file back from your archive (Obscura Vault, a backup), then restore the version.”;
2. keeps the state it leaves as a new version, named “Before restoring version n”: the history tells what was restored, and when;
3. records the file’s fingerprint, size and date.

The file, its XMP sidecar and the catalogue’s metadata are not changed; Read the file again (in the inspector) then re-reads its metadata if needed. The restoration applies as soon as it is confirmed, without waiting for Save.

If the file’s current state underpins a valid certificate, the confirmation says so and names the certificate (“Restore a version of a certified file?”): after the restoration, the file’s current state in the catalogue will no longer match that certificate. You then click Restore anyway.

Relating a file

The editor’s Related part lists the files linked to this one (see Relationships): the kind of relationship, the other file’s name, and an arrow giving the direction (→ this file is the source, ← it derives from the other).

Relate a file… opens a picker:

1. search for the other file by its name, title, a keyword or a word of its indexing (the first 200 results are listed, with their thumbnail; refine the search to find the others);
2. choose the kind of relationship: Derivative, Edit, RAW + JPEG, Stack, Duplicate or Other;
3. click the file, then Relate.

The relationship goes from this file to the one you chose. A file already related with this kind is marked “Already related”. A row’s − button removes the relationship, after a confirmation. Relating and removing apply at once, without waiting for Save.

Selecting two files in the grid, then ⋯ › Relate, still does the same.

Attached documents

The editor’s Documents part gathers the papers that go with the photograph. Their kind is the same as for a document of the work: correspondence (a letter, an exchange), invoice (print, purchase), exhibition sheet, archives, external certificate, condition report or other. (Up to version 0.18, a file’s document had four kinds, Letter among them; a letter already attached became correspondence with the update.)

To attach a document: choose its kind in the menu, then Attach a document… and the file (PDF, image, text: any format). Catalog copies the document into the library, in the Documents/ folder next to the database (see Where Catalog keeps its data), and records the SHA-256 fingerprint of the copy. The original is not changed; the document stays readable if the original is moved, deleted or on an unplugged disk.

For each document:

• its name is edited in the field (Return, or leaving the field, saves it); at first it is the file name, without extension; the original file name and the size stay shown below;
• its kind is changed in the menu;
• the Confidential box keeps it out of the LIDO and CIDOC exports, and out of the CSV unless you include confidential records (see Attached documents). It starts ticked for a new invoice, which carries prices and parties, and unticked for the other kinds; you tick or untick it as you see fit. A document that serves as the proof of a confidential provenance event stays confidential as long as the event is: its box is then ticked, greyed out, and Catalog says why;
• Open the document opens it in the default application (Preview for a PDF); Show in Finder shows the copy;
• Delete document (the bin icon, after a confirmation) deletes the document and its copy in the library; the original, where you took it from, is never touched. The deletion cannot be undone with Edit › Undo.

Attaching, renaming, ticking Confidential and deleting apply at once, without waiting for Save. The inspector lists the file’s documents (Documents section), with a Confidential padlock on those that are; a work’s record lists those of all its files (Documents tab, see The work record).

The documents of this editor are attached to a file of the library; those about the work itself (correspondence, an exhibition sheet, archives, an external certificate) are attached to the work or to one of its prints, in the Documents tab of its record (see The work record). A document attached to a file of a work can serve as the proof of an event of its provenance (see Provenance). Removing a file from the catalogue also removes its documents; their copies are deleted the next time Catalog opens. They are in the CSV, LIDO and CIDOC exports with the works of their file, except confidential documents (see Attached documents).

If a document’s copy cannot be found (Documents/ folder erased, library restored without it), “Open” says so: restore the library folder from a backup, or attach the document again.

Where to save

Under Save to, three choices:

• The catalogue and an XMP sidecar (the file is not modified) — the default, which Settings › Files can change;
• The catalogue only — nothing is written next to the file;
• The catalogue, the sidecar and the file itself — offered only for JPEG, TIFF, PNG and HEIC/HEIF.

The editor always opens on the choice of Settings › Files, and writing into the file is confirmed at every save. For a RAW and other formats, writing into the file is not offered (the editor then opens on the sidecar): “This format cannot take metadata without being re-encoded (RAW…): an XMP sidecar is written next to it.”

The XMP sidecar

The sidecar has the file’s name with the .xmp extension (IMG_0001.CR2 → IMG_0001.xmp). If one already exists (Adobe or IMG_0001.CR2.xmp), Catalog writes into that one.

When another file of the same folder has the same name — a RAW and its JPEG (IMG_0001.CR2 and IMG_0001.JPG), a TIFF and its JPEG (photo.tif and photo.jpg) — one .xmp cannot serve both:

• IMG_0001.xmp stays the RAW’s, the one Lightroom reads;
• every other file has its own, name and extension included: IMG_0001.JPG.xmp, photo.tif.xmp, photo.jpg.xmp;
• a JPEG, TIFF, PNG or HEIC never reads or writes IMG_0001.xmp when a file of the same name is next to it: its metadata never mix with the RAW’s.

The folder on disk decides, not the catalogue: a RAW that was not imported keeps its IMG_0001.xmp.

Catalog merges: it replaces only the properties it manages — title, description, rights, creator, keywords, hierarchical keywords, rating, label, creation date, latitude and longitude. All other properties of an existing sidecar (Lightroom develop settings, other programs’ namespaces) are kept as they are. A field you clear is removed from the sidecar.

Writing into the file

Choosing The catalogue, the sidecar and the file itself asks for confirmation: “Modify the original file? … will be rewritten without touching its pixels. Its SHA-256 changes; the previous one is kept as a version.” Click Write into the file to confirm.

• The image data is copied as is, never re-encoded.
• The rest of the file’s metadata (EXIF, other XMP properties) is kept; macOS copies the XMP into the file’s IPTC fields.
• The new file is written next to the original and then swapped in at once: if anything fails, the original stays intact.
• Since the file’s content has changed, Catalog records its new SHA-256 fingerprint and keeps the previous one as a version (see Versions).

If this file is preserved elsewhere with its fingerprint (in Obscura Vault, for example), this write will make it show as modified. Prefer the sidecar for an original you preserve.

If saving fails

• “The file cannot be found: nothing was saved. Was the folder moved or the disk unplugged?” — the sidecar and writing into the file need the file. Plug the disk back in, or choose The catalogue only.
• “Saving failed. Nothing was changed.”

Good to know

• Ratings, flags and labels set in the grid stay in the catalogue. The rating typed in the editor, though, is written to the sidecar (and to the file if you chose to) and carried over to the grid.
• A sidecar modified by another program is read again with Read the file again. A new import of the folder takes the fields you did not change in Catalog.