JSON schemas¶
Schema types¶
There are currently four types of schema: Images schema, Image schema, Members schema, and Member schema.
Example response from the API¶
A sample response from the API, for an Images schema might be:
{
"name": "images",
"properties": {
"images": {
"items": {
"type": "array",
"name": "image",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"},
"visibility": {"enum": ["public", "private"]},
"status": {"type": "string"},
"protected": {"type": "boolean"},
"tags": {
"type": "array",
"items": {"type": "string"}
},
"checksum": {"type": "string"},
"size": {"type": "integer"},
"created_at": {"type": "string"},
"updated_at": {"type": "string"},
"file": {"type": "string"},
"self": {"type": "string"},
"schema": {"type": "string"}
},
"additionalProperties": {"type": "string"},
"links": [
{"href": "{self}", "rel": "self"},
{"href": "{file}", "rel": "enclosure"},
{"href": "{schema}", "rel": "describedby"}
]
}
},
"schema": {"type": "string"},
"next": {"type": "string"},
"first": {"type": "string"}
},
"links": [
{"href": "{first}", "rel": "first"},
{"href": "{next}", "rel": "next"},
{"href": "{schema}", "rel": "describedby"}
]
}
The top-level schema is called images
, and contains an array of
links and a properties object. Inside this properties object we see the
structure of this top-level images
object. So we know that it will
take this form:
{
"images": [something...]
}
Within this object, we can see that it contains an array of anonymous
objects, each of which is called image
and has its own set of nested
properties:
{
"images": [
{
[object 1...]
},
{
[object 2...]
},
{
[object 3...]
}
]
}
The structure of these nested objects are defined as another schema -
i.e. a subschema. We know that each object has an ID property
(string), a name property (string), a visibility property (can either be
private
or public
), etc.
{
"images": [
{
"id": "foo",
"name": "bar",
"visibility": "private",
// etc.
},
{
"id": "foo",
"name": "bar",
"visibility": "private",
// etc.
},
{
"id": "foo",
"name": "bar",
"visibility": "private",
// etc.
}
]
}
Each nested property of a schema is represented by the
OpenCloud\Image\Resource\Schema\Property
class.
If you would like to find out more about schemas, Guzzle has good documentation about service descriptions, which is fairly analogous.
JSON Patch¶
The Glance API has a unique way of updating certain dynamic resources: they use JSON Patch method, as outlined in RFC 6902.
Requests need to use the
application/openstack-images-v2.1-json-patch
content-type.
In order for the operation to occur, the request entity body needs to contain a very particular structure:
[
{"op": "replace", "path": "/name", "value": "Fedora 17"},
{"op": "replace", "path": "/tags", "value": ["fedora", "beefy"]}
]
- The
op
key refers to the type of Operation (seeOpenCloud\Image\Enum\OperationType
for a full list). - The
path
key is a JSON pointer to the document property you want to modify or insert. JSON pointers are defined in RFC 6901. - The
value
key is the value.
Because this is all handled for you behind the scenes, we will not go into exhaustive depth about how this operation is handled. You can browse the source code, consult the various RFCs and the official documentation for additional information.