In short
Publishing happens in three moves: fill in the entity’s identity — author, organization, version, licence —, push it to a public git repository, then request its addition to the catalog. Linkr structurally guarantees that no connection credential and no patient data travels with it, but the remaining checks are yours.
Why publish
A database schema, a mapping of codes onto a standard vocabulary, a set of quality checks: this work takes time, and it is redone identically at every institution. Publishing it spares that repetition to those who come after.
For research work it is also a way of making a method verifiable. A cohort published with its criteria can be read, discussed and replayed on another population.
Publishing does not distribute your data
What leaves is your work: definitions, scripts, documentation. Patient data is excluded by construction — see Import and export.
Step 1 — fill in the identity
An entity published without an author or a licence is hard to reuse: nobody knows whom to credit or what they may do with it. Three places to fill in before distributing.
The author and the organization
The entity’s edit window carries an Attribution tab, with two fields: Author and Organization.
Both are locked by default and show the original value greyed out. The padlock opens the choice — deliberately so: re-attributing work is a rare gesture, and it should be a deliberate one.
Unlocking counts as re-attribution
Opening the padlock saves the value on display, even if you then change nothing. To keep the original author, leave the field locked.
The Attribution tab only appears when editing
On creation the author is necessarily you: there is nothing to re-attribute. The tab therefore appears only when you edit an existing entity.
ORCID, to be cited
The ORCID identifier is not entered on the entity but on your profile. It then travels automatically with everything you publish.
It has a concrete use beyond citation: ORCID is how another Linkr instance recognises the author of an imported entity, and credits you properly instead of crediting whoever imported it.
The version
The Metadata tab carries a Version field, in semver format — 0.1.0 by default — with three buttons offering the next number.
That number matters beyond tidiness: the catalog compares it with the copy installed on your users’ instances to offer them an update. An entity with no version never signals that it has moved on.
Step 2 — choose a licence
Without a licence, nobody has the right to reuse your work. The application says so plainly: “No license yet. Without one, others have no legal permission to reuse this content.”
Every entity has a License tab and a Choose a license button, which opens a choice of twelve licences grouped by family, each summarised in one line.
| Family | What it implies | Examples |
|---|---|---|
| Permissive | Do anything, keeping the copyright notice. | MIT, Apache 2.0, BSD 3-Clause |
| Weak copyleft | Modified files stay open, the rest may be combined freely. | MPL 2.0 |
| Copyleft | Derivative works must ship under the same licence. | GPL 3.0, AGPL 3.0, EUPL 1.2, CeCILL 2.1 |
| Data & content | Designed for datasets and documents rather than code. | CC BY 4.0, CC BY-SA 4.0, ODbL 1.0 |
| Public domain | No condition at all. | CC0 1.0 |
A thirteenth option, Custom license, lets you write your own terms in markdown — useful for institution-internal use, for example.
Which family for what
For a schema, an ETL pipeline or a plugin — code —, the permissive and copyleft licences fit best. For a data catalog or an open dataset, the Creative Commons and ODbL licences are made for it. EUPL and CeCILL are worth a look in a European or French context, where they stand on firmer legal ground.
The chosen text is stored as is and travels in the export as LICENSE.md, which GitLab and GitHub recognise and display automatically.
The readme
Every entity also carries a readme, written in markdown and exported as README.md. It is the first thing a visitor reads on the repository, and what the catalog displays.
Say there what a metadata table cannot: what this work is for, which data it was built on, its known limits, and what has to be adapted to reuse it elsewhere.
Step 3 — publish to a git repository
A catalog entry points at a git repository, so your work has to be there first.
From the entity’s menu, Versioning opens the Git repository tab. You give it the repository URL and, if it is private, an access token. Linkr verifies the remote before saving, detects the branch, and Commit & push sends the content.
The repository must be publicly clonable
Installing from the catalog presents no credentials: every instance must be able to clone the repository anonymously. A private repository produces an entry nobody can install.
Linkr does not check this for you — that is the point to verify yourself before proposing the entry. The catalog will flag an entry that has become Unreachable after the fact.
The access token never leaves
It is kept for you, per host, and appears in no export and in no repository. See Git versioning.
Step 4 — request addition to the catalog
The catalog is a git repository holding one description file per published entity. Adding yours is done through a merge request on that repository.
The Catalog page carries the link at the foot of its header: “Want to share your own work? Open a merge request on…”
Your file describes the entry: its identifier, its type, the repository address and branch, its name and description, the author and organization, the licence, the version and some tags. The existing entries serve as a model.
Why a review rather than a button
The catalog is a shared shelf: what sits on it is installed in one click by teams who do not know the author. Going through a review is what makes it possible to check that the repository really is reachable and that the entry describes what it claims.
An assistant that would pre-fill that file from the entity is under consideration, but does not exist today.
What Linkr guarantees, and what is left to you
Guaranteed by construction
- No password, token, host or database name travels in an export.
- Data files are excluded, unless explicitly marked file by file.
- An exported database carries not a single row.
- Execution results — counts, attrition — do not travel.
For you to check
- That the repository really is public and clonable without credentials.
- That no file marked “for versioning” holds sensitive data.
- That your scripts carry neither credentials nor internal paths.
- That you are allowed to publish this work, under your institution’s rules.
A public database is filled by hand
Publishing an open dataset — synthetic data, a demonstration — means adding the files to the repository outside Linkr. The application never writes rows into an export, precisely so that it cannot become the path by which patient data escapes.
Publishing outside the catalog
Not everything deserves to be indexed publicly. Two common uses do without it:
- A shared repository with no catalog entry — your colleagues import it through the From Git tab, with a token if the repository is private. This is the usual route for institution-internal content.
- An internal catalog — an institution can point its instances at its own index. See Community catalog.
Plugins carry a "Publishing" setting
A plugin’s settings window offers Listed or Unlisted. It is a hint written into the plugin for the catalog’s benefit, not an access control: it restricts nothing within your own installation.
Going further
- Community catalog — what your readers will see.
- Import and export — exactly what an archive contains.
- Git versioning — linking a project to a repository and pushing to it.
- Entities and sharing — lineage identity, and why it matters for a published entity.