{% extends 'base.html' %}
{% block title %}Предварительная база деклараций{% endblock title %}


{% block content %}

<h1>Спецификация выходного JSON СмартПарсера, версия 3.0 </h1>


<h2>Вводная информация </h2>

<p>
    Каждый год российские чиновники публикуют декларации о доходах и имуществе. Форматы документов могут быть разными -
    Excel, Word, PDF, HTML. Для качественного использования публикуемых данных требуется их приведение в единый
    машиночитаемый формат и дальнейшая обработка (связывание отдельных записей в цепочку, относящуюся
    к одному должностному лицу). Для краткости мы будем называть декларантами или персонами всех должностных лиц,
    которые публикуют сведения о своих доходах.
</p>

<p>
    Первая часть этого процесса - парсинг исходных файлов. Из входных формата Excel, Word, PDF, HTML данные переводятся
    в формат json. Разработка парсера ведется, в том числе в открытом режиме в <a
        href=https://github.com/TI-Russia/smart_parser>репозитории на Гитхабе </a>.
</p>

<p> В сведениях о доходах и имуществе, публикуемых в соответствии с действующим антикоррупционным законодательством,
    указывается следующая информация: </p>
<ul>
    <li>Фамилия, имя, отчество декларанта;</li>
    <li>Сумма годового дохода (руб.);</li>
    <li>Транспортные средства;</li>
    <li>Недвижимость;</li>
    <li>Должность декларанта;</li>
    <li>Департамент, в котором работает декларант (или подведомственная организация)</li>
    <li>Доход, транспортные средства и недвижимость для супруг и несовершеннолетних детей без указания ФИО</li>
</ul>


<p> Пример входной таблицы [1]: </p>

<img src=/static/images/declaration_example.png> </img>


<h2>Описание JSON формата </h2>


<p> Один json-файл имеет следующую структуру:
    {<br/>
    “persons”: [массив всех декларантов, найденных в документе ], <br/>
    “document”: {описание документа, который был распарсен} <br/>
    }<br/>


<p> В поле document идёт описание документа, который был обработан парсером в процессе парсинга. В нём могут быть
    следующие поля: </p>
<ul>
    <li> year - заполняется, если известен год декларируемых доходов;</li>
    <li>sheet_number - для Excel документов, рекомендуется разбивать JSON по листам, указывая в этом поле номер листа,
        данные из которого содержатся в текущем JSON файле.
    </li>
    <li>sheet_title - для Excel документов, полный заголовок листа, обычно печатается в верхних строках документа
        (например, "Сведения о доходах, об имуществе и обязательствах имущественного характера федеральных
        государственных гражданских служащих Министерства сельского хозяйства Российской Федерации и членов их семей за
        отчетный период с 1 января 2012 г. по 31 декабря 2012 г. Департамент регулирования агропродовольственного рынка,
        рыболовства, пищевой и перерабатывающей промышленности")
    </li>
</ul>
</p>

<p> В поле persons находится массив всех персон (декларантов, найденных в
    документе). </p> Основные поля каждого элемента этого массива: <br/>
{ <br/>
“person”: { <br/>
‘name_raw’: “string”, <br/>
‘department’: “string”, <br/>
‘role’: “string”,
}, <br/>
“document_position”: “string”, <br/>
“person_index”: “number”
“incomes”: [array], <br/>
“real_estates”: [array], <br/>
“vehicles”: [array], <br/>
} <br/>

<p>
    Отдельно, требования по данным указаны ниже, вместе с описанием методов парсинга.
</p>

<h2> Поле ФИО декларанта person/name_raw </h2>


<p> Встречается два основных способа написания в декларациях: </p>
<ul>
    <li>Фамилия Имя Отчество (Иванов Иван Иванович)</li>
    <li>Фамилия И. О. (Иванов И. И.)</li>
</ul>
<p> Обычно эта информация записана в одной ячейке таблицы. Если ФИО содержит больше трех слов, так его и оставлять - это
    разрешено. </p>

<p> Парсинг ФИО осложняется тем, что иногда в этой же ячейке идет информация о должности декларанта (поле role).</p>


<h2>Поле person/department (отдел или подведомственная организация, где работает декларант) </h2>

<p> Отдел, в котором работает декларант, может находиться в отдельном столбце, а может стоять выше по таблице, когда
    декларанты идут группами, где каждая группа декларантов работает в одном отделе: </p>

<img alt=“Пример входной таблицы [2]“ src=/static/images/department_example.png width=800/>


<p> В последнем случае у всех декларантов одной группы будет одинаково заполнено поле person/department. Поле
    person/department может отсутствовать, тогда считается, что все декларанты работают в головной организации, которая
    опубликовала этот документ. </p>

<h2> Поле person/role (должность декларанта) </h2>

<p> В поле person/role записывается должность, на которой работает декларант. Обычно эта должность идет в отдельном
    столбце (см. примеры выше). </p>


<h2> Поле адреса внутри документа (document_position) </h2>

<p> Для будущего анализа результатов парсинга нужно указать место в документе, где именно была обнаружена данная
    секция: </p>
<ul>
    <li> Для Excel - это адрес ячейки (например, “A:12”)</li>
    <li> Для Doc или PDF - это номер страницы документа.</li>
</ul>

<h2> Порядковый номер персоны (person_index) </h2>

<p> Иногда в документе перед каждой персоной в отдельном столбце указан её порядковый номер в данном документе. В таких
    случаях этот номер надо указать в данном поле. Пример (первый столбец):
    <img alt=“Пример входной таблицы [2]“ src=/static/images/declarant_index.png> </img>

<p> Иногда порядковый номер указывается для департамента и объединяет несколько персон. В таких случаях это поле не
    нужно заполнять. </p>

<h2> Родственники (тип relative_type) </h2>

<p> Все объекты владения (доход, транспортное средство или недвижимость) содержат поля relative с допустимыми
    значениями: "Супруг(а)", "Ребенок" или null. Это поле обозначает, к кому относится данная запись, например, что
    машина супруги Значение null означает, что эта запись относится к основному декларанту. </p>


<h2> Сумма годового дохода (incomes) </h2>

<p> Сумма годового дохода обычно указывается в отдельной ячейке. Почти всегда есть доход основного декларанта. Кроме
    этого, в декларациях записана информация о доходах супруг(ов). Для каждого дохода вносится следующая запись:
    { <br/>
    “size”: number <br/>
    “size_raw”: string <br/>
    “relative”: relative_type <br/>
    } <br/>

<p> Поле size - это доход чиновника в рублях, иногда они пишут с точностью до копейки, тогда возникает не целочисленное,
    а число с плавающей точкой - это разрешено. </p>
<p> Поле size_raw - исходное сырое строковое значение ячейки с суммой дохода. </p>
<p> Во входных таблицах доход чаще всего встречается в виде числа с плавающей точкой, иногда с “руб.” или “р.” на конце,
    что нужно отбросить, так как по JSON схеме поле size должно быть number. </p>
<p> Внимание! Иногда сумма обозначается в тысячах рублей, что может быть указано как после цифры, так и в заголовке
    столбца. В таком случае приведенное в исходном файле число надо умножить на 1000. Существует еще формат “11 рублей
    50 копеек", который надо преобразовать к флоату (11.50). </p>
<p> Также иногда в декларациях встречается комментарий к источнику дохода, обычно указываемый рядом с суммой дохода в
    скобках, например, “часть дохода получена от продажи дома”. Эти строки надо внести в поле
    "/persons/incomes/comment". </p>
<p>В случае, когда доходы не указаны совсем, следует оставить пустым список в JSON “/persons/incomes”. </p>

<h2> Транспортные средства (поле vehicles) </h2>

<p> Транспортные средства обычно указываются в отдельных столбцах, и могут быть преобразованы в следующие поля:
    { <br/>
    “relative”: relative_type <br/>
    “text” : string, <br/>
    “type_raw”: string, <br/>
    “manufacture_year”: number, <br/>
    “own_type_raw”:string <br/>
    }<br/>
</p>
<p> В большинстве случаев в транспортных средствах заполняется только поле text и поле relative. Разделение информации о
    машинах на отдельных элементы оставлен на последующие этапы. Пример записи о транспортном средстве: </p>
<p>
    "vehicles": [ <br/>
    { <br/>
    "text": "а/м легковой Тойота Ланд Крузер Прадо", <br/>
    "relative": null <br/>
    . } <br/>
    Может быть и несколько транспортных средств в одной ячейке: <br/>
    "vehicles": [ <br/>
    {
    "text": "а/м легковой Ауди; Квадроцикл Ямаха", <br/>
    "relative": "Супруг(а)" <br/>
    } <br/>/
<p> Если описание транспортных средств разделено на разные колонки, тогда их обязательно надо конкатинировать через
    пробел в поле text (и дополнительно оставить в отдельных полях):
<ul>
    <li>Поле type_raw - вид транспортного средства - заполняется, если вид транспортного средства был указан в отдельной
        ячейке, например: “Автомобиль”, “А/м”, “Грузовой транспорт”, “Лодка”, “Снегоход”
    </li>
    <li>Поле "manufacture_year" - год выпуска -указывается, если был указан в отдельной графе;</li>
    <li> Поле own_type_raw - тип владения заполняется сырым строковым значением, если был указан в отдельной ячейке.
    </li>
</ul>

<h2> Недвижимость (поле real_estates) </h2>

<p> В сведениях о доходах обычно отдельно указываются объекты недвижимости в собственности и находящиеся в пользовании.
    Как правило, в исходной таблицы они располагаются в отдельных группах столбцов: левее группа из 4 столбцов,
    касающаяся недвижимости в собственности, правее 3 столбца о недвижимости в пользовании. </p>

<img src=/static/images/realty_example.png>

<p> В некоторых случаях оба типа недвижимости объединены в один столбец, а режим использования уточняется в скобках.
    Один объект недвижимости описывается следующими полями: </p>
{ <br/>
“own_type_by_column”: “В собственности” | “В пользовании” <br/>
“own_type_raw”: string,  <br/>
“relative”: relative_type <br/>
“type_raw”: string, <br/>
“square”: float, <br/>
“square_raw” : string,  <br/>
“country_raw”: string <br/>
“text”: string <br/>
} <br/>
Например: <br/>
{ <br/>
“own_type_by_column”: “В собственности”, <br/>
"own_type_raw": "Индивидуальная", <br/>
"type_raw": "Земельный участок", <br/>
"text": "Земельный участок", <br/>
"square_raw": "1500.00", <br/>
"square": 1500.00, <br/>
"country_raw": "Россия", <br/>
"relative": null <br/>
} <br/>


<p> Для того, чтобы отделить эти два типа используется поле own_type_by_column (личной собственности соответствует
    значение “В собственности”, и для пользования - "В пользовании"). </p>

<p>Поле own_type_raw заполняется, когда присутствуют отдельный столбец с уточнением типа владения. Столбец обычно
    называется “вид собственности”, примеры значений такие: </p>
<ul>
    <li> “индивидуальная”,</li>
    <li> “долевая собственность ½”</li>
    <li> “общая собственность”</li>
    <li> “совместная собственность”</li>
</ul>

<p> Поле type_raw содержит тип недвижимости (квартира, земельный участок, дача и пр). В этом же поле содержится иногда
    указание доли владения. Поле square_raw содержит площадь недвижимости в метрах квадратных. Поле square содержит
    преобразованное во float значение поля square_raw. Поле country_raw содержит страну, в которой находится данный
    объект недвижимости. Иногда type_raw и own_type_raw записаны во входной таблице в одной ячейке, в таких случаях,
    содержимое этой ячейки пишется в поле text, а поля type_raw и own_type_raw не заполняются. </p>

<img src=/static/images/realty_example2.png width=800>


<p> Если же type_raw и own_type_raw разделены, тогда в поле text пишется (дублируется) значение поля type_raw. Поле text
    является обязательным. </p>

<h2> Недвижимость без разделения на колонки </h2>

<p> Встречаются документы, где недвижимость указана в одной колонке, в одной строке включены сразу все данные - площадь,
    вид и тип владения. В таких случаях эту строку надо заносить в поле text. </p>
<p> Бывает, что в одной колонке вместе указывается вид недвижимости и тип собственности, которые также надо заносить в
    поле text, а площадь и страну заносить в соответствующие поля - square_raw и country_raw. </p>

<p> Пример: </p>

<img src=/static/images/realty_example3.png width=800 />

<p>Иногда даже отсутствуют площадь и тип владения, есть только описание объекта.
    Пример: </p>

<img src=/static/images/realty_example4.png width=800>

<p> В таких случаях содержимое этой одной колонки целиком должно быть записано в поле text, но если
    колонки две (как в примере выше), то по ним должен быть определено и записано поле own_type_by_column. </p>

<p>
    <a href="https://docs.google.com/document/d/17IszYNrnsJzxJCZa9hUbjWvlNRCdIDdB2t58M0ojMEY">Предыдущая версия этого документа </a>
</p>

{% endblock content %}