Skip to content
GEO Knowledge Hub

Publishing a Knowledge Package

A Knowledge Package bundles one or more Knowledge Resources together. The flow mirrors a Resource’s, with two extra steps: associating Resources to the Package and (optionally) importing them into a future version.

The next steps show you can use the Rest API to publish a Knowledge Resource:

  1. Create a draft

    Section titled “Create a draft”
    POST /api/packages HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/json
    

    {
      "access": { "record": "public", "files": "public" },
      "files": { "enabled": true },
      "metadata": {
        "title": "My EO Application",
        "publication_date": "2024-01-15",
        "creators": [
          {
            "person_or_org": {
              "type": "personal",
              "family_name": "Smith",
              "given_name": "Jane"
            }
          }
        ],
        "rights": [{ "id": "cc-by-4.0" }]
      }
    }

    Response — 201 Created.

  2. Upload files

    Section titled “Upload files”

    Each file follows a three-step pattern: init → upload → commit. Users initialize the file, upload content and commit. This process must be done for every file you want to upload.

    2a. Initialize

    Section titled “2a. Initialize”
    POST /api/packages/{id}/draft/files HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/json
    

    [
      { "key": "figure.png" },
      { "key": "article.pdf" }
    ]

    2b. Upload

    Section titled “2b. Upload”
    PUT /api/packages/{id}/draft/files/figure.png/content HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/octet-stream
    

    <binary file data>

    2c. Commit

    Section titled “2c. Commit”
    POST /api/packages/{id}/draft/files/figure.png/commit HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>

    Repeat steps 2b and 2c for each file in the upload list.

  3. Update metadata

    Section titled “Update metadata”
    PUT /api/packages/{id}/draft HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/json
    

    {
      "access": { "record": "public", "files": "public" },
      "files": { "enabled": true },
      "metadata": {
        "title": "My EO Application — Updated",
        "publication_date": "2024-01-15",
        "creators": [
          {
            "person_or_org": {
              "type": "personal",
              "family_name": "Smith",
              "given_name": "Jane"
            }
          }
        ],
        "rights": [{ "id": "cc-by-4.0" }],
        "description": "Flood mapping using Sentinel-1 SAR data.",
        "subjects": [{ "subject": "flood mapping" }],
        "languages": [{ "id": "eng" }]
      }
    }

  4. Associate Knowledge Resources

    Section titled “Associate Knowledge Resources”

    Linking a Resource to a Package is a two-call operation:

    (1) Associate to the Package context: Registers the Resource as part of this Package’s life across versions. A Resource added to a Package context is managed by the Package and will be published with it.

    (2) Add to the current draft: Places the Resource in this specific version of the Package.

    4a. Associate to the Package context

    Section titled “4a. Associate to the Package context”
    POST /api/packages/{id}/context/actions/associate HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/json
    

    {
      "records": [{ "id": "<resource-id>" }]
    }

    Response: 204 No Content.

    4b. Add the Resource to this draft

    Section titled “4b. Add the Resource to this draft”
    POST /api/packages/{id}/draft/resources HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/json
    

    {
      "resources": [{ "id": "<resource-id>" }]
    }

    Response: 200 OK.

  5. Publish

    Section titled “Publish”

    Publishing a Package mints its DOI and publishes every associated Resource that is still a draft.

    POST /api/packages/{id}/draft/actions/publish HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>

    Response: 202 Accepted.

  6. (Optional) Create a new version

    Section titled “(Optional) Create a new version”

    Opens a fresh draft with an incremented versions.index. You can also import the Resources from the previous version in one shot, then add or replace as needed.

    6a. Open a new version

    Section titled “6a. Open a new version”
    POST /api/packages/{id}/versions HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>

    6b. Import resources from the previous version

    Section titled “6b. Import resources from the previous version”
    POST /api/packages/{id}/draft/actions/resources-import HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>

    From here, repeat steps 2 → 5 to update the new version.