zaboday / specs Goto Github PK

Данный репозиторий содержит публичные спецификации, связанные с проектом "Автокод".

Поля данных (далее по тексту - филдлы) обладают следующими свойствами:

• Филд имеет уникальный путь (path);
• Пути (path) филдов являются фиксированными;
• Имя филда данных состоит из букв латинского алфавита в нижнем регистре;
• При необходимости разделить имя филда данных на составные слова используется символ "подчеркивания" (_);
• Для группировки различных филдов используется нотация с помощью точки (.);
• Глубина "вложенности" нотаций может быть произвольной;
• Для указания того, что элемент пути филда является массивом используется обозначение [] (добавляется в конец группы филда).
• Для указания типа данных, которые может содержать филд могут использоваться следующие ключевые слова - array, boolean, float, integer, object, string, null;
• Каждый филд может быть null.

Пример нотации с помощью точки:

Имеется набор филдов: name, year, vin, owner_name. Все они относятся к базовым характеристикам ТС, кроме owner_name, который относится к данным владельца. В этом случае их именование будет иметь следующий вид: base.name, base.year, base.vin, owner.owner_name.

Пример использования указателя массива:

Отчёт содержит набор данных о датах и местах прохождения технического осмотра ТС. Филды этих данных имеют вид diagnostic_card.items[].date и diagnostic_card.items[].place соответственно. Это означает, что diagnostic_card.items[] - это массив, элементами которого являются объекты, имеющие ключи date и place.

Описание всех филдов вы можете найти в данном файле, json-schema отчёта располагается в этом файле.

Примеры отчётов: с данными, без данных.

Для создания отчёта необходимо передать тип и значение идентификатора (VIN-код, номер СТС и т.п.).

Поддерживаемые типы идентификаторов и их описания перечислены в данном файле.

Для формирования данных отчёта происходят обращения к различным источникам. Каждый источник обладает следующими свойствами:

• Имя источника состоит из букв латинского алфавита в нижнем регистре;
• Для группировки различных источников используется нотация с помощью точки (.);
• Каждый источник наполняет данными фиксированный набор филдов;
• Если несколько источников наполняют данными одни и те же филды - в отчёт попадают данные от того источника, который нами считается наиболее доверительным.

Со всеми поддерживаемыми нами источниками вы можете ознакомиться в данном файле.

Отчет может содержать данные о марках и моделях транспортных средств, включая их уникальные идентификаторы, состоящие из символов A-Z, цифр и символа _.

Со всеми поддерживаемыми нами идентификаторами вы можете ознакомиться в файлах марок и моделей.

Модели поделены по категориям типа ТС. Пример: models_bus.json - автобусы.

С идентификаторами типов моделей вы можете ознакомится в файле спецификации.

Данные, содержащиеся в данном репозитории обновляются с течением времени. Измененные состояния фиксируются с помощью тэгирования с присвоением соответствующего значения версии. Значения версий присваиваются в соответствии с правилами семантического версионирования.

На данный момент существуют 3 мажорные версии:

• v1 - устаревшая (не поддерживается с 22 июня 2018 года);
• v2 - устаревшая (не поддерживается с 19 февраля 2019 года);
• v3 - актуальная.

Для того, что бы получать уведомления об изменениях - подпишитесь на них, перейдя по этой ссылке.

Данный репозиторий содержит SDK для удобного доступа к данным спецификаций.

Для установки выполните в терминале следующую команду:

$ composer require avtocod/specs "^3.0"

Для этого необходим установленный composer. Для его установки перейдите по данной ссылке.

Обратите внимание на то, что необходимо фиксировать мажорную версию устанавливаемого пакета.

После этого вы сможете получать, например, спецификации по филдам в вашем php-приложении следующим образом:

<?php

$fields_specifications = \Avtocod\Specifications\Specifications::getFieldsSpecification();

Для получения информации об остальных возможностях - смотрите исходный код.

Если у вас возникли какие-либо проблемы при работе с данным репозиторием, пожалуйста, создайте соответствующий issue перейдя по данной ссылке.