Skip to main content

Use the EDITO Data Catalogue

More details on how the EDITO Catalogue is working and how to work with it.

Context

The EDITO Data Catalogue complements the EDITO Data Storage to form the EDITO Data Lake, which represents the “data access” component of EDITO (find more details in this article).

As a reminder, the EDITO Data Catalogue can reference data inside EDITO storage or external data, whereas the EDITO Data Storage provides an elastic cloud object storage allowing users to store personal, group or public data.

As a user, you have three ways to interact with the EDITO Data Catalogue:

  • Via a Viewer or the STAC Browser, to browse and search data.

  • Via The Data API, to reference and manage your own data when necessary.

📌 Note: only browsing and searching have a graphical interface. All write actions (such as creating catalogues, collections, items) go exclusively through the Data API.

Reminders

The EDITO Data Catalogue API is compliant with STAC and OGC API Features standards.

Especially, we use:

  • STAC Collections to classify data by scientific variables (wind speed, sea ice albedo, etc.). This is the objective classification of any data. Each collection represents a specific variable defined by a specific convention standard name definition. The collections are governed by the community, but moderated by the administrators.

  • STAC Items to represent homogeneous pieces of data (over the variable dimensions). Items are added and governed by the users. An item is necessarily inserted into a collection and refers to the scientific variable of the collection it belongs to, your item will automatically be attached to the collection matching its scientific variable when you publish it. Some item metadata are automatically generated to ease integration with other sub-system of EDITO or external systems.

⚠️ An item can be part of several catalogues but only one collection.

  • STAC Catalogues to classify data by alternative view or ordering (classification by variable families, such as “temperature”, “O2”, etc., personal catalogues, project catalogues). This is the subjective classification of any data. Catalogues are added and governed by the users. Some catalogue metadata are automatically generated to ease integration with other sub-system of EDITO or external systems.

Organization of the Data Catalogue through the Viewer

Default View - As a logged out user

Once you access the Integration Viewer, the interface looks like this:

  • (1): the list of available catalogs. You have the Copernicus Marine, EMODnet catalogues pinned at the top, along projects' catalogues, users' catalogues and finally a list of variable families from Copernicus Marine and EMODnet

💡 EDITO Pro Tip: by clicking on "EDITO Data Catalog" at the top you will also have access to several Data Collections.

  • (2): you can search for a catalogue using keywords

  • (3): your access to the user support

  • (4): to connect to the Viewer

⚠️ When logged out of your EDITO account, you will only have access to projects' catalogues (and collections and their items) made public by EDITO:

As a logged in user

Once you're logged into your EDITO account, you will have access to:

  • Public catalogues, such as Copernicus Marine, EMODnet and their content

  • Catalogues associated with the projects or groups you belong to, in the Projects Catalog section

  • In the Users Catalog section you will see your own resources (items, collections and catalogues) if you have them.

In a Project Catalogue, what you see depends on the visibility of each resource. For example you can see:

  • Resources visible to the project/group

  • Resources that you create and kept private to yourself

  • Public resources, where applicable.

Rights, ownership and visibility

Access to resources in the EDITO Data Catalogue is controlled by two mechanisms: permissions and visibility:

  • Permissions determine what actions a user can perform on a resource

  • Visibiliy determines who can read and discover that resource.

Types of permissions

The main permissions are CREATE, UPDATE and DELETE. READ access is determined by the resource's visibility.

  • READ: determines whether you can see a resource. It is controlled through the resource's visibility.

  • CREATE: allows you to create resources.

  • UPDATE: allows you to modify an existing resource.

  • DELETE: allows you to delete an existing resource.

Read and visibility

READ access is managed through visibility, which is separated from the right to create, update or delete a resource.

A resource can be visible:

  • Only to a specific user;

  • To a project/group;

  • Publicly, through default, when public visibility is permitted.

Resource ownership

Whenever you create a catalogue, collection or item, you become the owner of that resource. As the resource owner, you automatically have the right to:

  • UPDATE it

  • DELETE it

⚠️ Ownership of an individual resource should not be confused with ownership of the main catalogue (for a project's catalogue only).

📌 Note: you can list the permissions associated with your own user through the Data API.

In your personal catalogue

Every EDITO user has a personal catalogue corresponding to their username (findable in the Users Catalog section of the Viewer).

The user is the owner and can:

  • CREATE resources

  • UPDATE resources

  • DELETE resources

By default, resources in your private space are kept visible to you only using your private visibility:

"visibility": ["{username}_private"]

⚠️ You cannot directly make a catalogue or collection public yourself.

  • Making a catalogue or collection publicly visible requires the appropriate publication process through EDITO User Support.

  • Items can be made public directly when public visibility is available for the item.

  • See Public visibility section below

In a project's catalogue

Members of an EDITO project or group can also work in the catalogue associated with that project.

Project catalogue owner

The first member who accesses the project catalogue becomes its owner. This ownership concerns the main project catalogue itself and its group-level permissions. It does not make that person the owner of every resource subsequently created inside the project.

For example:

  • User1 may be the owner of the project's main catalogue.

  • User2 may create an item inside that project.

  • User2 then becomes the owner of that item.

📌 Note: ownership of the project catalogue can currently be transferred through User Support; there is no self-service ownership transfer process.

Default permissions for project members

By default, project members receive the CREATE permission for catalogues, collections and items: creating a resource makes the user the owner of that resource. The creator can therefore update and delete the resource they created.

Managing project permissions

The project catalogue owner can change the permissions granted to the group as a whole.

For example, in addition to the default CREATE permission, the owner may grant the group UPDATE or DELETE permissions where appropriate.

Permissions are managed independently for:

  • Catalogues

  • Collections

  • Items

📌 Individual member permissions: management of permissions for specific members separately from the group-level permissions is still being defined.

In order to update group's permissions related to a catalogue, the owner must do a POST request to https://api.dive.edito.eu/data/groups/<PROJECT_NAME>/rights using the following payload (to adjust depending on the permissions that need to be set):

{
"create_<PROJECT_NAME>_catalog": true,
"create_<PROJECT_NAME>_collection": true,
"create_<PROJECT_NAME>_item": true,
"delete_<PROJECT_NAME>_catalog": false,
"delete_<PROJECT_NAME>_collection": false,
"delete_<PROJECT_NAME>_item": false,
"update_<PROJECT_NAME>_catalog": false,
"update_<PROJECT_NAME>_collection": false,
"update_<PROJECT_NAME>_item": false
}

Visibility

The visibility field controls READ access.

A resource can normally be visible either to its creator only or to the group. By default, when working in a project catalogue:

  • Catalogues are visible to the group;

  • Collections are private to their creator;

  • Items are private to their creator.

When creating a resource, users can choose between the visibility options they are allowed to use, typically:

"visibility": ["{username}_private"]

for private visibility, or:

"visibility": ["{group_name}"]

for visibility to the project/group.

For example, you can own an item and have permission to update or delete it while keeping that item visible only to yourself.

📌 Note:

  • For catalogues and collections, visibility is defined at the top level of the resource.

  • For STAC items, visibility is defined inside the properties object.

Deleting a resource

⚠️ The owner of a resource can delete it only while its content do not include resources owned by other members.

For example, if another project member (User1) creates a resource in a catalogue owned by someone else (User2), User2 can no longer delete its catalogue. User1 retains their own ownership and associated UPDATE and DELETE permissions on that resource.

Public visibility

Public visibility uses:

"visibility": ["default"]

  • Users can make their own items public

  • Users cannot directly make a catalogue or collection public. Publication of a catalogue or collection must be requested through EDITO User Support

Public visibility is hierarchical

Making an item public is not sufficient on its own to make the item publicly discoverable.

For an item to be accessible through a public catalogue path, the item's collection and the catalogue containing it must also be public.

In other words:

Public catalogue
     └── Public collection
           └── Public item

This distinction is important when preparing data for publication: users can make items public themselves, but publication of the containing collection and catalogue requires assistance from EDITO User Support.

⚠️ Attempting to apply an unauthorised public visibility to a catalogue or collection will return a permissions 403 error.

How to add your own dataset in a catalogue

Before creating, updating or deleting a resource, check which catalogue you are working in and which permissions apply to you.

  • In your personal catalogue, you manage the resources you create.

  • In a project catalogue, members have CREATE permission by default and become owners of the resources they create. Additional group permissions depend on the configuration defined by the project catalogue owner.

All write operations require authentication through the Data API.

Private example

For example, to create a collection visible only to you:

curl -X POST 'https://api.dive.edito.eu/data/collections' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{
    "id": "ocean_temperature_products",
    "type": "Collection",
    "title": "My Ocean Temperature Products",
    "description": "Sea surface temperature datasets from my project.",
    "visibility": ["{username}_private"]
  }'

Replace {username} with your own EDITO username.

If the collection is being created in a context where group visibility is permitted, you can instead make it visible to the group:

"visibility": ["{group_name}"]

📌 For catalogues and collections, visibility is located at the top level of the resource.

For items, visibility is located inside the properties object.

Linking an external catalogue

The current method is to POST a catalogue under the /catalogs endpoint with the stac_url parameter set to the external catalogue's URL.

It will appear as a child under its parent catalogue. Only one external child catalogue can currently be added this way.
​

Using the Data API

The base URL to interact with the catalogue is https://api.dive.edito.eu/data.

You can use the Data API to:

  • List and inspect collections (/collections, /collections/{collectionId});

  • List, retrieve and create items within a collection (/collections/{collectionId}/items);

  • Create, update and delete catalogues (/catalogs) when you have the required permissions;

  • Attach items to catalogues through links (rel: item) in the request body;

  • Attach catalogues and collections by POSTing the full object directly to /catalogs/{parent};

  • Search across resources through /search, for example by bounding box, owner or catalogue name;

  • List the permissions associated with your own user.

Your dataset itself must be hosted somewhere accessible, for example in EDITO personal or group storage, or in another accessible storage location, because the Data API stores the metadata pointing to the data, not the data itself.

Using the API requires an access token and some familiarity with STAC item, collection and catalogue structures. For the complete list of endpoints and request examples, see the Data API documentation.
​

General example

This example walks through creating your own catalogue, adding a collection to it and publishing an item into that collection, all in your personal space and visible only to you.

Create a catalogue

curl -X POST 'https://api.dive.edito.eu/data/catalogs/users/<USERNAME>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{
    "id": "my-username",
    "type": "Catalog",
    "title": "My catalogue",
    "description": "My personal catalogue"
  }'

Create a collection and attach it to your catalogue

curl -X POST 'https://api.dive.edito.eu/data/catalogs/<USERNAME>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{
    "id": "ocean_temperature_products",
    "type": "Collection",
    "title": "My Ocean Temperature Products",
    "description": "Sea surface temperature datasets from my project.",
    "visibility": ["{username}_private"]
  }'

Publish an item into the collection

curl -X POST 'https://api.dive.edito.eu/data/collections/ocean_temperature_products/items' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{
    "id": "my-item",
    "type": "Feature",
    "properties": {
      "datetime": "2023-01-12T09:01:00Z",
      "visibility": ["{username}_private"]
    },
    "geometry": { "type": "Polygon", "coordinates": [[[0,0],[0,0],[0,0]]] },
    "assets": {
      "data": { "href": "<URL_TO_YOUR_DATA>", "title": "data", "roles": ["data"] }
    },
  }'

Your item is now referenced in the Data Catalogue, visible only to you and associated with the scientific variable represented by its collection.

As the creator of the item, you are also its owner and automatically have UPDATE and DELETE permissions on it.

💡 EDITO Pro Tip: for the complete list of endpoints, request parameters and response formats, you can browse the interactive API documentation. You can test requests directly from your browser, without writing any code.

What's next?

If you have any questions, problems, or suggestions, please feel free to contact us via chat using the widget available at the bottom right of the page.


​

Did this answer your question?

Related Articles

EDITO Help Center
This page is currently being created and is constantly evolving to cover as many topics as possible.

Funded by the European Union