User guide

This page introduces the concepts you encounter while using shepard. It is descriptive, not exhaustive — the live API explorer at /shepard/doc/swagger-ui is the source of truth for fields and parameters.

Collections

A Collection is the top-level container. It carries a name, a description, free-form attributes, an owner, and a Permissions record. Everything you store lives inside a Collection.

Screenshot: Collections page — placeholder. Replace with Playwright capture once the visual-regression workflow lands.

REST surface: CollectionRest (backend/.../context/collection/endpoints/CollectionRest.java).

DataObjects

A DataObject lives inside a Collection. DataObjects form two relationships:

parent / child — composition. A parent DataObject groups its children; children inherit nothing automatically, but the tree shape is what the UI and most clients walk.
predecessor / successor — derivation. A DataObject can declare one or more predecessor DataObjects (predecessorIds) under the same Collection, marking “this was derived from those”.

REST surface: DataObjectRest (backend/.../context/collection/endpoints/DataObjectRest.java).

References

A Reference is a typed pointer attached to a DataObject. The reference kinds verified in source today (under backend/src/main/java/de/dlr/shepard/context/references/.../endpoints/):

Kind	Class	Stores
File	`FileReferenceRest`	Files (binary), backed by MongoDB GridFS
Structured-Data	`StructuredDataReferenceRest`	JSON documents, MongoDB
Timeseries	(under `data/timeseries`, see `TimeseriesRest`)	Channels in TimescaleDB
Spatial-Data	`SpatialDataReferenceRest`	Geometries in PostGIS (optional)
URI	`URIReferenceRest`	External URIs
Lab-Journal	(under `context/labJournal`)	CommonMark + GFM markdown entries; see Lab journal reference
Video	`VideoStreamReferenceV2Rest`	MP4/WebM video files + ffprobe metadata, backed by MongoDB GridFS; see Video stream references
Collection / DataObject	(cross-references)	Links between entities

Basic vs advanced mode

Every user can toggle a personal Advanced mode preference (icon in the top-right of the app bar). The two modes are about information density, not feature gating:

Basic — reduces friction. Hides internal numeric ids in metadata strips, hides operator-flavoured panels (Snapshots, Publishing on Collections; Provenance Graph on DataObjects). Default for fresh accounts.
Advanced — same content, plus the dev knobs: numeric ids, Snapshots, Publishing (PID / Handle minting), the full Provenance Graph visualisation.

Annotations, descriptions, attributes, references, lab-journal entries, and lineage are visible in both modes — they’re primary research content, not implementation details.

The preference is stored at /v2/users/me/preferences so it follows the user across browsers.

Permissions

Per backend/src/main/java/de/dlr/shepard/auth/permission/model/Permissions.java the model is:

An owner (single User).
Lists of manager, writer, and reader users.
Lists of readerGroups and writerGroups (UserGroup).
A permissionType from backend/src/main/java/de/dlr/shepard/common/util/PermissionType.java: Public, PublicReadable, or Private.

Effective access is therefore:

Owner — full control, including delete and permission changes.
Manager — same as Owner except cannot reassign ownership.
Writer — read + write (and via group writer, read + write).
Reader — read-only (and via group reader, read-only).
PublicReadable — anyone authenticated may read; only listed writers/managers may modify.
Public — broader read; specifics governed by the visibility flag.
Private — only the explicit lists apply.

Task guides

Step-by-step walkthroughs for common tasks:

MFFD digital-thread tour — a 10-minute guided walk through the MFFD showcase data (live links)
Plot timeseries data — interactive charts, zoom/pan, channel selection, container-level previews
Explore collection lineage — parent/child and predecessor/successor graph
Trace dataset provenance — who acted on a dataset and when
Upload data — files, JSON, CSV
Monitor collection activity — activity sparklines
Publish a data object — lifecycle publishing
Publish to Helmholtz Unhide — federated harvesting
Annotate a container with semantic tags — attach ontology terms to a timeseries / file / SD container
Delete a container that has references — the safe-delete warning and what “orphaned references” mean

Search

A REST search endpoint exists at SearchRest (backend/.../common/search/endpoints/SearchRest.java). A unified /search/v2 surface and richer query semantics are proposed in aidocs/13 and are not yet shipped — use the existing endpoints documented at /shepard/doc/swagger-ui until the v2 design lands.

API explorer

For exact request and response shapes, point your browser at https://your-host/shepard/doc/swagger-ui (path confirmed from application.properties: quarkus.http.non-application-root-path=/shepard/doc, quarkus.swagger-ui.always-include=true). The OpenAPI document itself is at /shepard/doc/openapi.json.

Per-shelf OpenAPI documents

This fork additionally exposes two filtered views of the OpenAPI document, so a generated client can pin to a single API shelf:

/shepard/doc/openapi/v1.json — the upstream-compatible /shepard/api/... surface only. Build a client against this if you want to stay byte-compatible with gitlab.com/dlr-shepard/shepard.
/shepard/doc/openapi/v2.json — this fork’s /v2/... development surface only (P-series, R-series, U-series profile, lab journal, git integration, templates, …). Build a client against this if you only consume the additive endpoints and want a smaller client.

Both endpoints support ?format=yaml for YAML output (default is JSON) and are public, mirroring the combined /shepard/doc/openapi.json — no auth needed to fetch the spec. The combined document keeps working unchanged.