Support Additional Share Metadata in Delta Sharing Protocol

[zhu-tom]

This is a proposal of the initial scope to add additional share metadata to the Delta Sharing Protocol.

Motivation

We currently do not support sharing additional metadata in the Delta Sharing Protocol such a comments, tags, and display name.

Note: As this is only an initial scope, more fields could be introduced in the future. It is expected for clients to ignore unrecognized fields when parsing the response.

Protocol Changes

We propose the following new fields in GetShare

REST APIs

List Shares

We will add new displayName, comment, and properties fields to each share in the ListShares response.

HTTP Request	Value
Method	GET
Headers	Authorization: Bearer {token}
URL	{prefix}/shares
URL Parameters	Unchanged

200: The shares were successfully returned.

HTTP Response	Value
Body	{ "items": [ { "name": "string", "id": "string", "displayName": "string", "comment": "string", "properties": { "key": "value" } } ], "nextPageToken": "string" }

Get Share

We will add new displayName, comment, and properties fields to the GetShare response.

HTTP Request	Value
Method	GET
Headers	Authorization: Bearer {token}
URL	{prefix}/shares/{share}
URL Parameters	Unchanged

200: The share's metadata was successfully returned.

HTTP Response	Value
Body	{ "share": { "name": "string", "id": "string", "displayName": "string", "comment": "string", "properties": { "key": "value" } } }

API Response Format

Share

Field Name	Data Type	Description	Optional/Required
displayName	String	Share name that should be displayed to the user Max length: 255	Optional
comment	String	User-provided free-form text description Max length: 65536	Optional
properties	Map<String, String>	Properties assigned to the share key Max length: 255 value Max length: 1000 Max amount of keys: 50	Optional

Note: Any fields exceeding these lengths should be truncated by the client.