Uploading geoscience object metadata

Introduction

This guide will walk you through the process of uploading the metadata for a geoscience object.

Endpoint

• PUT /geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/{object_path:path

This endpoint allows you to create or update a geoscience object. Geoscience objects can be stored hierarchically, by providing the path to the object, including the object name, in the request URL. The submitted properties will be validated against the specified schema properties.

To create a new object, upload it to a unique path with the UUID field set to null. The response will contain a reflection of the uploaded object with a newly assigned object ID. This can be used for future requests to update the object.

If a version of the geoscience object already exists at the specified path a new version will be created.

To move or rename an existing object, simply upload a new version of it (with the same UUID) to a new, unique path or file name.

Note that every upload of an object is considered a new version, even if no changes have been made. If required, the object should be compressed, currently gzip compression is supported. Set header Content-Encoding: gzip if the content is compressed and Accept-Encoding: gzip to receive compressed content.

Request body

The request body should be a JSON object containing the properties of the geoscience object to be created or updated.

Example of a Pointset object request body:

{
    "schema": "/objects/pointset/1.0.0/pointset.schema.json",
    "uuid": null,
    "name": "Example pointset.",
    "description": "This is an example of a pointset Geoscience object.",
    "locations": {
        "coordinates": {
            "width": 3,
            "data_type": "float64",
            "length": 50,
            "data": "35b8b8ba5479a34e905a1b9e212e1cb4a52ec484b969359f2c28f5a00311dbca"
        }
    },
    "bounding_box": {
        "min_y": -5550857.067070156,
        "max_y": -5309927.430829638,
        "min_x": 19108070.856018253,
        "max_x": 19338143.530560993,
        "min_z": 0,
        "max_z": 0
    },
    "coordinate_reference_system": {
        "epsg_code": 3857
    },
    "tags": {
        "location": "location"
    }
}

Definitions of payload fields:

• schema (Required)
• uuid (Required)
• name, description, locations, bounding_box, coordinate_reference_system, tags

schema (Required)

The schema field specifies the URL of the schema against which the properties of the geoscience object will be validated. A list of available schemas can be found in the evo-schemas repository.

uuid (Required)

The uuid field specifies the UUID of the geoscience object. If creating a new object, this should be set to null. If updating an existing object, this should be set to the UUID of the object.

pointset-specific-fields

The remaining fields: name, description, locations, bounding_box, coordinate_reference_system, tags, are specific to the object schema. The example above is for a pointset object.

Response

The response will be a JSON object containing the properties of the created or updated geoscience object, along with a newly assigned object ID.

Example:

{
    "object_path": "pointset_lm_demo.json",
    "object_id": "9fd1cb16-ac0b-40a6-b9ee-89a5d702bce0",
    "object": {
        "schema": "/objects/pointset/1.0.0/pointset.schema.json",
        "uuid": "9fd1cb16-ac0b-40a6-b9ee-89a5d702bce0",
        "name": "Example pointset.",
        "description": "This is an example of a pointset Geoscience object.",
        "locations": {
            "coordinates": {
                "width": 3,
                "data_type": "float64",
                "length": 50,
                "data": "35b8b8ba5479a34e905a1b9e212e1cb4a52ec484b969359f2c28f5a00311dbca"
            }
        },
        "bounding_box": {
            "min_y": -5550857.067070156,
            "max_y": -5309927.430829638,
            "min_x": 19108070.856018253,
            "max_x": 19338143.530560993,
            "min_z": 0,
            "max_z": 0
        },
        "coordinate_reference_system": {
            "epsg_code": 3857
        },
        "tags": {
            "location": "location"
        }
    },
    "version_id": "1720043136271901142",
    "created_at": "2024-07-03T21:45:36Z",
    "created_by": {
        "id": "19d415c0-d8b8-4d19-bbde-f86e3c74d9cd",
        "name": "Example User",
        "email": "example.user@example.com"
    },
    "etag": "61e87e4f5a34dcfa7d761120c972ef5339777cbf",
    "geojson_bounding_box": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    171.65072,
                    -44.54938
                ],
                [
                    173.7175,
                    -44.54938
                ],
                [
                    173.7175,
                    -42.98657
                ]
            ]
        ]
    },
    "links": {
        "download": "https://<geoscience_object_service_host_url>/download_url_details",
        "data": [
            {
                "id": "81048210-978e-4b8e-9e37-60b1bdf22a62",
                "name": "35b8b8ba5479a34e905a1b9e212e1cb4a52ec484b969359f2c28f5a00311dbca",
                "download_url": "https://<geoscience_object_service_host_url>/remaining_download_url_details"
            }
        ]
    }
}

Response fields

object_path

The object_path field specifies the path of the created or updated geoscience object.

object_id

The object_id field specifies the ID of the created or updated geoscience object.

object

The object field contains the properties of the created or updated geoscience object (pointset in this example). This includes:

• schema: The URL of the schema against which the properties of the geoscience object have been validated.
• uuid: The UUID of the geoscience object.
• name: The name of the geoscience object.
• description: A description of the geoscience object.
• locations: The locations of the geoscience object, including the coordinates.
• bounding_box: The bounding box of the geoscience object.
• coordinate_reference_system: The coordinate reference system of the geoscience object.
• tags: Any tags associated with the geoscience object.

version_id

The version_id field specifies the version ID of the created or updated geoscience object. This ID can be used for future requests to update the object.

created_at

The created_at field specifies the date and time when the geoscience object was created.

created_by

The created_by field contains the ID, name, and email of the user who created the geoscience object.

etag

The etag field is a unique identifier for a specific version of a resource.

geojson_bounding_box

The geojson_bounding_box field specifies the geographical bounding box of the geoscience object.

links

The links field contains links related to the geoscience object, such as the download link and data links.

Summary

1. Prepare the properties of the geoscience object you want to create or update.
2. Make a POST request with the properties in the request body.
3. The response will include the properties of the created or updated geoscience object, along with a newly assigned object ID. This can be used for future requests to update the object.