Technical Documentation / Working with Data / Publishing Science Results - STEP 2

[edobrowolska]

#Step 2: Creating and uploading a STAC Item Catalog
Description

• I would add also this as a second sentence to introduction: The STAC items should be created for all assets in your dataset (single files), gathered in dedicated STAC Catalogs to become available to EarthCODE users.

• The hierarchy is structured as follows: ( I would update it to following):

1. STAC Catalog: A top-level container with a title and a description, grouping related data files (behaves like a folder in file management system)
   In a STAC Catalog you can gather different STAC components. Usually it serves to create smaller folders (as directories) to organize STAC Items in a logical way. You can also add extra information to describe the items better, similar to how the STAC Collection does.
   Should we add also sentence like this? : "There are no limitations on the number of items that can be grouped within a STAC Catalog. However, the performance of the STAC Browser may be affected by the size and quantity of the items, potentially resulting in slower display times"
2. STAC Item: One item represents a single data file (e.g. one GeoTiff). In STAC it is represented in a form of GeoJSON feature with additional metadata requested such as geospatial extent, temporal range, projection etc. Each item is provided with direct link to actual data files (its remote location) in form of associated Assets. One item can have mutliple Assets which can also describe different bands or file types.
3. STAC Collection: Collection is created to include additional metadata about the Items that are part of specific STAC Catalogs. Open Science Catalogue repository stores collections to describe the products accessible throuh STAC Catalogs. In Open Science Catalogue STAC Collections are created in Step 3.

• Remove explanation of Assets

• Add a "STAC in a nutshell" o explain different STAC comonent by linking to the documentation: https://stacspec.org/en/tutorials/intro-to-stac/

• Example file (in code format) should include more description related to actual Open Science Catalog entries.
  Below you can find an example of the hierarchy of STAC Catalog described above:

Example STAC Catalog structure

my-items-catalog
├── catalog.json
└── item_1
└── item_1.json
└── item_2
└── item_2.json

An example of the basic STAC catalog.json file is provided below:
{
"type": "Catalog",
"id": "my-items-catalog-id",
"stac_version": "1.1.0",
"description": "Provide here a meaningful description of the dataset",
"links": [
{
"rel": "root",
"href": "./catalog.json",
"type": "application/json",
"title": "Title of the Dataset"
},
{
"rel": "item",
"href": "./item_1/item_1.json", #relative link to the item.json describing single file in the dataset
"type": "application/geo+json"
},
{
"rel": "item",
"href": "./item_2/item_2.json",
"type": "application/geo+json"
},
],
"title": "Title of the Dataset"
}

An example of the basic STAC item.json file (describing single file in the dataset):
{
"type": "Feature",
"stac_version": "1.1.0",
"stac_extensions": [
"https://stac-extensions.github.io/eo/v1.1.0/schema.json"
],
"id": "item_1",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-50.17968937855544,
66.77834561360399
],
[
-47.9894188361956,
66.83503196763441
],
[
-48.056356656894216,
67.37093506267574
],
[
-50.295235368856346,
67.31275872920898
],
[
-50.17968937855544,
66.77834561360399
]
]
]
},
"bbox": [
-50.295235368856346,
66.77834561360399,
-47.9894188361956,
67.37093506267574
],
"properties": {
"datetime": "2025-03-18T09:47:57.377671Z"
},
"links": [
{
"rel": "root",
"href": "../catalog.json",
"type": "application/json",
"title": "Title of the Dataset"
},
{
"rel": "parent",
"href": "../catalog.json",
"type": "application/json",
"title": "Title of the Dataset"
}
],
"assets": {
"data": {
"href": "https://EarthCODE/OSCAcssets/PROJECT/PRODUCT/item_1.tif",
"type": "image/tiff; application=geotiff",
"eo:bands": [
{
"name": "b1",
"description": "gray"
}
],
"roles": []
}
}
}

[aparrini-68]

I'm a little bit confused by these definitions:
Items – Each Item represents a single data file and contains metadata such as geospatial extent, temporal range, and projection.
Assets – Each Item has one or more Assets, which have a direct link to the actual data files and contain metadata such as file type and spectral bands.

how can an Item that represents a single data file include multiple assets?

[anders0204]

I'm also confused by this @aparrini-68! I suppose for a given observation (a single geographical area + time) you can have multiple data files that are in separate bands, for example. We should change the wording for what the "Item represents" though.

Would something like "Each item represents a single observation of a geographical area in a a point in time" be more accurate? @edobrowolska ?

[anders0204]

STAC Collection: Collection is created to include additional metadata about the Items that are part of specific STAC Catalogs. Open Science Catalogue repository stores collections to describe the products accessible throuh STAC Catalogs. In Open Science Catalogue STAC Collections are created in Step 3.

I don't think there is a reason to introduce Collections here as they are not relevant for this part of the tutorial. It's probably confusing enough already! Do you agree?

[edobrowolska]

Hi Anders and Andrea I have added my comments in the #56

[edobrowolska]

STAC Collection: Collection is created to include additional metadata about the Items that are part of specific STAC Catalogs. Open Science Catalogue repository stores collections to describe the products accessible throuh STAC Catalogs. In Open Science Catalogue STAC Collections are created in Step 3.

I don't think there is a reason to introduce Collections here as they are not relevant for this part of the tutorial. It's probably confusing enough already! Do you agree?

Yes, I think the collections can be intoduced in the next step 3, where we explain the creation of Catalogue entries. Where we actually ask user to describe their Products in Collections schema.
Product (Dataset) = a collection of related sets of information that is composed of separate elements but can be manipulated as a unit by a computer.

Item (Variable) = a single set of information, typically linked to one or more geophysical variables.
So Items to be used for the Variables and STAC Collections for the Products. I think this might make more sense.
Let me knowwhat do you think..

[aparrini-68]

Hi, so if I understand well :

1. a Dataset contains one or more items (so potentially refers to different files). why there is the need to consider a unit manipulation? I mean in my opinion it should be possible also to perform a partial manipulation.. do I miss anything?
2. an item is a sort of "box" that contains variables and their files like in this example https://stacspec.org/en/tutorials/intro-to-stac/ correct?
   3)Asset -> the definition is the same as before
   this is my understanding and if correct apart from point 1 I agree

[edobrowolska]

Hi Andrea
, I'm not sure if I understand correctly what do you mean by partial manipulation? Maybe by looking at the example for instance here, you can suggest better definition.
What I mean is that the Product collection may contain one or many items like here: https://opensciencedata.esa.int/external/s3.waw4-1.cloudferro.com/EarthCODE/Catalogs/4DANTARCTICA/antarctic-ice-sheet-velocity-monthly-2021/catalog
The Item is one single file describing one or many variables like here: https://opensciencedata.esa.int/external/s3.waw4-1.cloudferro.com/EarthCODE/Catalogs/4DANTARCTICA/antarctic-ice-sheet-velocity-monthly-2021/20210101-ESACCI-L3C-AIS-IV-S1-1M_200m-fv1.0/20210101-ESACCI-L3C-AIS-IV-S1-1M_200m-fv1.0
And the Asset defintion from before I think was ok, it should be just underlined that the Asset is created automatically in STAC Item as a part of STAC Item: here is an example: https://s3.waw4-1.cloudferro.com/EarthCODE/Catalogs/4DANTARCTICA/antarctic-ice-sheet-velocity-monthly-2021/20210101-ESACCI-L3C-AIS-IV-S1-1M_200m-fv1.0/20210101-ESACCI-L3C-AIS-IV-S1-1M_200m-fv1.0.json

[aparrini-68]

Hi ,
I think we are in line. the first link you sent is the dataset AKA Product collection. Why you wrote "can be manipulated as a unit"? I just think that this part of the sentence could be removed because the dataset can be manipulated as needed ( as a unit -> the whole dataset, partially -> some of the items ). what do you think?

[edobrowolska]

I agree! this latest part of the sentence can be removed, from my point of view!