diff --git a/spec/protocols/OVERVIEW.md b/spec/protocols/OVERVIEW.md index 5bddb1bcb..e90af8781 100644 --- a/spec/protocols/OVERVIEW.md +++ b/spec/protocols/OVERVIEW.md @@ -10,26 +10,38 @@ This document describes the OpenSharing Protocol's general concepts, including t A profile file is a JSON file that contains the information for a recipient to access shared data on a OpenSharing server. There are a few fields in this file as listed below. -Field Name | Descrption --|- -shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. -endpoint | The url of the sharing server. -icebergEndpoint | The url of the sharing server that supports the iceberg table endpoints. -bearerToken | The [bearer token](https://tools.ietf.org/html/rfc6750) to access the server. -expirationTime | The expiration time of the bearer token in [ISO 8601 format](https://www.w3.org/TR/NOTE-datetime). This field is optional and if it is not provided, the bearer token can be seen as never expire. +| Field Name | Description | Note | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | +| shareCredentialsVersion | The file format version of the profile file. This version will be increased whenever non-forward-compatible changes are made to the profile format. When a client is running an unsupported profile file format version, it should show an error message instructing the user to upgrade to a newer version of their client. | [required] | +| endpoint | The url of the sharing server. | [required] | +| icebergEndpoint | The url of the sharing server's Iceberg REST catalog endpoint. If provided, it must be `{endpoint}/iceberg`. | [optional] | +| bearerToken | The [bearer token](https://tools.ietf.org/html/rfc6750) to access the server. | [required] | +| expirationTime | The expiration time of the bearer token in [ISO 8601 format](https://www.w3.org/TR/NOTE-datetime). This field is optional and if it is not provided, the bearer token can be seen as never expire. | [optional] | Example: ```json { "shareCredentialsVersion": 1, - "endpoint": "https://sharing.opensharing.io/open-sharing/", - "icebergEndpoint": "https://sharing.opensharing.io/open-sharing/iceberg/", + "endpoint": "https://sharing.opensharing.io/open-sharing", + "icebergEndpoint": "https://sharing.opensharing.io/open-sharing/iceberg", "bearerToken": "", "expirationTime": "2021-11-12T00:12:29.0Z" } ``` +or + +```json +{ + "shareCredentialsVersion": 1, + "endpoint": "https://sharing.opensharing.io/open-sharing", + "bearerToken": "" +} +``` + +OpenSharing servers that share tables in Iceberg format may optionally provide an `icebergEndpoint` in the profile file. If provided, it must be `{endpoint}/iceberg`. Clients must not assume `icebergEndpoint` is present and should handle its absence gracefully. + ## Names Share, Schema, and shared objects are identifiable by names. To ensure compatibility and avoid issues across different sharing servers, the following limitations apply for object names: