Exporting the catalogue

The Exports section produces the full export of the library, the package for Obscura Vault and three formats:

• Full export — the whole library and all its data, in open formats, in a folder or a ZIP archive (see Full export of the library);
• Package for Obscura Vault — a backup, a full export without images and the list of the originals, to entrust to Obscura Vault for archiving (see Package for Obscura Vault);
• CSV — for a spreadsheet, or to re-import into another catalogue;
• LIDO 1.1 (XML) — for a museum or a collections portal;
• CIDOC CRM (Turtle) — for an institution working with linked data.

The full export, the package for Vault and the CSV export are included without a licence: your data always leaves in an open format. LIDO and CIDOC CRM exports require an Obscura Catalog licence; without one, Catalog says so before even asking where to save (see Licence and free tier).

The section’s cards are arranged in two groups, across the whole width of the window: Work records (CSV, LIDO, CIDOC, then, under Options for these exports, the Attached documents and LIDO and CIDOC records cards), then Whole library (the full export and the package for Vault). The number of columns follows the width: two in a narrow window, three at 1,440 points; on a large screen, the two groups sit side by side. The cards of a row have the same height, their buttons lined up at the bottom.

Each export covers every work in the catalogue, whatever its status (drafts included), minus what the confidentiality rule holds back. During an export, a progress bar is shown; you can stop it: “Export stopped. No partial file is kept.” Everything is first written into a hidden folder next to the destination, and only appears once complete: an export that is stopped, or fails (a full disk), leaves no table, no copy of a document and no justification note, and nothing is recorded in the confidential exports log. At the end, Show in Finder opens the files written.

Full export of the library

Full export of the library, the first card of the Whole library group, or File › Export All…, writes the whole library and all its data in open formats, in a folder “Full export ––”, or a ZIP archive of the same name: enough to read it without Obscura Catalog, to hand it to an institution or to keep it as an archive. The backup (Settings › Backup) copies the database as it is, to restore it; the full export takes the data out in formats any software reads, and is not restored.

1. Choose the Separator of the tables and the options (below). File › Export All… uses the card’s options.
2. Export all…, choose the folder to write it in (Catalog says the name it will create there), then Export here.

The tables are in UTF-8 with BOM; they join on their identifiers (asset_id, work_id, document_id) and on the catalogue number; their paths are relative to the root of the export. The values of the lists are written as their code, the same whatever the interface language: the library’s (flag pick or reject, label red, yellow…, kind of relationship) as well as the catalogue’s (see The codes of the values). The columns of every table follow the same commitments as the CSV export (see What will not change).

Options

• Copy the images: every file of the library is copied into images/<folder>/<path in the folder>, its folder structure kept. Its SHA-256, computed while copying, is compared with the one the library recorded at import. An unreadable original (disk unplugged, file moved) is not copied; an original changed since the import is copied as it is. The image_status column of files.csv (copied, differs, missing) and manifest.json name them, and Catalog says so at the end. Before starting, Catalog checks that the disk has the space needed.
• Add the LIDO 1.1 records and Add the CIDOC CRM: the files of the LIDO and CIDOC exports (see below), which require the same licence; their documents point to documents/.
• Add the names given to faces: bibliotheque/faces.csv, the names of the people of the Faces section and the files they appear in. Face prints, which are biometric data, are never exported, nor the position of a face in the image, with or without this option; nor the prints of similar photos.
• ZIP archive instead of a folder: a single .zip file, written once the folder is checked.
• Include confidential records: as for the CSV (see Including confidential records), with a justification, recorded in CONFIDENTIAL-EXPORT.txt at the root of the export and in the Confidential exports log (format “Full export”), for this export only.

What stays confidential

The confidentiality rule applies to the whole export. By default, confidential works, confidential provenance events (and their auction sales), confidential conservation interventions, the cost of every intervention, confidential documents and relations with a confidential work are left out; with a confidential work, the files linked only to it, or only to other works left out, stay too: their rows, metadata, indexing, tags, documents and images. A photo that is an installation view showing a confidential work is treated like that work’s files: withheld with them. A view showing a work whose reproduction is excluded keeps its row, never its image, even with the confidential records. A file linked to an exported work leaves with it; a file linked to no work leaves. A tag, a face name or a collection that applies only to withheld files stays with them: tags.csv, faces.csv and collections.csv do not name it (nor a smart collection whose rule is on such a tag, nor a group of collections holding only those); a tag or a collection that applies to no file leaves. The agents of agents.csv are those the exported records cite (authors and asserters of the attributions, printers of the prints, venues and curators of the exhibitions, publishers of the publications, parties to the publishable provenance events and the houses of their sales, conservators of the exported conservation interventions, rights holders): every agent a table of catalogue/ names has its row there. A party that only appears in a confidential event is not there, nor the holder of a print, nor an agent marked Confidential (no table names it then). With Include confidential records, the whole agent directory is there. LIDO and CIDOC never have the confidential records, even when the export includes them. Internal notes never leave.

Progress, stopping, checking

A bar shows the step (reading the library, copying the documents, copying the images, writing the tables, checking, compressing) and how far it is; Stop abandons the export and leaves nothing. Catalog reads the whole library in one consistent read: what you change during the export does not get in half-way, and you can keep working. It writes into a hidden folder next to the destination, reads every file back against the manifest (size and SHA-256, no extra or missing file), then gives it its name: a half-written export never appears. A second export on the same day takes the next name (“… (2)”). At the end, Show in Finder shows the folder or the archive.

To check a copy you received, shasum -a 256 <file> (in Terminal) gives the SHA-256 to compare with the one in manifest.json.

Package for Obscura Vault

Package for Obscura Vault, the card beside the full export, or File › Prepare a Package for Vault…, prepares what Obscura Vault needs to look after the library: Vault archives it, checks its fixity and keeps an off-site copy. Catalog and Vault share no database and no settings: the package is the only exchange between them. Preparing a package is included without a licence, like the full export.

1. Choose the Separator and the options (below). File › Prepare a Package for Vault… uses the card’s options.
2. Prepare a package…, choose the folder to write it in (Catalog says the name it will create there), then Save here.
3. In Obscura Vault, import that folder, or the ZIP archive.

What a package contains

A folder “Catalog package ––”, or a ZIP archive of the same name:

By default, the originals themselves are not copied into the package: they are listed by their SHA-256, the one computed at import, never by their path. Vault matches each SHA-256 against its archives; those it does not hold yet, it reads where the library finds them, and archives them only if the SHA-256 it reads is the right one. An original moved, changed since the import or on an unplugged disk is reported “absent” by Vault, without an error. The files the export retains and their versions are listed; the attached documents are not: they are already in backup/ and export/.

Catalog writes the backup first, then reads the export from that backup: the three parts describe the same state of the library, and you can keep working meanwhile.

Options

• Separator, Add the LIDO 1.1 records and Add the CIDOC CRM (licence, asked when the package is prepared), Add the names given to faces: the full export’s options, for the package’s export. It never has the images.
• ZIP archive instead of a folder: a single .zip file, whose root is the package’s folder, written once the package is checked.
• Copy the originals into the package (unticked by default): see below.
• Include confidential records in the export: as for the full export, with a justification, recorded in export/CONFIDENTIAL-EXPORT.txt and in the Confidential exports log (format “Package for Vault”), for this package only.

Copying the originals into the package

Tick Copy the originals into the package when the Vault that will receive the package cannot reach the disks of the originals: another Mac, or a package carried on a disk. Catalog then copies all the originals originals.csv lists into the package’s originals/ folder, each one once even if it appears several times in the library, under its SHA-256 (originals/<first two characters>/<SHA-256>, without an extension; its name stays in originals.csv).

• Size. The package then takes the size of the originals, on top of the rest: several hundred gigabytes for a photographic fonds. Before it starts, Catalog checks that the destination disk has that space, and refuses otherwise without writing anything; it checks again just before the copy.
• Check. Each original is read again and its SHA-256 computed during the copy. A copy is embedded only if its SHA-256 is exactly the one recorded at import; the embedded_path column of originals.csv is filled in for it only, and Vault checks it in turn.
• Not embedded. An original changed since the import (retouched, saved again) no longer has the bytes the library cites: its copy is removed. An original not found (disk unplugged, file moved) is not copied. An earlier version of a file has no copy to embed: Catalog does not keep its bytes. These originals stay in originals.csv, with their source hint: Vault can still read them where they are, if it can reach them.
• Outcome. Catalog says how many originals are embedded and, if any, how many are not and why: “120 originals embedded in the package; 3 not embedded: changed since the import (2), not found (1).”

The copy is a step of the progress (“Copying the originals…”, in bytes); Stop abandons it and leaves nothing.

What a package never contains

• the certificates’ signing key or its encrypted backup: it stays in the Mac’s keychain, and its backup in your keeping;
• the account’s session and the licence;
• the thumbnails and previews, which Catalog computes again;
• copies of the originals, unless you tick Copy the originals into the package;
• the face prints and the similar-photo prints, outside the database itself, in backup/.

A package is sensitive

The backup (backup/) is the whole database: it always holds the confidential records, the provenance amounts and the internal notes, whatever the options. The Include confidential records in the export box decides for the export only.

originals.csv also tells how your folders are organised. Entrust a package only to Obscura Vault or to a disk you control; Vault treats it as sensitive data (encrypted at rest and off site, nothing of its contents in its logs). The card says so before any option.

Progress, stopping, outcome

A bar shows the step (backing up the library, reading the backup, writing the export, copying the originals if you asked for it, listing the originals, checking the package, compressing the archive) and how far it is; Stop abandons the package and leaves nothing. Catalog writes into a hidden folder next to the destination, reads the whole package back as Vault will (every file against package.json: size and SHA-256, no extra or missing file), then gives it its name: a half-written package never appears. Before it starts, it checks that the disk has the space needed, originals to copy included. A second package on the same day takes the next name (“… (2)”); each package is complete, with its own identifier.

At the end, Catalog says how many originals are listed and their volume on their disks, the size of the package, how many originals are embedded if you asked for it (and why the others are not) and, if any, the originals left out of originals.csv because the SHA-256 or the size the library recorded for them is damaged: Vault would refuse the whole package for a single such row. Show in Finder shows the folder or the archive.

Restoring from Vault

Vault gives the package’s folder back as it is. To get the library back:

1. Copy the package’s backup/ folder where you want the library, and give it a name (“Restored library”, for instance): Catalog writes into the library it opens, and the package given back must stay intact.
2. File › Open Library…, then choose that folder (see Moving the library, keeping several libraries): Catalog restarts on it, with its works, agents, provenance, attached documents, issued certificates and settings.
3. The originals missing from the Mac are restored from Vault, by their SHA-256. Put back at their original location (the source_path column of originals.csv), they are found by the library, and the Missing mark goes away.

The export (export/) is not restored: it is there to read the catalogue without Catalog.

The confidentiality rule

Confidential works and events are excluded from every export; only the CSV, the full export and the package for Vault can include them, with a justification, for one export. Internal notes never leave.

The works table export (Export this table…, see The works table) follows the same rule and offers the same option, justified and recorded in the log (format “CSV”).

The following are confidential:

• a work marked Confidential record (see Identification);
• a confidential provenance event: this is the default, and always the case as long as a party is a living person; its amount is kept, and only goes into the provenance.csv of an export that includes confidential records (see Provenance); its auction sale follows it;
• the amounts of an auction sale marked Amounts confidential, even when its event is publishable: the sale leaves, without its estimates, hammer price, currency or its event’s amount;
• a conservation intervention marked Confidential (see Conservation);
• a document marked Confidential, or that proves a confidential event, or that documents a confidential intervention (see Attached documents);
• an agent marked Confidential (see Confidential agents): whatever role it is cited in, it is absent from LIDO, CIDOC, reports and certificates (no name, identifier or role), the record citing it leaving as if no agent were given, without the free-text place (of an exhibition, of an event) standing in for it; the CSV and Export this table… name it only with the confidential records.

The internal notes appear in no export, whatever the options: those of works, prints, agents, conservation interventions, lines of rights and documents of the work, and the note of a relation between works. Nor do a print’s location and price; its current holder only leaves in the current_holder column of prints.csv, with the confidential records, and the lender of an object shown only in the lender column of exhibitions.csv, with the confidential records. The stocktake leaves in no export. Nor does a record’s change history: it only leaves in the library’s backup (including a Vault package’s), without any confidential value.

CSV

Export catalogue as CSV: one row per work, plus joined files, linked by the catalogue number.

1. Choose the Separator: Comma (RFC 4180) or Semicolon (Excel, French locale). The screen starts from the separator of Settings › Exports (Default separator… takes you there).
2. If needed, tick Include confidential records (below).
3. Export…, choose a folder, then Export here. Catalog creates a new folder there, “CSV export ––” (“… (2)” when it already exists), and writes the export in it: it never touches the files already there, nor those of an earlier export, and the report gives the folder’s name.

Catalog writes twelve files, in UTF-8 with BOM (Excel opens them directly). The values of the lists (status, existence, precision of a date, edition kind, print status, kinds of document, relation and transaction, licences…) are written as their code (extant, draft, limited…), never as their label: the same fonds exported with Catalog in French or in English gives identical files. The table The codes of the values gives the label of each code in French and in English.

catalogue_number is the work’s catalogue no., inventory_number the inventory no. of the work (in works.csv) or of the print (in prints.csv), empty when there is none (see Catalogue no. and inventory no.).

In prints.csv, framed is 1 for a framed print, and frame_description then gives its frame note; signature_location, signed_at and signed_place say where, when and in what place it is signed. In exhibitions.csv, publications.csv and provenance.csv, print_number is the number of the print exhibited, cited or concerned, empty when it is the work with no particular print. current_holder names the print’s current holder, an agent of agents.csv, only when the export includes the confidential records, empty otherwise. frame_mm gives the framed dimensions (420 × 520, 420 × 520 × 30 with the depth). A print’s location, price and internal note are in no column. In exhibitions.csv, organizer names the exhibition’s organiser; lender, the lender of the object shown, only when the export includes the confidential records, empty otherwise. The exhibitions import ignores these two columns for now.

valuations.csv has rows only in an export that includes the confidential records, with its justification: a print’s values are always confidential. One row per value, history included, with the print’s print_number; one row per price tier of an edition, print_number empty, the edition (edition, its sequence) and its copies (first_copy, last_copy). kind is production, public_price, insurance or estimate (estimated value); source is a public price’s channel (gallery, studio, fair, other), an insured value’s source (artist, gallery, expert, insurer, other) or an estimated value’s (artist, gallery, expert, other); detail what a production value covers; appraiser the appraiser of an insured or estimated value, an agent of agents.csv; document_id its supporting document, a row of documents.csv. Never the internal note.

The other titles have one column per kind: alternate_titles (untyped), original_titles, translated_titles, former_titles, several titles separated by |, the language after a final @ (Night piece@en). former_numbers gives the former numbers, the source in parentheses (42 (Catalogue 1985) | N-7). storage_locations gives the work’s storage locations, the kind in parentheses, as its code (Box 12 (box) | LaCie (hardDrive)): internal information, written only when the export includes the confidential records, empty otherwise; LIDO and CIDOC never carry it. signature_text is a print’s signature text, distinct from the inscriptions; poster and web are 1 when the work is reproduced on a poster or online.

In relations.csv, each relation between two works (see Relations) appears once. relation is related (related work), variant, commonNegative (same negative), sameSession (same sitting), state (another state of the same image) or preparatory: the work of catalogue_number is then the preparatory work of the one of related_catalogue_number; the other relations read both ways. A relation’s note is never in it, nor a relation with a confidential work, except in an export that includes the confidential records.

sales.csv holds each auction sale (see Adding or editing an event) of an event of provenance.csv, and of no other: the sale of a confidential event is only there with the confidential records, confidential then being 1. outcome is sold, unsold or withdrawn; the estimates and the hammer price are in the sale’s currency (currency), with a dot as the decimal mark; premium_included is 1 when the hammer price includes the buyer’s premium, and empty without a hammer price. sale_date is empty when the sale has its event’s date. amounts_confidential (the last column) is 1 for a sale marked Amounts confidential, 0 otherwise: without the confidential records, its estimates, hammer price, premium_included and currency are then empty, as are its event’s amount and currency in provenance.csv.

conservation.csv holds each conservation intervention (see Conservation) on the work or on a print (print_number): kind is restoration, incident or conditionReport, condition (the condition observed) excellent, good, fair, poor or unknown; document_id is a document of documents.csv. A confidential intervention is only there with the confidential records; the cost (cost, currency) is only written in an export that includes the confidential records, even for a public intervention; the internal note never. In works.csv, condition and condition_description give the condition of a work without a print (empty when none is recorded); a print’s is in prints.csv.

rights.csv holds each line of an exported work’s rights (see Rights), in their order (line: 1, 2…): holder is the rights holder (an agent), licence is allRightsReserved, ccBy, ccBySa, ccByNd, ccByNc, ccByNcSa, ccByNcNd, cc0, publicDomain, other or unknown, licence_terms gives its terms, restrictions the reproduction restrictions, expires_on the expiry and expiry_precision its precision. The rights leave with their work (a confidential work’s only with the confidential records), never their internal note. The free rights statement stays the rights_statement column of works.csv.

In exhibition_views.csv, one row per work visible on an installation view (see Installation views), only for an exhibition the work, or one of its prints, hangs in, as exhibitions.csv lists it: the exhibition by its title and dates; position, the view’s place in the exhibition’s strip, from 1 (a removed view can leave a gap); the photo by asset_id, file (its path, as imported) and sha256, as in bibliotheque/files.csv; print_number, the print visible, empty when it is the work without saying which print. A view showing a confidential work (the photo shows it), or whose photo is linked only to confidential works, is in it only with the justified confidential records, each counted in the journal of confidential exports; a view showing a work whose reproduction is excluded is never in it (the photo reproduces it).

In works.csv, state_rank is the work’s state rank (2 for “State II”, empty without a rank), reproduction_exclusion the code of an excluded reproduction’s reason (empty when it is not excluded) and date_argument the dating rationale (see Scholarly notice); the CSV import of works ignores them for now.

works.csv re-imports as is through the CSV import (see Importing a CSV inventory), inventory numbers included; so do exhibitions.csv and publications.csv, with their links and citations. The import reads the codes, and also the French and English labels the versions before 0.19 wrote: a file already exported re-imports.

Formulas neutralised

A spreadsheet runs a cell that starts with = as a formula: a title received from a lab or a Lightroom catalog holding =HYPERLINK(…) would open as a link, or worse. In every CSV Catalog writes (the CSV export, the tables of the full export and of the package for Vault, “Export this table…”, the vocabulary as CSV), a text cell that starts with =, +, @, a tab or a carriage return therefore gets a leading apostrophe ('=HYPERLINK(…)); so does a cell that starts with - without being a number (-12 and -3.5 stay as they are). The spreadsheet then shows the text as it was entered. The columns of amounts, dimensions and codes are never touched.

The CSV import removes that apostrophe, in those cases only: a file exported then re-imported gives back the original texts exactly (see Importing a CSV inventory).

What will not change

These files are a lasting format: a spreadsheet, a script or another program that reads them will keep reading them with the next versions of Obscura Catalog. From 1.0 on:

• the order of the columns of each file is frozen, as the tables above give it, and so are their names. A new column is only ever added at the end of the row; no column is renamed, moved or removed. (In 0.16, inventory_number was inserted as the third column of works.csv and prints.csv: this will not happen again.) A program that reads the columns by name sees no difference; a program that reads them by position only has to ignore the extra columns at the end of the row;
• the codes of the values do not change: a code never takes another meaning and is never renamed; a new value, if a list gets one, comes with a new code;
• a text cell that looks like a formula starts with an apostrophe (see Formulas neutralised), which the import removes: an addition of 0.19.1, which changes neither the order, nor the names, nor the codes of the columns;
• the tables without an import are “export only”: prints.csv, provenance.csv, relations.csv, sales.csv, conservation.csv, rights.csv, documents.csv and exhibition_views.csv, like agents.csv and attributions.csv of the full export, do not re-import in 1.0; these data are entered in the record. An import will come later, as an addition, without changing their columns.

Including confidential records

For an export meant for a specific use (an insurer, a rights holder), tick Include confidential records. Catalog warns: “The files will contain confidential records: parties, transactions, prices. Anyone the files reach can read them.”

A justification is then required. Next to the twelve files, Catalog writes CONFIDENTIAL-EXPORT.txt (EXPORT-CONFIDENTIEL.txt with a French interface), which records the date, the number of works exported and the justification. The tables, the copies of the documents and this note appear together, once the export is complete; the log entry is written at that moment, never for an export that was stopped or failed.

The option only applies to one export: it is unticked, and the justification cleared, as soon as the export is finished.

The field is labelled “Justification (recorded in the audit log)”: the justification is written in CONFIDENTIAL-EXPORT.txt, which goes with the files, and in the library’s Confidential exports log, in Settings › Privacy. Every export that included the confidential records is listed there, newest first: its date, format, justification, the folder it was written to, the number of works exported and what it let out that is confidential, each category as what it is: works, provenance events, documents, values, holders, lenders, storage locations, conservation interventions (confidential ones, or with their cost) and confidential agents (each once). Entries written by an earlier version do not count storage locations, interventions or agents (“Export this table…” then counted a holder as a provenance event). The log follows the library into its backups and cannot be edited. If Catalog cannot write it, the export stays written, with its note, and Catalog says so.

Source, URIs and language of LIDO and CIDOC records

The LIDO and CIDOC records card says, before any export, what both formats will be written with; they are changed in Obscura Catalog › Settings… › Exports, where Record settings… takes you (Save applies them, Revert drops them). These settings belong to the library: they are saved next to its database (export-settings.json), and follow it in its backups and moves.

• Record source (name of the fonds): the institution or fonds publishing the records, written in every LIDO record (recordSource) and at the top of the CIDOC file. When empty, the workspace name is used. One line, 200 characters at most.
• Base URI: the address under which Catalog mints the URIs of works (<base>work/<catalogue number>), prints (<base>print/<print number>), actors and places. Enter the domain of the fonds, starting with https:// (for example https://data.my-fonds.org/catalogue/): without it, the URIs are provisional (https://catalogue.obscura.local/) and point to nothing outside this Mac. Once the address is set, each LIDO work and print record also carries the object’s URI (objectPublishedID of type URI), the same as in CIDOC: both exports name the same object the same way. Catalog refuses an address that is not http:// or https://, or that contains a space, ?, #, user info (@) or an accented domain; the final / is added. Do not change the address once the data is published: a changed URI names another resource.
• Record language: the declared language of the records (xml:lang in LIDO, language tags in CIDOC) and of the labels Catalog writes itself (a print’s edition, in French or English). By default, the interface language. A work whose title language is set keeps that language for its record.

LIDO 1.1

Export LIDO 1.1 (XML)… offers to save <catalogue name>-lido.xml.

LIDO is the exchange format of museums and collections portals. Catalog writes one record per work and per print: identification, creation with the author of the accepted attribution and their authority identifiers, exhibitions, acquisitions from the provenance, linked files. The document follows the official LIDO 1.1 schema. Each record is sourced by the name of the fonds (see above) and declares its profile (see Profile versions). The accepted attributions of the other roles (printer, collaborator, assistant, retoucher, press printer, publisher) are actors of the creation event, after the author: one eventActor each, its role as roleActor (printer, collaborator, assistant, retoucher, press printer, publisher) and, unless certain, its qualifier (attributed to…). An anonymous or unaccepted attribution is not in it, nor its argument. A print’s printer, entered in the print, is in the production of its record.

A work’s record also carries its bibliography (one relatedWorkSet with the relation documented in per citation: the bibliography line, the full reference, the print cited and the quoted passage, with the publication’s ISBN, ISSN or DOI) and, for a work that is not extant, its condition (lost, destroyed…: an objectDescriptionSet of type existence). A print’s record carries its signature (an inscriptions of type signature: signed or stamped, location, date and place), its condition (an objectDescriptionSet of type condition, with the condition note), and the exhibitions and acquisitions that concern it alone; those of the work stay in the work’s record.

The auction sales of publishable events are events of type Provenance, method auction: the sale title (eventName), the auction house (eventActor, role auction house), the date (the event’s when the sale has none), the lot and the outcome (eventDescriptionSet of types lot and outcome), in the record of the work or of the print concerned. Never an estimate or a hammer price.

Public conservation interventions are events of type Restoration (a restoration) or Event (non-specified) (an incident, a condition report), named after their kind (eventName): the conservator (eventActor, role conservator), the date, the description and the condition observed (eventDescriptionSet, the second of type condition), in the record of the work or print concerned. The condition of a work without a print is, like a print’s, an objectDescriptionSet of type condition. Never an intervention’s cost, note or document.

The rights are in rightsWorkWrap, in the work’s record and in each of its prints’ (a print reproduces the work on the same terms): the free rights statement first (creditLine), then one rightsWorkSet per line of rights: the licence (rightsType, its Creative Commons or RightsStatements.org URI as conceptID and its name, “CC BY-NC 4.0”, “In Copyright”; its terms as a second term, or alone for another licence), the expiry (rightsDate, latestDate), the rights holder (rightsHolder, their name and VIAF, ULAN, Wikidata identifiers), the reproduction restrictions (creditLine). Never the internal note.

The catalogue no. identifies the work’s record (lidoRecID, and objectPublishedID once the work is published), the print number the print’s. The inventory no. of a work or a print, when there is one, goes out as repositoryWrap/repositorySet/workID of type inventory number: the number alone, never the holder’s name or address. The former numbers go out in a repositorySet of type former, one workID of type former number each, the source as lido:label. The other titles are alternate titleSets, typed original title, translated title or former title, their language as xml:lang; the history and the analysis, objectDescriptionSets of type history and analysis; the circumstances and the project, eventDescriptionSets of the creation; the film or sensor and the format, typed termMaterialsTechs; a print’s signature text, an inscriptionTranscription of its inscriptions of type signature, before the description. The relations with other works are relatedWorkSets, before the bibliography: the other work by its catalogue no. (objectID of type local, the identifier of its own record) and its title, the relation as relatedWorkRelType (related to, variant of, same negative as, same sitting as, other state of, preparatory for, prepared by), never the relation’s note nor a confidential work.

The states of an image (see Relations): each of the two works names the other with an other state of relation, and a work’s rank, when entered, is its displayState (“State II”, in the language of the records), in displayStateEditionWrap. The other state’s rank is in that work’s own record. An exhibition’s organiser is an actor of the exhibition event, after the venue: an eventActor with the role organizer, with its authority identifiers. The lender of an exhibited object never appears (it is confidential), nor the framed dimensions, the dating justification or the reason a reproduction is excluded; a work whose reproduction is excluded has no image resource in its record.

The installation views the work is visible on (see Installation views) are resources of the work’s record, after its images: one resourceSet per view, the photo by its id (resourceID of type local) and its digest (resourceID of type SHA-256), its path (linkResource), resourceRelType installation view, and a resourceDescription of type exhibition naming the exhibition by the title of its event in the record. Only the views of an exhibition the work, or one of its prints, hangs in; none showing a confidential work or a work whose reproduction is excluded, none whose photo is linked only to confidential works.

Confidential records are always excluded from it.

CIDOC CRM

Export CIDOC CRM… offers to save <catalogue name>-cidoc.ttl.

CIDOC CRM is the reference ontology for cultural heritage. Catalog exports a profile deliberately restricted to twelve classes, correctly filled rather than approximate, its URIs minted under the base URI of the fonds. The file declares its profile at the top (<> owl:versionInfo "obscura-catalog/cidoc-crm/2.1", see Profile versions):

The creation is P14 carried out by the accepted author and the accepted attributions of the other roles (printer, collaborator, assistant, retoucher, press printer, publisher). Each one’s role goes through a PC14 carried out by node (P01i is domain of), which names the actor (P02 has range) and its role (P14.1 in the role of), an E55 Type described once: <base>type/role/photographer, …/printer, …/collaborator, …/assistant, …/retoucher, …/press-printer, …/publisher. An anonymous or unaccepted attribution, or one of a confidential agent, is not in it.

Each actor’s URI is the id of its record in the directory, <base>actor/<id>, and its name is its label (rdfs:label): two namesakes stay two actors, and renaming an agent does not change its URI. Places keep a URI made from their name (<base>place/paris).

An exhibition (<base>exhibition/<identifier>) is described once, with its title, dates and place, and P16 used specific object names each work, or the print exhibited, that it showed. Its organiser carries it out (P14 carried out by), the role given by a PC14 carried out by node (P14.1 in the role of <base>type/role/organizer); never the lender. The bibliography: each citation is an E31 Document (<base>citation/<identifier>) carrying the bibliography line, the quoted passage (P3 has note), P70 documents towards the work or the print cited and P106i forms part of towards the publication (<base>publication/<identifier>, its full reference and identifiers). An acquisition that concerns a print alone transfers the title of that print (P24). The relations with other works: a variant and a work from the same negative P130 shows features of the other work, and a PC130 shows features of node says which of the two through P130.1 kind of similarity (<base>type/similarity/variant or <base>type/similarity/same-negative); two states of the same image likewise, with <base>type/similarity/state, and a work’s rank among the states is a note of the work (P3 has note “state: 2”); a related work or one of the same sitting rdfs:seeAlso it; a preparatory work P15i influenced the creation of the work it prepared, which carries P15 was influenced by. Neither a relation’s note, nor a confidential work.

An installation view (<base>view/<identifier>) is an E36 Visual Item, described once, after the exhibitions: it P138 represents the exhibition (its E7 Activity) and each object visible on the view, the work or the print visible; a note installation view (P3 has note) says what it is, the photo’s digest is its skos:notation. P138 represents rather than P62 depicts: P62 starts from a physical object (E24), and the view is an image, not a print of it. No path: CIDOC carries no image. Only the views of an exhibition the work hangs in; never a view showing a confidential work or a work whose reproduction is excluded, nor a photo linked only to confidential works.

An auction sale of a publishable event, without another class: an E7 Activity (<base>work/<catalogue no.>/sale/<n>, a note auction) that P16 used specific object the work or the print offered, P14 carried out by the auction house, with the sale title, the lot (“lot 42”) and the outcome (sold, unsold, withdrawn) as P3 has note, and its time-span. Never an estimate or a hammer price.

A public conservation intervention, without another class: an E7 Activity (<base>work/<catalogue no.>/conservation/<n>, its kind as rdfs:label: restoration, incident, condition report) that P12 occurred in the presence of the work or print concerned, P14 carried out by the conservator, with the description and the condition observed (condition: good) as P3 has note, and its time-span. Never the cost, the note or the document. The current condition of a work or a print has no class in the profile: it is in LIDO and the CSV.

A work’s rights: each rights holder once, P105 right held by on the work (the CRM’s shortcut for a right held), and each line as a P3 has note (“rights: CC BY-NC 4.0; holder: …; restrictions: …; expires: 2071”). The free rights statement is an E30 Right (<base>work/<catalogue no.>/rights, the statement as rdfs:label) the work is subject to (P104 is subject to). Never the internal note.

LIDO and CIDOC profile versions

What Catalog writes in LIDO and CIDOC follows a versioned profile, which each file declares: lido:applicationProfile (obscura-catalog/lido/1.2) in each LIDO record, owl:versionInfo (obscura-catalog/cidoc-crm/2.1) at the top of the Turtle. Each format has its own version. An addition (an element, a property, a role, a type) makes a minor version: a tool that reads the previous one still reads what it knows. A change that would read differently (a moved, renamed or removed element, a URI minted differently, a changed meaning) makes a major version, announced in the release notes.

• LIDO 1.0 → 1.1 (0.20.0): an addition. The states of an image (other state of, displayState) and an exhibition’s organiser (organizer).
• CIDOC 1.0 → 2.0 (0.20.0): a change in reading. An actor’s URI comes from the id of its record, no longer from its name (<base>actor/henri-x becomes <base>actor/<id>): in 1.0, two namesakes were a single actor, and renaming an agent changed its URI. The states (<base>type/similarity/state, the note “state: 2”) and an exhibition’s organiser are added. A tool that kept the 1.0 URIs matches the actors by their name and authority identifiers.
• LIDO 1.1 → 1.2: an addition. The installation views, installation view resources of the work’s record.
• CIDOC 2.0 → 2.1: an addition. The installation views, one more class (E36 Visual Item) and one property (P138 represents).

A work’s catalogue no. and a print’s number are untyped skos:notations; an inventory no. is a skos:notation typed <base>notation/inventory-number, so it is never taken for them, a former number a skos:notation typed <base>notation/former-number. The other titles are skos:altLabels in their language; the history and the analysis, crm:P3_has_notes of the work; the circumstances, the project, the film or sensor and the format, crm:P3_has_notes of the creation.

Confidential records and internal notes are always excluded from it.

Attached documents

The documents of the work and of its prints (the record’s Documents tab, see Documents), then those of the files linked to the work (see Attached documents) go into all three exports with the work: a document attached to a file linked to two works appears under each.

The internal note of a document of the work never leaves.

Confidentiality. A document is confidential:

• when its Confidential box is ticked (in the record’s Documents tab, or in the file’s Edit…, see Attached documents); it starts ticked for a new invoice, which carries prices and parties;
• when it serves as the proof of a confidential provenance event, whatever its box says, as long as the event is: publishing the proof would publish the event;
• when it serves as the proof of an event whose sale is marked Amounts confidential, whatever its kind and its box, as long as the sale’s box is ticked: a hammer-price slip carries the amounts it withholds;
• when it is the document of a confidential conservation intervention, whatever its box says, as long as the intervention is;
• when it is the supporting document of a value of a print (an expert’s report, an insurance schedule), whatever its box says, as long as it supports it: a value is always confidential;
• the documents of a confidential work do not leave any more than it does.

Other documents leave with their work, an unticked invoice included. Confidential documents only go into the CSV (and the tables of the full export or of a package), with Include confidential records (confidential column set to 1); never into LIDO or CIDOC.

The files themselves. By default, an export describes the documents (title, kind, size, SHA-256 fingerprint) without copying their files: the fingerprint lets the receiver check the file you send separately. Tick Copy the document files next to the export (Attached documents card) to include them:

• CSV: in the documents/<document identifier>/<file name> folder next to the tables; the export_path column of documents.csv gives that path;
• LIDO and CIDOC: in a <file name>-documents/ folder next to the saved file (<file name>-documents (2)/ when that folder already exists: an export never mixes its copies with another’s); the LIDO record points to it (linkResource), and so does CIDOC (rdfs:seeAlso, a URI relative to the Turtle file).

The copies kept by the library (Documents/ folder) are what is copied, those of the work’s documents as well as the files’; the full export always copies them into documents/. A document whose copy is missing is described without a file, and the export’s report says so.

The codes of the values

The value of each list as the CSV files write it (the code), and its label on the screens. The CSV import reads the code as well as the labels, in French and in English, case and accents ignored.

Precision of a date — works.date_precision, provenance.date_precision, conservation.date_precision, rights.expiry_precision

Existence of the work — works.existence

Status of the record — works.status

Certainty of an attribution — works.attribution (the accepted attribution), attributions.certainty

Role of an attribution — attributions.role

Condition — works.condition, prints.condition, conservation.condition

Reason for an excluded reproduction — works.reproduction_exclusion (empty: the reproduction is not excluded)

Kind of storage location — works.storage_locations (in parentheses: Box 12 (box))

Edition kind — prints.edition_kind

Print period — prints.print_period

Signature — prints.signature

Print status — prints.status

Citation kind — publications.citation_kind

Publication kind — publications.publication_kind

Provenance event — provenance.event

Transaction kind — provenance.transaction

Document kind — documents.kind (and bibliotheque/documents.csv)

Relation kind — relations.relation

Outcome of a sale — sales.outcome

Intervention kind — conservation.kind

Licence — rights.licence

Value kind — valuations.kind

Source or channel of a value — valuations.source

Agent kind — agents.kind

Agent role — agents.roles (several, separated by |)

In short: what leaves, and what stays

Reports and certificates follow the same rule with no option: nothing confidential is printed in them, nor a confidential agent, nor any amount (see Reports and What the certificate contains).

Good to know

• The full export carries the twelve tables of the CSV export unchanged: a script written for one reads the other. The export of a package for Vault has eleven: the installation views are not in it yet.
• Each CSV export has its own dated folder: two exports into the same folder never mix, and a public export never inherits the documents or the note of an earlier confidential one.
• The interface language changes nothing in the files of the CSV export and of the full export: their values are codes (see The codes of the values).
• LIDO and CIDOC exports are written in the language set in Settings › Exports, the interface language by default (see Source, URIs and language).
• Confidential documents (an invoice, by default) only leave with the confidential records, in the CSV, the full export or a package’s export (see Attached documents).
• Agents’ authority identifiers (VIAF, ULAN, Wikidata, ISNI, ORCID) make LIDO and CIDOC exports far more useful to an institution: fill them in (see Agents).
• A provenance event is confidential until you untick “Confidential” in its editor: it then appears neither in LIDO nor in CIDOC, and only appears in provenance.csv if you include confidential records. Once publishable, it goes in; its amount is only in provenance.csv (see Provenance).