Concepts

This section explains what fylr is built out of. The same words show up everywhere — in the user interface, in the admin screens, in plugin manifests, in the API documentation — so it pays to read these pages once before working with the API.

The pages are ordered. Each one only uses words that earlier pages introduced. The prose stays at vocabulary level; each page ends with an In the API block that maps its terms to what requests and responses actually say.

Coming from a classical DAM

In most DAM systems the asset is the central object: a file, with metadata attached to it. fylr inverts this. The central object is the record — a structured set of fields — and files hang off the record in fields of type file. A record can carry no file at all (a person, a location, an exhibition), one file, or many. What a classical DAM calls an asset corresponds in fylr to a record with a file field; the metadata is not a description attached to "the file" but a record in its own right, which references its files.

Because the metadata lives on the record, several files share one set of it: the front and back of a postcard are two files in one record — where a classical DAM holds two assets with duplicated metadata. See Files and assets for the two forms this takes (variants in one file field, nested rows per file).

Rough equivalences, each explained on its page:

Classical DAM	fylr
Asset (file + metadata)	Record with a file field
Related assets with duplicated metadata (front/back, detail shots)	One record holding several files (variants or nested rows)
Asset type, metadata schema	Objecttype in the datamodel
Derivatives, proxies, previews	Renditions of an original
Workspace, archive	Pool tree — the permission container a record lives in
Folder tree, category tree, taxonomy	Hierarchical objecttype the record links to
Lightbox, basket, share set	Collection
Metadata form, view	Mask
Keywords, labels, flags	Tags

One term is a known trap: in fylr, a version is a record's metadata version, not a file derivative. The derived files are renditions — see Files and assets.

Read in this order

1. Records and objecttypes — start here. What is a record? What is an objecttype? How do they relate?

2. Files and assets — files versus records; a file field holds variants; originals and renditions.

3. The datamodel — the schema for all your objecttypes. Versions, HEAD vs CURRENT, how changes are committed.

4. Hierarchies and polyhierarchies — when objecttypes form trees; single-parent vs multiple-parent.

5. Nested and reverse-nested tables — rows that live inside another record instead of standing on their own.

6. Pools — the primary container for live objects. Pool trees, what inherits down.

7. Masks — different views of the same objecttype. Mask hierarchy. The "preferred" mask.

8. Permissions — who can do what, where. System rights, ACL grants, right presets.

9. Tags and transitions — tags, tag filters, workflow transitions.

10. Collections and publishing — collections, presentations, share links, deep links.

11. Search and events — how search differs from direct lookup; the event log; change history.

After these pages, the API reference is the natural next step.

How these pages are written

• Plain English, vocabulary level. The prose explains the concepts; field names and endpoint paths are confined to the In the API block ending each page.

• One concrete example per concept, drawn from a real-world use case (museums cataloguing photos, retailers cataloguing products, an archive of articles).

• fylr is the easydb 6 product line — a Go rewrite that keeps the easydb 5 API contract. easydb 5 comes up only when it explains historical naming.

See also

• API reference — the endpoints these pages give you the vocabulary for.

• Glossary — one-line definitions of every term used here.

• FOR ADMINISTRATORS — administering the concepts described here.

• FOR USERS — the interface guide.