Return metadata about image schema

Discover Gettable Image Fields

Image registries store a variety of information about images. The set of base, typed attributes for an image is dynamic, and different registry servers may publish different sets of these typed attributes.

To retrieve information about this set of attributes that will be displayed when retrieving information about an individual image, you can issue the following call:

GET /v2/form/image

Request body is ignored.

Response will be a 200 OK, with the body containing a JSON-encoded mapping of metadata about the image fields published by the registry server:

{
 ‘_type’: ‘form’,
 ‘action’: <CURRENT_URL>,
 ‘method’: ‘GET’,
 ‘type’: ‘image’,
 ‘fields’: [
   {
   ‘name’: ‘name’,
   ‘type': 'string'
   },
   {
   ‘name’: 'disk_format',
   'type': 'string',
   'maxlen': 30
   },
   {
   ‘name’: 'container_format',
   ‘type': 'string',
   'maxlen': 30,
   },
   {
   ‘name’: 'size',
   ‘type': 'number'
   },
   {
   ‘name’: 'status',
   'type': 'string',
   'maxlen': 64,
   },
   {
   ‘name’: 'created_at',
   'type': 'string',
   },
   {
   ‘name’: 'updated_at',
   'type': 'string'
   },
   {
   ‘name’: 'deleted_at',
   'type': 'string'
   },
   {
   ‘name’: 'min_disk',
   ‘type': 'number'
   },
   {
   ‘name’: 'min_ram',
   'type': 'number'
   },
   {
   ‘name’: ‘owner’,
   ‘type’: ‘string’,
   },
   {
   ‘name’: ‘tags’,
   ‘type’: ‘string’,
   ‘maxlen’: 64,
   ‘multiple’: true
   },
   <EXTENDED_ATTRIBUTES>
 ]
}

All mappings in the fields collection will have a name key, which will be the name of the base image attribute.

All mappings in the fields collection will have a type key, which must be one of the following:

    string
    number
    boolean

If a field mapping has the optional multiple boolean attribute, that means the field has multiple values (it’s an array).

For string attributes, there may be an optional maxlen attribute that indicates the maximum length that particular string field will be. There is a similar optional minlen attribute.

The <EXTENDED_ATTRIBUTES> in the output above is simply description mappings for any base typed attribute that the registry server may publish for an image. Here is an example of such extended attributes a registry might publish:

   {
   ‘name’: 'disk_config',
   'type': 'boolean'
   },
   {
   ‘name’: 'architecture',
   'type': 'string',
   ‘maxlen’: 64
   }

Discovering Settable Image Fields

To retrieve information about this set of attributes that are settable when registering a new image, you can issue the following call:

GET /v2/form/image?method=POST

Request body is ignored.

Response will be a 200 OK, with the body containing a JSON-encoded mapping of metadata about the image fields the caller may set on an image:

{
 ‘_type’: ‘form’,
 ‘action’: <CURRENT_URL>,
 ‘method’: ‘POST’,
 ‘type’: ‘image’,
 ‘fields’: [
   {
   ‘name’: ‘name’,
   ‘type': 'string',
   ‘mandatory’: true,
   },
   {
   ‘name’: 'disk_format',
   'type': 'string',
   'maxlen': 30,
   ‘mandatory’: true,
   },
   {
   ‘name’: 'container_format',
   ‘type': 'string',
   'maxlen': 30,
   ‘mandatory’: true,
   },
   {
   ‘name’: 'size',
   ‘type': 'number'
   },
   {
   ‘name’: 'min_disk',
   ‘type': 'number'
   ‘min’: 0
   },
   {
   ‘name’: 'min_ram',
   'type': 'number',
   ‘min’: 0
   },
   {
   ‘name’: ‘tags’,
   ‘type’: ‘string’,
   ‘maxlen’: 64,
   ‘multiple’: true
   },
   <EXTENDED_ATTRIBUTES>
 ]
}

All fields that are writeable in a call to POST /v2/images/ will be included in the fields collection.

All mappings in the fields collection will have a name key, which will be the name of the base image attribute.

All mappings in the fields collection will have a type key, which must be one of the following:

    string
    number
    boolean

If a field mapping has the optional multiple boolean attribute, that means the field has multiple values (it’s an array).

If a field mapping has the optional mandatory boolean attribute, that means the field is required to have a value when issuing the call to POST /v2/images. If the request to create a new image does not contain values for mandatory fields, a 409 Conflict will be returned.

If a field mapping has the optional protected boolean attribute, that means the field is only writeable by users that have admin rights when issuing the call to POST /v2/images. If a user with non-admin rights attempt to set a protected attribute, a 403 Forbidden will be returned.

If a field mapping has the optional regex attribute, that means the field will be validated against the regular expression. Data values that fail the regular expression check will cause a 409 Conflict to be returned.

For string attributes, there may be an optional maxlen attribute that indicates the maximum length that particular string field will be. Data values that fail this constraint will cause a 409 Conflict to be returned.

For number attributes, there may be an optional max attribute that indicates the maximum value for the field. There is a similar optional min attribute. Data values that fail this constraint will cause a 409 Conflict to be returned.

The <EXTENDED_ATTRIBUTES> in the output above is simply description mappings for any base typed attribute that the registry server may publish for an image. Here is an example of such extended attributes a registry might publish:

   {
   ‘name’: 'disk_config',
   'type': 'boolean',
   ‘mandatory’: true,
   ‘protected’: true,
   ‘regex’: ‘(automatic|manual)’
   },
   {
   ‘name’: 'architecture',
   'type': 'string',
   ‘maxlen’: 64,
   ‘mandatory’: true,
   ‘protected’: true
   }

Discovering Editable Image Fields

To retrieve information about this set of attributes that are settable when modifying an existing image, you can issue the following call:
GET /v2/form/image?method=PUT

Request body is ignored.

Response will be a 200 OK, with the body containing a JSON-encoded mapping of metadata about the image fields the caller may set on an image when modifying an existing image:

{
 ‘_type’: ‘form’,
 ‘action’: <CURRENT_URL>,
 ‘method’: ‘PUT’,
 ‘type’: ‘image’,
 ‘fields’: [
   {
   ‘name’: ‘name’,
   ‘type': 'string',
   },
   {
   ‘name’: 'disk_format',
   'type': 'string',
   'maxlen': 30,
   },
   {
   ‘name’: 'container_format',
   ‘type': 'string',
   'maxlen': 30,
   },
   {
   ‘name’: 'size',
   ‘type': 'number'
   },
   {
   ‘name’: 'min_disk',
   ‘type': 'number'
   ‘min’: 0
   },
   {
   ‘name’: 'min_ram',
   'type': 'number',
   ‘min’: 0
   },
   <EXTENDED_ATTRIBUTES>
 ]
}

Note that the tags array is not settable (by default) in a call to PUT /v2/images/<IMAGE_ID>. Tags are actually a full subcollection of the image resource and can be modified and added to using the separate calls for managing an image’s tags. We include the tags array as a settable field in the POST /v2/images as a convenience, but remove it in the call to PUT /v2/images/<IMAGE_ID> call to avoid the problem with calls to modify the image metadata overwriting a previously set collection of tags.

All fields that are writeable in a call to PUT /v2/images/<IMAGE_ID> will be included in the fields collection.

All mappings in the fields collection will have a name key, which will be the name of the base image attribute.

All mappings in the fields collection will have a type key, which must be one of the following:

    string
    number
    boolean

If a field mapping has the optional multiple boolean attribute, that means the field has multiple values (it’s an array).

If a field mapping has the optional mandatory boolean attribute, that means the field is required to have a value when issuing the call to PUT /v2/images. If the request to create a new image does not contain values for mandatory fields, a 409 Conflict will be returned.

Note that in calls to PUT /v2/images/<IMAGE_ID>, most fields should NOT have the mandatory attribute set, as required attributes should be set in the POST /v2/images call.

If a field mapping has the optional protected boolean attribute, that means the field is only writeable by users that have admin rights when issuing the call to POST /v2/images. If a user with non-admin rights attempt to set a protected attribute, a 403 Forbidden will be returned.

If a field mapping has the optional regex attribute, that means the field will be validated against the regular expression. Data values that fail the regular expression check will cause a 409 Conflict to be returned.

For string attributes, there may be an optional maxlen attribute that indicates the maximum length that particular string field will be. Data values that fail this constraint will cause a 409 Conflict to be returned.

For number attributes, there may be an optional max attribute that indicates the maximum value for the field. There is a similar optional min attribute. Data values that fail this constraint will cause a 409 Conflict to be returned.

The <EXTENDED_ATTRIBUTES> in the output above is simply description mappings for any base typed attribute that the registry server may publish for an image. Here is an example of such extended attributes a registry might publish:

   {
   ‘name’: 'disk_config',
   'type': 'boolean',
   ‘protected’: true,
   ‘regex’: ‘(automatic|manual)’
   },
   {
   ‘name’: 'architecture',
   'type': 'string',
   ‘maxlen’: 64,
   ‘protected’: true
   }