# JSON schemas

The Cloud Images API supplies json documents describing the JSON-encoded data structures that represent domain objects, so that a client knows exactly what to expect in an API response.

A JSON Schema is represented by the `OpenCloud\Image\Resource\Schema\Schema` class.

## 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 (see `OpenCloud\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.