Merge branch '15397-remove-obsolete-apis'
[arvados.git] / doc / api / properties.html.textile.liquid
1 ---
2 layout: default
3 navsection: api
4 title: "Metadata properties"
5 ...
6 {% comment %}
7 Copyright (C) The Arvados Authors. All rights reserved.
8
9 SPDX-License-Identifier: CC-BY-SA-3.0
10 {% endcomment %}
11
12 Arvados allows you to attach arbitrary properties to "collection":methods/collections.html, "container_request":methods/container_requests.html, "link":methods/links.html and "group":methods/groups.html records that have a @properties@ field.  These are key-value pairs, where the value is a valid JSON type (string, number, null, boolean, array, object).
13
14 Searching for records using properties is described in "Filtering on subproperties":methods.html#subpropertyfilters .
15
16 h2. Reserved properties
17
18 Components that ship with Arvados may automatically set properties on objects. These usually help track provenance or provide additional link metadata. These properties usually have a key that starts with @arv:@, and can always be set even when the system is configured with a strict vocabulary.
19
20 table(table table-bordered table-condensed).
21 |_. Property name|_. Appears on|_. Value type|_.Description|
22 {% comment %}
23 The arv:git* container properties, and the associated Git commands, primarily come from arvados_cwl.executor.ArvCwlExecutor.get_git_info.
24 {% endcomment -%}
25 |arv:gitBranch|container request, collection of type=workflow|string|When @arvados-cwl-runner@ is run from a Git checkout, this property is set with the name of the branch checked out (the output of @git rev-parse --abbrev-ref HEAD@)|
26 |arv:gitCommitter|container request, collection of type=workflow|string|When @arvados-cwl-runner@ is run from a Git checkout, this property is set with the name and email address of the committer of the most recent commit (the output of @git log --format='%cn <%ce>' -n1 HEAD@)|
27 |arv:gitCommit|container request, collection of type=workflow|string|When @arvados-cwl-runner@ is run from a Git checkout, this property is set with the full checksum of the most recent commit (the output of @git log --format='%H' -n1 HEAD@)|
28 |arv:gitDate|container request, collection of type=workflow|string|When @arvados-cwl-runner@ is run from a Git checkout, this property is set with the commit date of the most recent commit in RFC 2822 format (the output of @git log --format='%cD' -n1 HEAD@)|
29 |arv:gitDescribe|container request, collection of type=workflow|string|When @arvados-cwl-runner@ is run from a Git checkout, this property is set with the name of the most recent tag that is reachable from the most recent commit (the output of @git describe --always --tags@)|
30 |arv:gitOrigin|container request, collection of type=workflow|string|When @arvados-cwl-runner@ is run from a Git checkout, this property is set with the URL of the remote named @origin@, if set (the output of @git remote get-url origin@)|
31 |arv:gitPath|container request, collection of type=workflow|string|When @arvados-cwl-runner@ is run from a Git checkout, this property is set with the absolute path of the checkout on the filesystem|
32 |arv:gitStatus|container request, collection of type=workflow|string|When @arvados-cwl-runner@ is run from a Git checkout, this property is set with a machine-readable summary of files modified in the checkout since the most recent commit (the output of @git status --untracked-files=no --porcelain@)|
33 |arv:workflowMain|collection of type=workflow|string|Set on a collection containing a workflow created by @arvados-cwl-runner --create-workflow@, this is a relative reference inside the collection to the entry point of the workflow.|
34
35 The following system properties predate the @arv:@ key prefix, but are still reserved and can always be set.
36
37 table(table table-bordered table-condensed).
38 |_. Property name|_. Appears on|_. Value type|_.Description|
39 |type|collection|string|Appears on collections to indicates the contents or usage. See "Collection type values":#collectiontype below for details.|
40 |container_request|collection|string|The UUID of the container request that produced an output or log collection.|
41 |docker-image-repo-tag|collection|string|For collections containing a Docker image, the repo/name:tag identifier|
42 |container_uuid|collection|string|The UUID of the container that produced a collection (set on collections with type=log)|
43 |container|collection|string|(legacy) The UUID of the container that produced a collection.  Set on intermediate collections created by arvados-cwl-runner.  Starting with Arvados 2.6.0 arvados-cwl-runner uses @container_uuid@ instead, but older versions may still set the @container@ property.|
44 |cwl_input|container_request|object|On an intermediate container request, the CWL workflow-level input parameters used to generate the container request|
45 |cwl_output|container_request|object|On an intermediate container request, the CWL workflow-level output parameters collected from the container request|
46 |template_uuid|container_request|string|For a workflow runner container request, the workflow record that was used to launch it.|
47 |workflowName|container_request|string|For a workflow runner container request, the "name" of the workflow record in @template_uuid@ at the time of launch (used for display only).|
48 |username|link|string|For a "can_login":permission-model.html#links permission link, the unix username on the VM that the user will have.|
49 |groups|link|array of string|For a "can_login":permission-model.html#links permission link, the unix groups on the VM that the user will be added to.|
50 |image_timestamp|link|string|When resolving a Docker image name and multiple links are found with @link_class=docker_image_repo+tag@ and same @link_name@, the @image_timestamp@ is used to determine precedence (most recent wins).|
51 |filters|group|array of array of string|Used to define "filter groups":projects.html#filtergroup|
52
53 h3(#collectiontype). Collection "type" values
54
55 Meaningful values of the @type@ property.  These are recognized by Workbench when filtering on types of collections from the project content listing.
56
57 table(table table-bordered table-condensed).
58 |_. Type|_.Description|
59 |log|The collection contains log files from a container run.|
60 |output|The collection contains the output of a top-level container run (this is a container request where @requesting_container_uuid@  is null).|
61 |intermediate|The collection contains the output of a child container run (this is a container request where @requesting_container_uuid@ is non-empty).|
62 |workflow|A collection created by @arvados-cwl-runner --create-workflow@ containing a workflow definition.|
63
64 h2. Controlling user-supplied properties
65
66 Arvados can be configured with a vocabulary file that lists valid properties and the range of valid values for those properties.  This is described in "Metadata vocabulary":{{site.baseurl}}/admin/metadata-vocabulary.html .
67
68 Arvados offers options to set properties automatically and/or prevent certain properties, once set, from being changed by non-admin users.  This is described in "Configuring collection's managed properties":{{site.baseurl}}/admin/collection-managed-properties.html .
69
70 The admin can require that certain properties must be non-empty before "freezing a project":methods/groups.html#frozen .