1. What is JSON-schema?
2. Structure
3. Usage

JSON-schema on GitHub: https://github.com/VKCOM/vk-api-schema

“JSON Schema” is a popular standard for describing data structures. The specifications of this standard and its popular uses are available here http://json-schema.org/.
This schema was created to describe JSON-data, but it itself is a JSON-object. By using keywords inside the schema, the rules of validating object structures and the types of fields are created.

For example, each VK user has an ID (number), first name (string) and last name (ñòðîêà). In API these data are represented as an object with corresponding fileds.

JSON-object with basic user data looks like this:

{"id":210700286,"first_name":"Lindsey","last_name":"Stirling"}

JSON Schema for this object:



required keyword gives the list of mandatory fields. If at least one of these fileds will be absent, the object will not pass validation against the schema.

additionalProperties keyword gives a possibilty of additional fields in an object. In our example additional fields are prohibited (if they are present object will not pass vaildation against the schema).

Let's call users.get mtehod with parameters user_ids=210700286,297428682, è v=5.52 (Show result in browser).
The server will return JSON:

{"response":[{"id":210700286,"first_name":"Lindsey","last_name":"Stirling"},{"id":297428682,"first_name":"Jared","last_name":"Leto"}]}

This is an object with a single response field which contains an array with a basic VK user info Inserted object contains the same three fields: id — integer, user ID; first_name — string, first name; last_name — string, last name.

JSON schema for this object:

Repository contains 4 .json files.

Describes all API methods. For example, users.get:


Describes format of objects which returns in a methods responses. For example, "audio_audio_album":


Object name consists of methods section name and object name separated with underscore.

Describes methods responses format. For example account.getProfileInfo method response:


Describes additional keywords using in schema, sush as "method", "error", "parameter" and other. It's necessary to extend JSON Schema possibilites over the specification. For example, we use "error" keyword.


Separation of the files is only necessary for the manual data retrieval. Use them individually is meaningless, because every scheme refers to all the others.

The schema is ready for the creation of clients using almost any programming language and who are also working with VK API. The formal description of these data structures allows the usage of code generators along with a significant economization of time, while paying maximum attention to the logic of your app.

An example of this is Java SDK for VK API, which was implemented with the help of code generators using JSON-schema.