Coder Social home page Coder Social logo

vk-api-schema's Introduction

VK API JSON Schema

This repository contains JSON Schema documents explaining all the VK.COM API objects and methods mentioned here.

JSON Schema standard specifications and the most common usage scenarios could be found here: http://json-schema.org/

These schemes are compatible with JSON Schema version draft-07 and VK API version 5.199.

Packagist

Structure

Repository contains several .json files.

  • "methods.json" describes all of VK API methods (could be found at this page).
  • "objects.json" describes objects which are used in methods responses.
  • "responses.json" describes methods responses structure.
  • "errors.json" describes possible method errors.
  • "schema.json" describes additional keywords used in our implementation, such as "method", "error", "parameter" and others so to extend the canonical specification for our needs.

Samples

users.get method description:

{
      "name": "users.get",
      "description": "Returns detailed information on users.",
      "open": true,
      "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": "domains",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "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';",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "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"
        }
      ],
      "responses": {
        "response": {
          "$ref": "responses.json#/definitions/users_get_response"
        }
      }
    }

market_market_album object description:

"market_market_album": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Market album ID",
          "minimum": 1
        },
        "owner_id": {
          "type": "integer",
          "description": "Market album owner's ID"
        },
        "title": {
          "type": "string",
          "description": "Market album title"
        },
        "count": {
          "type": "integer",
          "description": "Items number",
          "minimum": 0
        },
        "updated_time": {
          "type": "integer",
          "description": "Date when album has been updated last time in Unixtime",
          "minimum": 0
        },
        "photo": {
          "$ref": "#/definitions/photos_photo"
        }
      },
      "required": [
        "id",
        "owner_id",
        "title",
        "count",
        "updated_time"
      ]
    }

vk-api-schema's People

Contributors

alatushkin avatar allebdev avatar alsemyonov avatar aotd1 avatar apiwoman avatar fedorov-xyz avatar klimrmad avatar mobyman avatar nk2ge5k avatar pale-emperor avatar strixg avatar tsivarev avatar yurybandarchuk16 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

vk-api-schema's Issues

groups_group_link отсутствует поле name

https://vk.com/dev/groups.addLink

name (string) — название ссылки в блоке сообщества;

vk-api-schema/objects.json

Lines 4060 to 4084 in c5958b1

"groups_group_link": {
"type": "object",
"properties": {
"desc": {
"type": "string",
"description": "Link description"
},
"edit_title": {
"description": "Information whether the title can be edited",
"$ref": "#/definitions/base_bool_int"
},
"id": {
"type": "integer",
"description": "Link ID"
},
"image_processing": {
"description": "Information whether the image on processing",
"$ref": "#/definitions/base_bool_int"
},
"url": {
"type": "string",
"format": "uri",
"description": "Link URL"
}
},

Fix polls.getById response

Описание объекта polls_getById_response в responses.json не соответствует актуальному ответу от сервера, также не соответствует описанию в документации.

"polls_getById_response": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "objects.json#/definitions/polls_poll" } } }, "additionalProperties": false }

В действительности, вместо массива должен быть один объект polls_poll.

Отсутствует описание объекта messages_conversation_peer_type

В объекте messages_conversation_peer в файле objects.json ссылка указывает на объект messages_conversation_peer_type из файла objects.json, однако такого объекта не существует.

Если верить официальной документации, то:

type (string) — тип. Возможные значения: user, chat, group, email

`name_case` is an enum field, so it should provide enum values in responses.json

There is a list of possible values for name_case parameter provided in the description of the parameter.

In some methods (e. g. friends.getAvailableForCall, see https://github.com/VKCOM/vk-api-schema/blob/master/methods.json#L2339) it even provides default values, according to an “imaginary enum”.
But default value 0 is invalid for provided type string, so schema is invalid too.

Please, provide enums for name_case and other enum fields.

Отсутствует описание объекта groups_address_work_info_status

Отсутствует описание объекта groups_address_work_info_status в файле objects.json при наличии ссылок на этот объект.

В официальной документации имеем:

тип расписания. Возможные значения:
no_information — нет информации о расписании;
temporarily_closed — временно закрыто;
always_opened — открыто круглосуточно;
forever_closed — закрыто навсегда;
timetable — открыто в указанные часы работы. Для этого типа расписания необходимо передать параметр timetable;

Проблема с именем "2fa"

У типа "account_info" есть свойство "2fa_required", которые является не очень подходящим. Особенно, появляются проблемы при написании SDK так, как большинство языков не поддерживают названия переменных, которые начинаются с цифры

Сломанный Bots Long Poll Api для бесед

Не реагирует на message_reply и message_edit в беседах
Не возвращает 'id' сообщения в беседах

{'type': 'message_new', 'object': {'date': 1531466618, 'from_id': 463526827, 'id': 42, 'out': 1, 'peer_id': 463526827, 'text': 'тест', 'conversation_message_id': 38, 'fwd_messages': [], 'important': False, 'random_id': 0, 'attachments': [], 'is_hidden': False}, 'group_id': 168230748}

{'type': 'message_reply', 'object': {'date': 1531466618, 'from_id': -168230748, 'id': 43, 'out': 0, 'peer_id': 463526827, 'text': 'тест', 'conversation_message_id': 39, 'fwd_messages': [], 'important': False, 'random_id': 0, 'attachments': [], 'is_hidden': False}, 'group_id': 168230748}

{'type': 'message_new', 'object': {'date': 1531466636, 'from_id': 463526827, 'id': 0, 'out': 0, 'peer_id': 2000000001, 'text': 'тест', 'conversation_message_id': 69, 'fwd_messages': [], 'important': False, 'random_id': 0, 'attachments': [], 'is_hidden': False}, 'group_id': 168230748}

groups_ban_info отсутствует поле comment_visible

https://vk.com/dev/groups.getBanned

Пример ответа

{
  "response": {
    "count": 31,
    "items": [{
      "type": "profile",
      "profile": {
        "id": 205609296,
        "first_name": "Иван",
        "last_name": "Метлов",
        "is_closed": false,
        "can_access_closed": true
      },
      "ban_info": {
        "admin_id": 120158515,
        "date": 1548790301,
        "reason": 0,
        "comment": "Плохо увернулся от бана",
        "comment_visible": true,
        "end_date": 0
      }
    }]
  }
}

vk-api-schema/objects.json

Lines 3382 to 3409 in c5958b1

"groups_ban_info": {
"type": "object",
"properties": {
"admin_id": {
"type": "integer",
"description": "Administrator ID",
"minimum": 1
},
"comment": {
"type": "string",
"description": "Comment for a ban"
},
"date": {
"type": "integer",
"description": "Date when user has been added to blacklist in Unixtime",
"minimum": 0
},
"end_date": {
"type": "integer",
"description": "Date when user will be removed from blacklist in Unixtime",
"minimum": 0
},
"reason": {
"$ref": "#/definitions/groups_ban_info_reason"
}
},
"additionalProperties": false
},

В схеме нет поля comment_visible bool

Отсутствует описание объекта groups_address_timetable_day

В объекте groups_address_timetable в файле objects.json ссылка указывает на объект groups_address_timetable_day из файла objects.json, однако такого объекта не существует.

Судя по ответам от API, объект имеет вид:
{ "open_time": 1080, "close_time": 1380, "break_open_time": 0, "break_close_time": 0 }

Из официальной документации:

open_time, close_time — начало и конец рабочего дня. break_open_time, break_close_time - время перерыва.

storage.get с параметром keys возвращает массив

https://vk.com/dev/storage.get

Пример ответа при keys=test

{"response":[{"key":"test","value":""}]}

vk-api-schema/responses.json

Lines 5103 to 5110 in a47e602

"storage_get_response": {
"type": "object",
"properties": {
"response": {
"type": "string",
"description": "Key value"
}
},

Возможное решение - добавить storage_get_keys_response

P.S. Надо учитывать, что в некоторых языках названия структур в верблюжем стиле - названия storage_getKeys_response и storage_get_keys_response совпадут

objects.json/apps_app отсутствует свойство friends

vk-api-schema/objects.json

Lines 1495 to 1597 in 12c49e6

"apps_app": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Application ID"
},
"title": {
"type": "string",
"description": "Application title"
},
"screen_name": {
"type": "string",
"description": "Screen name"
},
"description": {
"type": "string",
"description": "Application description"
},
"icon_278": {
"type": "string",
"description": "URL of the app icon with 279 px in width"
},
"icon_150": {
"type": "string",
"description": "URL of the app icon with 150 px in width"
},
"icon_139": {
"type": "string",
"description": "URL of the app icon with 139 px in width"
},
"icon_75": {
"type": "string",
"description": "URL of the app icon with 75 px in width"
},
"banner_560": {
"type": "string",
"description": "URL of the app banner with 560 px in width"
},
"banner_1120": {
"type": "string",
"description": "URL of the app banner with 1120 px in width"
},
"type": {
"$ref": "#/definitions/apps_app_type"
},
"section": {
"type": "string",
"description": "Application section name"
},
"author_url": {
"type": "string",
"description": "Application author's URL"
},
"author_id": {
"type": "integer",
"description": "Application author's ID"
},
"author_group": {
"type": "integer",
"description": "Official community's ID"
},
"members_count": {
"type": "integer",
"description": "Members number"
},
"published_date": {
"type": "integer",
"description": "Date when the application has been published in Unixtime"
},
"catalog_position": {
"type": "integer",
"description": "Catalog position"
},
"screenshots": {
"type": "array",
"items": {
"$ref": "#/definitions/photos_photo"
}
},
"international": {
"type": "integer",
"description": "Information whether the application is multilanguage"
},
"leaderboard_type": {
"$ref": "#/definitions/apps_app_leaderboard_type"
},
"genre_id": {
"type": "integer",
"description": "Genre ID"
},
"genre": {
"type": "string",
"description": "Genre name"
},
"platform_id": {
"type": "integer",
"description": "Application ID in store"
},
"is_in_catalog": {
"type": "integer",
"description": "Information whether application is in mobile catalog"
}

friends array - список идентификаторов друзей текущего пользователя, которые установили приложение (если был передан параметр return_friends = 1.)

https://vk.com/dev/objects/app

Описание событий Bots Long Poll API

    "groups_long_poll_events": {
      "type": "object",
      "properties": {
        "message_new": {
          "$ref": "#/definitions/base_bool_int"
        },
...

список событий есть, но описания полей нет

В нескольких методах отсутствует access_token_type

В следующих методах отсутствует массив access_token_type. Без передачи токена методы возвращают ошибку.

  • account.setOffline
  • account.getProfileInfo
  • places.getTypes
  • friends.deleteAllRequests
  • friends.getAppUsers
  • notifications.markAsViewed
  • apps.deleteAppRequests
  • stats.trackVisitor
  • ads.getAccounts

У объекта notes_note нет поля read_comments

https://vk.com/dev/objects/note

read_comments integer - количество прочитанных комментариев (только при запросе информации о заметке текущего пользователя).

vk-api-schema/objects.json

Lines 6900 to 6954 in c5958b1

"notes_note": {
"type": "object",
"properties": {
"can_comment": {
"description": "Information whether current user can comment the note",
"$ref": "#/definitions/base_bool_int"
},
"comments": {
"type": "integer",
"description": "Comments number",
"minimum": 0
},
"date": {
"type": "integer",
"description": "Date when the note has been created in Unixtime",
"minimum": 0
},
"id": {
"type": "integer",
"description": "Note ID",
"minimum": 1
},
"owner_id": {
"type": "integer",
"description": "Note owner's ID",
"minimum": 1
},
"text": {
"type": "string",
"description": "Note text"
},
"text_wiki": {
"type": "string",
"description": "Note text in wiki format"
},
"title": {
"type": "string",
"description": "Note title"
},
"view_url": {
"type": "string",
"format": "uri",
"description": "URL of the page with note preview"
}
},
"required": [
"id",
"owner_id",
"comments",
"date",
"title",
"view_url"
],
"additionalProperties": false
},

pages.getHistory в ответе нет поля edited, но есть date

https://vk.com/dev/pages.getHistory

edited — дата редактирования страницы;

Пример ответа

{
    "response": [{
        "id": 183526239,
        "length": 23,
        "date": 1430756719,
        "editor_id": 2314852,
        "editor_name": "Irina Denezhkina"
    }]
}

json schema

vk-api-schema/objects.json

Lines 7440 to 7464 in c5958b1

"pages_wikipage_version": {
"type": "object",
"properties": {
"edited": {
"type": "integer",
"description": "Date when the page has been edited in Unixtime"
},
"editor_id": {
"type": "integer",
"description": "Last editor ID"
},
"editor_name": {
"type": "string",
"description": "Last editor name"
},
"id": {
"type": "integer",
"description": "Version ID"
},
"length": {
"type": "integer",
"description": "Page size in bytes"
}
}
},

  • Поле edited в ответе отсутствует, но есть поле date.
  • В json schema прописано поле edited

Ошибка или в документации(и json schema), или в api

Поля объекта groups_group не соответствуют описанию.

  1. В объекте "groups_group" свойство "id" имеет тип string, что не соответствует описанию на сайте и также не соответствует актуальному возвращаемому значению. Должен быть указан тип integer.

  2. В объекте "groups_group" свойство "is_admin" имеет тип "integer", но вместе с этим ссылается на "#/definitions/base_bool_int". Тип вообще не должен быть указан в таком случае.

Версия API и версионирование схемы

Думаю имеет смысл добавить версию API в какой-либо json (schema.json?) кроме README.md.

И версионированне схемы какое-то странное, 1.8.0 соответствует версии API 5.74. Возможно стоит использоват такие же версии как у API, но с добавлением версии схемы, типа 5.74_1. И если делается фикс для схемы 5.74, то новая версия будет 5.74_2. Ну и теги к коммитам проставить соответственно, что-то вроде api_5.74_2

Еще судя по всему, вы руками обновляете схему, лучше бы генератор написали какой-то (выложена схема для 5.74, но актуальная версия уже 5.80)

Отсутствие ссылок

При использовании json-schema-to-typescript можно получить много ошибок об отсутствии ссылок ($ref pointer)
К примеру в objects.json отсутствует groups_address_work_info_status

groups_long_poll_server - поле ts это строка, а не число

https://vk.com/dev/groups.getLongPollServer

ts (string) — timestamp.

vk-api-schema/objects.json

Lines 4704 to 4726 in c5958b1

"groups_long_poll_server": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Long Poll key"
},
"server": {
"type": "string",
"description": "Long Poll server address"
},
"ts": {
"type": "integer",
"description": "Number of the last event"
}
},
"required": [
"key",
"server",
"ts"
],
"additionalProperties": false
},

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.