The translation was generated automatically and may contain mistakes

JSON Schema

JSON Schema is a common standard for describing a data structure. The schema is used to describe JSON data, but it is also a JSON object. With the help of keywords in the scheme, rules for validating the structure of the object and the types of its fields are created. More information about restrictions and types of data — on the official website JSON Schema .

The JSON Schema API VKontakte located at: github.com/VKCOM/vk-api-schema .

Let’s look at a simple example.

Each user VKontakte have an ID id (Number), name first_name (line) and last name last_name (Line). In the API, this data is represented as an object with a set of corresponding fields. In JSON, the object looks like this:

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

A JSON schema describing this object:

JSON
{ "type": "object", "properties": { "id": { "type": "integer", "description": "User ID" }, "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" } }, "required": [ "id", "first_name", "last_name" ], "additionalProperties": false }

Key word required Provides a list of mandatory fields. If at least one of the listed fields is missing, the object will not pass validation according to this scheme.

Key word additionalProperties This allows for the presence of additional fields in the object. In our case, additional fields are forbidden (if they exist, the object will not be validated according to the scheme).

Let’s move on to a more complex structure.

Call the method users.get with parameters user_ids=210700286,297428682 and v=5.52 . In response, the server will return JSON:

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

It’s a single-field object response which, in turn, contains an array of objects with basic information about the VKontakte user.. The nested object contains all the same three fields: id — численное значение, идентификатор пользователя; first_name — string value, user name; last_name — string value, the name of the user.

The JSON schema for this object looks like this:

JSON
{ "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "User ID" }, "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" } }, "required": [ "id", "first_name", "last_name" ] } } } }

Structure

The repository includes 4 .json file.

methods.json

Describes everything aPI methods . For example, the method users.get :

JSON
{ "name": "users.get", "description": "Returns detailed information on users.", "access_token_type": [ "user", "group", "service" ], "parameters": [ { "name": "user_ids", "description": "User IDs or screen names ('screen_name'). By default, current user ID.", "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, { "name": "fields", "description": "Profile fields to return. Sample values: 'nickname', 'screen_name', 'sex', 'bdate' (birthdate), 'city', 'country', 'timezone', 'photo', 'photo_medium', 'photo_big', 'has_mobile', 'contacts', 'education', 'online', 'counters', 'relation', 'last_seen', 'activity', 'can_write_private_message', 'can_see_all_posts', 'can_post', 'universities', 'can_invite_to_chats'", "type": "array", "items": { "$ref": "objects.json#/definitions/users_fields" } }, { "name": "name_case", "description": "Case for declension of user name and surname: 'nom' — nominative (default), 'gen' — genitive , 'dat' — dative, 'acc' — accusative , 'ins' — instrumental , 'abl' — prepositional", "type": "string", "enum": [ "nom", "gen", "dat", "acc", "ins", "abl" ], "enumNames": [ "nominative", "genitive", "dative", "accusative", "instrumental", "prepositional" ] } ], "responses": { "response": { "$ref": "responses.json#/definitions/users_get_response" } } }

objects.json

Describes the format of objects that come in responses from methods. For example, the object audio_audio :

JSON
{ "audio_audio": { "type": "object", "properties": { "access_key": { "type": "string", "description": "Access key for the audio" }, "artist": { "type": "string", "description": "Artist name" }, "id": { "type": "integer", "description": "Audio ID", "minimum": 0 }, "owner_id": { "type": "integer", "description": "Audio owner's ID" }, "title": { "type": "string", "description": "Title" }, "url": { "type": "string", "format": "uri", "description": "URL of mp3 file" }, "duration": { "type": "integer", "description": "Duration in seconds", "minimum": 0 }, "date": { "type": "integer", "description": "Date when uploaded", "minimum": 0 }, "album_id": { "type": "integer", "description": "Album ID", "minimum": 0 }, "genre_id": { "type": "integer", "description": "Genre ID", "minimum": 0 }, "performer": { "type": "string", "description": "Performer name" } }, "required": [ "id", "owner_id", "duration", "artist", "title" ], "additionalProperties": false } }

The name of an object consists of the name of the section whose methods return that object, and the name of the object itself after the underscore.

responses.json

Describes the format of method responses. For example, the method response utils.resolveScreenName :

JSON
{ "utils_resolveScreenName_response": { "type": "object", "properties": { "response": { "$ref": "../utils/objects.json#/definitions/utils_domain_resolved", "required": true } } } }

schema.json

Describes additional entities that are used in the schema, such as method , error , parameter and others. This is necessary to extend the capabilities of the JSON schema by adhering to the specification. For example, we use an entity error :

JSON
{ "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "Error code", "minimum": 0 }, "description": { "type": "string", "description": "Error description" }, "subcodes": { "type": "array", "items": { "$ref": "#/definitions/error_subcode" }, "description": "Array of error subcodes" }, "global": { "type": "boolean", "default": false }, "disabled": { "type": "boolean", "default": false }, "deprecated_from_version": { "$ref": "#/definitions/deprecated_from_version" }, "from_version": { "$ref": "#/definitions/from_version" } }, "required": [ "code", "description" ], "additionalProperties": false } }

File partitioning is only necessary for the convenience of manual data retrieval. It is pointless to use them separately, since each scheme refers to all the others.

Использование

Based on the schema, you can create an API SDK on any platform. You can work with only one section of methods or use all of them to implement a full-featured client.

The scheme allows you to work with code generators, this approach gives you the opportunity to devote more time to the internal logic of your application, saving resources on studying the API data format.

An example of a schema-based SDK you can find on this page .

Если ранее вы не были знакомы с нашим API, мы бы советовали также прочитать это executive direction before the start of work.