Concepts & lifecycles

The GEO Knowledge Hub organises content around two core entities, Knowledge Packages and Knowledge Resources. Both share the same underlying record model (metadata, files, versions, access control) but play different roles in the publication workflow.

This page describes each entity, the role-based permissions that gate access, and the draft to published lifecycle that REST API workflows follow.

User roles

The API recognises two different roles to manage and use content in the GEO Knowledge Hub: User and Knowledge Provider. The table below summarizes the permissions associated with each role.

Role	What it can do
User	Search, view and download public content. Authenticated users can additionally leave comments and feedback. No special role is required — accounts are created by signing up.
Knowledge Provider	All of the above, plus create, curate and publish Knowledge Packages and Knowledge Resources, and manage their files and versions. Granted upon request.

Entities

Knowledge Package

A Knowledge Package is the top-level sharing unit. It represents a complete Earth Observation application, bundling all the materials needed to understand and reproduce it.

Atomic: one Earth Observation application per package.
Versioned: every change after publication produces a new version.
Immutable once published: files and resources cannot be altered; a new version must be created instead.
Citable: each version is linked to a DOI, either reused from an existing identifier or minted on publish via DataCite Fabrica.

A Package tracks its associated Resources through relationship.resources. Each entry references a Resource by its record id:

{
  "relationship": {
    "resources": [
      { "id": "zyfzk-d2485" },
      { "id": "abc12-xy345" }
    ]
  }
}

Knowledge Resource

A Knowledge Resource is the building block of a Knowledge Package. It represents a single material, like a dataset, processing script, computational environment, or document that be associated with one or more Packages.

Resources are versioned independently and can be assigned a DOI via DataCite when published. When a Resource is associated with a Package, and it is only published when the Package is published.

A Resource tracks its parent Package through parent.relationship.managed_by. This field is set automatically when the Resource is associated with a Package:

{
  "parent": {
    "relationship": {
      "managed_by": {
        "id": "g5xwf-hwy26"
      }
    }
  }
}

Community

A Community groups Packages and Resources around a specific topic or GEO Work Programme Activity. Communities provide a shared space where Knowledge Providers collaborate, and where curators review and organise content before publication. Communities are inherited from InvenioRDM. See the InvenioRDM Communities API for the full reference.

Lifecycle

Both Knowledge Packages and Knowledge Resources follow the same two-state lifecycle: Draft and Published.

Knowledge Package and Knowledge Resource lifecycle. Editing a draft keeps it a draft; publishing promotes it to Published; a new version creates a fresh Draft from a Published record.

There are some important considerations to keep in mind when working with the lifecycle:

(1) A Draft is private to its owners. They can freely edit metadata, upload or remove files, change associations and delete the draft outright.

(2) A Published record is public and immutable.

(3) Files and (for Packages) Resources within a Published record cannot be modified. Metadata can still be edited at any time without creating a new version.

(4) To change files or resources after publication, you create a new version, which starts as a fresh Draft. The previous version remains intact and accessible.

Allowed operations per state

The same constraints apply to both Knowledge Packages and Knowledge Resources, with one important difference: a Resource that is associated with a Package is published together with its Package, not independently.

Knowledge Package
Knowledge Resource

Draft — what you can do

Edit metadata
Upload or remove files
Associate or dissociate Resources
Delete the draft

Published — what you can do

Edit metadata only

Files and Resources are immutable. To change content, create a new version. A DOI is minted on publish via DataCite Fabrica.

Common record shape

All records, Packages and Resources, share the same top-level fields. The table below summarises them. See Metadata schema for the field-level details.

Top-level field	Description
`id` / `pid`	Internal persistent identifier for this specific version.
`parent`	Links all versions of a record; holds ownership and Package association.
`pids`	External persistent identifiers: DOI (DataCite), OAI-PMH, Handles. System-managed.
`access`	Visibility: `public` / `restricted` plus optional embargo.
`metadata`	Descriptive fields (title, creators, dates, subjects, locations, …).
`files`	Associated file entries plus the `enabled` flag.
`relationship`	Links between Packages and Resources.
`assistance_requests`	Feed or training session requests (Packages only).

The metadata structure aligns with the DataCite Metadata Schema v4.x with GEO-specific extensions (geo_work_programme_activity, engagement_priorities, target_audiences). See the Metadata reference and Vocabularies overview for the controlled values used by these fields.

Where to go next

1) Examples: end-to-end publishing recipes and search query patterns that put the lifecycle above into practice.

2) Common endpoints: cheat sheet of the most-used operations, deep-linked into the OpenAPI reference.

3) API reference: interactive OpenAPI specs for every endpoint.