Getting started

Ten minutes from a file on your disk to editing it through a view of your choice.

Run it, or install it

run.arspec.app is the whole editor in a browser tab, with nothing to install, and the quickest way to see whether Arspec suits you. It opens files you pick or drop on the window. Because a web page cannot write to your disk, it saves by handing you a copy to download.

The desktop apps for Windows, macOS and Linux, and the phone apps, add automatic saving: your edits are written back to the file shortly after you stop making them. The desktop apps can also connect to the AI chat you already use.

Open a file

The sidebar's Topics header has two buttons. Load source opens a box where you can paste an http(s) URL and press Enter, or pick one or more files with the system's file dialog. Dropping files anywhere on the window does the same. Open topic is for a .arspec file you saved earlier; more on those below.

Arspec reads Turtle (.ttl), N3, RDF/XML (.rdf), OWL/XML (.owl, .owx), JSON-LD (.jsonld), TriG (.trig), N-Quads (.nq), and plain JSON (.json), YAML (.yaml), TOML (.toml), XML (.xml) or a table (.csv, .tsv), each object, mapping, table, element or row of which becomes an anonymous node and each field, key, child element, attribute or column a property. It recognises a file by its content, not its name, so a URL without an extension opens as whatever it is. When a file imports other files that sit beside it, those are opened too and appear nested under it. A large file, or a slow one, shows its progress in a small dialog as it is downloaded and read, with a Cancel button that stops that file and lets the others of the same batch go on.

In the browser, the address of the page can name the file: run.arspec.app/?f=address opens with that file loaded, as if you had pasted the address into Load source, so a link to an ontology can be a link to it open in Arspec. A .arspec named this way opens as the topic it is, with the files it covers — that is what the demo link does. The https:// may be left off, a second f= opens a second file, and an address with a query of its own goes in URL-encoded. The server the file is on has to allow pages from other sites to read it (CORS); most that publish ontologies do.

To add one yourself, right-click a file's row (long press on touch). Import file… opens your system's file dialog; Import URL… opens a box for an address you type or paste. Either way Arspec writes an owl:imports into the document, and if the document has not yet said that it is an ontology, it says so now. A file that lives near the one importing it is named by the way to it rather than by its full path, so the two keep finding each other when the folder is copied somewhere else. The imported file then opens under the row.

A file with named graphs — TriG, N-Quads, or JSON-LD with @graph under an @id — shows each graph as a row under the file, marked with a small hub icon. The file's own row reads all of its graphs together; a graph's row opens that graph on its own. Right-click a graph's row to Rename it, Erase its statements, or Delete the graph whole; each is one step in the file's history, so Undo takes it back. Copy all triples, on a graph's row or a file's, copies everything the graph says, and Paste triples on another row puts it there — asking first, with the count and where the triples came from — without doubling what is there already. Mark as temporary keeps a graph in the session only: you read and edit it like any other, but it is left out of the file at the next save, which with automatic saving on is right away; Mark as persistent puts it back. A temporary graph's row shows a hollow hub. New graph… on a file's row makes a graph of the file: a word alone names it under the file's own address, and a prefixed name, an IRI or _:label names it where that says; ticked temporary, it is the session's from the start. In a file whose format has no room for a named graph — Turtle, say — the box comes ticked, and unticked the dialog says what a persistent graph means there: the next save asks whether to keep the file as TriG.

Topics: files and views that belong together

Every file you open belongs to a topic. A topic remembers which files go together, which views are switched on for each, and any views you have made for them. In the sidebar, each topic is shown with its files beneath it. Select a file and its views open as tabs.

You do not have to set a topic up. When you open a file, Arspec makes a topic for it in its own storage, so you can look at a file without deciding where anything should be kept. When a topic becomes worth keeping, use Save topic as… to write it as a small .arspec file wherever you like. The files stay where they are, and the topic refers to them. Save topic and sources as… copies the files too, into one folder, for a topic you want to hand to someone else.

The built-in views

Each tab above a file is a view, called a perspective. These come with the app:

The gear at the end of the tab strip opens the perspectives screen. It lists every view available for the file, whether built in, kept in the file, in the topic, or in your own profile, with a switch for each and a Create one… button. Each view has its own gear that opens its editor.

Selecting: the cursor

One row or one list is selected at a time, and a frame is drawn round it. The first click on a row selects it; the next click does something: on a field, what that field is set to do (edit it, or open the row); on the row’s free space, open or close it. So you can click around a file to look at it without changing anything or unfolding things by accident. A click on a list’s heading selects the list. A click outside every row and list — on the view’s title, on empty space, or on the tab you are already on — selects the view as a whole, which draws no frame.

With the keyboard: ↑ and ↓ move among the rows of a list (or among the lists under a row). At the top of a list ↑ goes out to what holds it; at the bottom ↓ carries on to whatever comes next further out, so holding it down walks the whole view. With the view as a whole selected, ↓ goes to its first row and ↑ to its last. ← goes out to the list or the row that holds the selection, → goes into the first row of a list or the first list under a row, and Enter does what a click on the selected row does. While a field is open for editing the keys are the field’s.

The same moves are under the left hand, which leaves the right on the mouse: W A S D are ↑ ← ↓ →, and Space is Enter. In a list that keeps an order of its own, Alt+↑ and Alt+↓ (or Alt+W and Alt+S) move the selected row up and down it, as Move up and Move down in its menu do. All of these can be changed: see Keys.

What is selected is also what the assistant takes “this” to mean.

Editing

Click a term of the selected row to edit it where it stands. The cell on the left of the field says what kind of thing it is: a namespace, a kind of value (str, num, bool, datetime), a blank node, or a full IRI typed as is. The field takes the name or the value and suggests names that already exist in that namespace. Pick the blank node and the field empties: leave it empty and the node is given an id of its own when you save, or type a label if you want one. Enter saves the change and Escape reverts it. If you rename something to a name that already exists, Arspec asks what you meant: merge the two, replace one with the other, or cancel.

Right-click (long-press on a phone or tablet) for a menu, and what you get depends on what you pressed. On a term: edit it, open it with another view, copy its text — and then everything its row offers. On a row’s free space or its label: expand it in place or open it on its own page, insert a row (above it, in a list that keeps an order of its own; into the list otherwise), copy the row with everything under it, paste rows into its list (above it, likewise, where the list keeps an order), move it up or down, delete it. On a list — its heading, the space between its rows, or the empty space of the view for the top-level list: add a row to its end, copy or delete all of its rows, paste rows in at its end. A new row is made of the kind its list shows, already matching the list’s conditions. Deleting a row removes it, the rows nested under it, and any anonymous nodes that would be left dangling; every action is one step to undo.

The same actions stand as buttons in the action bar floating at the foot of the view, for whatever is selected — the row, or the list — where the perspective puts them there (its Actions settings; every action of a new list starts in the bar). Hover a button for its name and its keys. The digits 1 to 9 and 0 press the bar’s buttons by their place from the left, so the first button is always 1 whatever action stands there; deleting a whole list is the one button no key presses. The Actions page has each action in full, what it does on a record and on a list, and how a view gets actions of its own.

Copying and pasting carry rows of one list, with everything nested under them — what an invoked view shows under a row included, as far down as it goes — and land in any list of the same kind: under another record, or in another file opened with the same view. Anonymous nodes come along as new anonymous nodes, with everything said about them. Rows that are already there are not added twice, with one exception: in a list of distinct items (Distinct by), pasting an item the list already has makes a copy of it under a new name, alice becoming alice2.

Every change is one step in the undo history: Ctrl+Z and Ctrl+Y, or the two arrows in the app bar. Renaming a prefix is one step, and so is deleting a namespace together with everything declared in it.

Looking into an item

On the selected row, click its name to expand the record. It shows anything the view reserves for an opened record. Open expanded puts the record on a page of its own instead. From there you can keep expanding and following references, and come back with Alt+← (⌘+[ on a Mac), the mouse's back button, or the arrow in the app bar.

Where a view opens other views about the item, as Attributes does under every subject, the expanded record gets a row of tabs, one per lens the view names, opened on the first that has something to show. A gear beside them lets you tick more lenses for that record. Open term with… on a term's menu opens a lens about that one term on a page of its own.

Opening a record

A selected row that has statements underneath it opens on a single click: click its name, or anywhere along its top line that is not a field of its own, and the record opens. Click again to close it. Fields keep their own click, so one set to be edited still opens its editor rather than the record around it. The frame stays where it was either way: it marks the selection, not what is open.

Finding a term

The magnifier in the app bar opens a search field. Nothing is hidden: every term whose name or prefix contains what you typed is highlighted where it stands, the field says how many there are, and Enter or the arrows beside it step through them, scrolling each into view. Shift+Enter steps back.

Keys

Preferences → Key Bindings lists every key Arspec answers: moving the cursor and the selected row; the standard actions on what is selected — Insert or + to add a row, Del or Backspace to delete the selected record, Ctrl+C and Ctrl+V to copy and paste, E or Shift+Enter to expand a record in place and collapse it again, Ctrl+Enter to open it on its own page; applying and cancelling an edit; undo and redo; going back and forward; stepping through a search; and the action bar’s ten places, 1 to 0. A whole list is deleted from its menu or its button only, never by a key: the cursor rests on the top-level list whenever nothing else is selected. Each has two places for a key, a main one and an alternative, and either does the same. Click a key, then press the key or the combination you want instead. If another command already has it, Arspec says which and asks before taking it; Esc leaves things as they were. Restore defaults puts everything back.

The keys this page mentions are the defaults on Windows and Linux. On a Mac the defaults are the Mac’s: ⌘Z and ⇧⌘Z to undo and redo, ⌘[ and ⌘] to go back and forward, ⌥↑ and ⌥↓ to move a row. Letters on their own, like W, can only be given to the cursor and the row: everything else has to work while you are typing, and needs Ctrl, Alt or a key that types nothing. What you change is saved with the rest of your preferences, and travels with them when you export them.

Saving

On a desktop, Preferences → General → Files → Save changes automatically is on by default. Edits are written back shortly after you stop, and a save that fails shows a notice in the status bar with a Retry button. Switch it off and a save button appears instead. In the browser there is no writing back to disk: Save as… on a file's row downloads a copy.