namespace file_properties
"This namespace contains helpers for property and template metadata endpoints.
These endpoints enable you to tag arbitrary key/value data to Dropbox files.
The most basic unit in this namespace is the :type:`PropertyField`. These fields encapsulate the
actual key/value data.
Fields are added to a Dropbox file using a :type:`PropertyGroup`. Property groups contain a
reference to a Dropbox file and a :type:`PropertyGroupTemplate`. Property groups are uniquely
identified by the combination of their associated Dropbox file and template.
The :type:`PropertyGroupTemplate` is a way of restricting the possible key names and value types
of the data within a property group. The possible key names and value types are explicitly
enumerated using :type:`PropertyFieldTemplate` objects.
You can think of a property group template as a class definition for a particular key/value
metadata object, and the property groups themselves as the instantiations of these objects.
Templates are owned either by a user/app pair or team/app pair. Templates and their associated
properties can't be accessed by any app other than the app that created them, and even then, only
when the app is linked with the owner of the template (either a user or team).
User-owned templates are accessed via the user-auth file_properties/templates/*_for_user endpoints, while
team-owned templates are accessed via the team-auth file_properties/templates/*_for_team endpoints. Properties
associated with either type of template can be accessed via the user-auth properties/* endpoints.
Finally, properties can be accessed from a number of endpoints that return metadata, including
`files/get_metadata`, and `files/list_folder`. Properties can also be added during upload, using
`files/upload`.
"
alias TemplateId = String(min_length=1,pattern="(/|ptid:).*")
alias PathOrId = String(pattern="/(.|[\\r\\n])*|id:.*|(ns:[0-9]+(/.*)?)")
alias Id = String(min_length=1)
alias PropertiesSearchCursor = String(min_length=1)
#
# Core data types
#
struct PropertyField
"Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox
files as a :type:`PropertyGroup`."
name String
"Key of the property field associated with a file and template.
Keys can be up to 256 bytes."
value String
"Value of the property field associated with a file and template.
Values can be up to 1024 bytes."
example default
name = "Security Policy"
value = "Confidential"
struct PropertyGroup
"A subset of the property fields described by the corresponding :type:`PropertyGroupTemplate`.
Properties are always added to a Dropbox file as a :type:`PropertyGroup`.
The possible key names and value types in this group are defined by the
corresponding :type:`PropertyGroupTemplate`."
template_id TemplateId
"A unique identifier for the associated template."
fields List(PropertyField)
"The actual properties associated with the template. There can be up to 32
property types per template."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
fields = [default]
struct PropertyFieldTemplate
"Defines how a single property field may be structured. Used exclusively by :type:`PropertyGroupTemplate`."
name String
"Key of the property field being described. Property field keys can be up to 256 bytes."
description String
"Description of the property field. Property field descriptions can be up to 1024 bytes."
type PropertyType
"Data type of the value of this property field. This type
will be enforced upon property creation and modifications."
union
"Data type of the given property field added."
string
"The associated property field will be of type string. Unicode is supported."
example default
string = null
example default
name = "Security Policy"
description = "This is the security policy of the file or folder described.
Policies can be Confidential, Public or Internal."
type = default
struct PropertyGroupTemplate
"Defines how a property group may be structured."
name String
"Display name for the template. Template names can
be up to 256 bytes."
description String
"Description for the template. Template descriptions
can be up to 1024 bytes."
fields List(PropertyFieldTemplate)
"Definitions of the property fields associated with this template.
There can be up to 32 properties in a single template."
example default
name = "Security"
description = "These properties describe how confidential this file or folder is."
fields = [default]
#
# Property routes
#
struct AddPropertiesArg
path PathOrId
"A unique identifier for the file or folder."
property_groups List(PropertyGroup)
"The property groups which are to be added to a Dropbox file. No two groups in the input should
refer to the same template."
example default
path = "/my_awesome/word.docx"
property_groups = [default]
union LookupError
malformed_path String
not_found
"There is nothing at the given path."
not_file
"We were expecting a file, but the given path refers to something that isn't a file."
not_folder
"We were expecting a folder, but the given path refers to something that isn't a folder."
restricted_content
"The file cannot be transferred because the content is restricted. For example, we might restrict a file due to legal requirements."
union LookUpPropertiesError
property_group_not_found
"No property group was found."
union TemplateError
template_not_found TemplateId
"Template does not exist for the given identifier."
restricted_content
"You do not have permission to modify this template."
union PropertiesError extends TemplateError
path LookupError
unsupported_folder
"This folder cannot be tagged. Tagging folders is not supported for team-owned templates."
union InvalidPropertyGroupError extends PropertiesError
property_field_too_large
"One or more of the supplied property field values is too large."
does_not_fit_template
"One or more of the supplied property fields does not conform to the template specifications."
duplicate_property_groups
"There are 2 or more property groups referring to the same templates in the input. "
union AddPropertiesError extends InvalidPropertyGroupError
property_group_already_exists
"A property group associated with this template and file already exists."
route properties/add(AddPropertiesArg, Void, AddPropertiesError)
"Add property groups to a Dropbox file. See :route:`templates/add_for_user` or
:route:`templates/add_for_team` to create new templates."
attrs
scope = "files.metadata.write"
struct OverwritePropertyGroupArg
path PathOrId
"A unique identifier for the file or folder."
property_groups List(PropertyGroup, min_items=1)
"The property groups \"snapshot\" updates to force apply. No two groups in the input should
refer to the same template."
example default
path = "/my_awesome/word.docx"
property_groups = [default]
route properties/overwrite(OverwritePropertyGroupArg, Void, InvalidPropertyGroupError)
"Overwrite property groups associated with a file. This endpoint should be used
instead of :route:`properties/update` when property groups are being updated via a
\"snapshot\" instead of via a \"delta\". In other words, this endpoint will delete all
omitted fields from a property group, whereas :route:`properties/update` will only
delete fields that are explicitly marked for deletion."
attrs
scope = "files.metadata.write"
struct PropertyGroupUpdate
template_id TemplateId
"A unique identifier for a property template."
add_or_update_fields List(PropertyField)?
"Property fields to update. If the property field already exists, it is updated.
If the property field doesn't exist, the property group is added."
remove_fields List(String)?
"Property fields to remove (by name), provided they exist."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
add_or_update_fields = [default]
remove_fields = []
struct UpdatePropertiesArg
path PathOrId
"A unique identifier for the file or folder."
update_property_groups List(PropertyGroupUpdate)
"The property groups \"delta\" updates to apply."
example default
path = "/my_awesome/word.docx"
update_property_groups = [default]
union UpdatePropertiesError extends InvalidPropertyGroupError
property_group_lookup LookUpPropertiesError
route properties/update(UpdatePropertiesArg, Void, UpdatePropertiesError)
"Add, update or remove properties associated with the supplied file and templates.
This endpoint should be used instead of :route:`properties/overwrite` when property groups
are being updated via a \"delta\" instead of via a \"snapshot\" . In other words, this endpoint
will not delete any omitted fields from a property group, whereas :route:`properties/overwrite`
will delete any fields that are omitted from a property group."
attrs
scope = "files.metadata.write"
struct RemovePropertiesArg
path PathOrId
"A unique identifier for the file or folder."
property_template_ids List(TemplateId)
"A list of identifiers for a template created by :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
path = "/my_awesome/word.docx"
property_template_ids = ["ptid:1a5n2i6d3OYEAAAAAAAAAYa"]
union RemovePropertiesError extends PropertiesError
property_group_lookup LookUpPropertiesError
route properties/remove(RemovePropertiesArg, Void, RemovePropertiesError)
"Permanently removes the specified property group from the file. To remove specific property field key
value pairs, see :route:`properties/update`.
To update a template, see
:route:`templates/update_for_user` or :route:`templates/update_for_team`.
To remove a template, see
:route:`templates/remove_for_user` or :route:`templates/remove_for_team`."
attrs
scope = "files.metadata.write"
#
# Property Group Template Routes
#
struct AddTemplateArg extends PropertyGroupTemplate
example default
name = "Security"
description = "These properties describe how confidential this file or folder is."
fields = [default]
struct AddTemplateResult
template_id TemplateId
"An identifier for template added by See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
union ModifyTemplateError extends TemplateError
conflicting_property_names
"A property field key with that name already exists in the template."
too_many_properties
"There are too many properties in the changed template.
The maximum number of properties per template is 32."
too_many_templates
"There are too many templates for the team."
template_attribute_too_large
"The template name, description or one or more of the property field keys is too large."
route templates/add_for_user(AddTemplateArg, AddTemplateResult, ModifyTemplateError)
"Add a template associated with a user. See :route:`properties/add` to add properties to a file. This
endpoint can't be called on a team member or admin's behalf."
attrs
scope = "files.metadata.write"
route templates/add_for_team(AddTemplateArg, AddTemplateResult, ModifyTemplateError)
"Add a template associated with a team. See :route:`properties/add` to add properties to a file or folder.
Note: this endpoint will create team-owned templates."
attrs
auth="team"
scope = "files.team_metadata.write"
struct GetTemplateArg
template_id TemplateId
"An identifier for template added by route See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
struct GetTemplateResult extends PropertyGroupTemplate
example default
name = "Security"
description = "These properties describe how confidential this file or folder is."
fields = [default]
route templates/get_for_user(GetTemplateArg, GetTemplateResult, TemplateError)
"Get the schema for a specified template. This endpoint can't be called on a team member or admin's behalf."
attrs
scope = "files.metadata.read"
route templates/get_for_team(GetTemplateArg, GetTemplateResult, TemplateError)
"Get the schema for a specified template."
attrs
auth="team"
scope = "files.team_metadata.write"
struct UpdateTemplateArg
template_id TemplateId
"An identifier for template added by See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
name String?
"A display name for the template. template names can
be up to 256 bytes."
description String?
"Description for the new template. Template descriptions
can be up to 1024 bytes."
add_fields List(PropertyFieldTemplate)?
"Property field templates to be added to the group template.
There can be up to 32 properties in a single template."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
name = "New Security Template Name"
description = "These properties will describe how confidential this file or folder is."
add_fields = [default]
struct UpdateTemplateResult
template_id TemplateId
"An identifier for template added by route See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
route templates/update_for_user(UpdateTemplateArg, UpdateTemplateResult, ModifyTemplateError)
"Update a template associated with a user. This route can update the template name,
the template description and add optional properties to templates. This endpoint can't
be called on a team member or admin's behalf."
attrs
scope = "files.metadata.write"
route templates/update_for_team(UpdateTemplateArg, UpdateTemplateResult, ModifyTemplateError)
"Update a template associated with a team. This route can update the template name,
the template description and add optional properties to templates."
attrs
auth="team"
scope = "files.team_metadata.write"
struct ListTemplateResult
template_ids List(TemplateId)
"List of identifiers for templates added by See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_ids = ["ptid:1a5n2i6d3OYEAAAAAAAAAYa"]
route templates/list_for_user(Void, ListTemplateResult, TemplateError)
"Get the template identifiers for a team. To get the schema of
each template use :route:`templates/get_for_user`. This endpoint can't be
called on a team member or admin's behalf."
attrs
scope = "files.metadata.read"
route templates/list_for_team(Void, ListTemplateResult, TemplateError)
"Get the template identifiers for a team. To get the schema of
each template use :route:`templates/get_for_team`."
attrs
auth="team"
scope = "files.team_metadata.write"
struct RemoveTemplateArg
template_id TemplateId
"An identifier for a template created by :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
route templates/remove_for_user(RemoveTemplateArg, Void, TemplateError)
"Permanently removes the specified template created from :route:`templates/add_for_user`.
All properties associated with the template will also be removed. This action
cannot be undone."
attrs
scope = "files.metadata.write"
route templates/remove_for_team(RemoveTemplateArg, Void, TemplateError)
"Permanently removes the specified template created from :route:`templates/add_for_user`.
All properties associated with the template will also be removed. This action
cannot be undone."
attrs
auth="team"
scope = "files.team_metadata.write"
union TemplateOwnerType
user
"Template will be associated with a user."
team
"Template will be associated with a team."
example default
user = null
union LogicalOperator
"Logical operator to join search queries together."
or_operator
"Append a query with an \"or\" operator."
example default
or_operator = null
union PropertiesSearchMode
field_name String
"Search for a value associated with this field name."
example default
field_name = "Security"
struct PropertiesSearchQuery
query String
"The property field value for which to search across templates."
mode PropertiesSearchMode
"The mode with which to perform the search."
logical_operator LogicalOperator = or_operator
"The logical operator with which to append the query."
example default
query = "Confidential"
mode = default
logical_operator = default
union TemplateFilterBase
filter_some List(TemplateId, min_items=1)
"Only templates with an ID in the supplied list will be returned (a subset of
templates will be returned)."
example default
filter_some = ["ptid:1a5n2i6d3OYEAAAAAAAAAYa"]
union TemplateFilter extends TemplateFilterBase
filter_none
"No templates will be filtered from the result (all templates will be returned)."
example default
filter_none = null
struct PropertiesSearchArg
queries List(PropertiesSearchQuery, min_items=1)
"Queries to search."
template_filter TemplateFilter = filter_none
"Filter results to contain only properties associated with these template IDs."
example default
queries = [default]
template_filter = default
struct PropertiesSearchMatch
id Id
"The ID for the matched file or folder."
path String
"The path for the matched file or folder."
is_deleted Boolean
"Whether the file or folder is deleted."
property_groups List(PropertyGroup)
"List of custom property groups associated with the file."
example default
id = "id:a4ayc_80_OEAAAAAAAAAXz"
path = "/my_awesome/word.docx"
is_deleted = false
property_groups = [default]
struct PropertiesSearchResult
matches List(PropertiesSearchMatch)
"A list (possibly empty) of matches for the query."
cursor PropertiesSearchCursor?
"Pass the cursor into :route:`properties/search/continue` to continue to receive
search results. Cursor will be null when there are no more results."
example default
matches = [default]
union PropertiesSearchError
property_group_lookup LookUpPropertiesError
route properties/search(PropertiesSearchArg, PropertiesSearchResult, PropertiesSearchError)
"Search across property templates for particular property field values."
attrs
scope = "files.metadata.read"
struct PropertiesSearchContinueArg
cursor PropertiesSearchCursor
"The cursor returned by your last call to :route:`properties/search` or
:route:`properties/search/continue`."
example default
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
union PropertiesSearchContinueError
reset
"Indicates that the cursor has been invalidated. Call
:route:`properties/search` to obtain a new cursor."
route properties/search/continue (PropertiesSearchContinueArg, PropertiesSearchResult, PropertiesSearchContinueError)
"Once a cursor has been retrieved from :route:`properties/search`, use this to paginate through all
search results."
attrs
scope = "files.metadata.read"