Данный репозиторий содержит публичные спецификации, связанные с проектом "Автокод".
Поля данных (далее по тексту - филдлы) обладают следующими свойствами:
- Филд имеет уникальный путь (
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_car.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
перейдя по данной ссылке.