Верховна Рада України
Портал відкритих даних

Структура набору даних

Кожен набір даних обов’язково повинен мати опис структури даних. Логічна структура включає набір полів, їх формат, параметри та призначення. Якщо структура має деревовидний вигляд, то додатково вказується ключ структури верхнього рівня. Будь-яку логічну структуру можна описати у вигляді звичайної таблиці:

section – Група елементу (якщо є);
element – Назва елементу (ключ);
format – Формат елементу (його тип);
attributes – Опис атрибутів (через кому);
annotation – Опис або призначення елементу.

Таким самим чином можна описати структуру всієї бази даних або її частини в табличному вигляді, де section вказуватиме на назву таблиці, element – назву поля, format – відповідно, формат поля таблиці, attributes – параметри поля (індекси, значення по замовчанню, обмеження тощо), annotation – опис поля або таблиці.

Для обробки та ідентифікації даних у відкритих форматах існують відповідні представлення – фізичні структури даних у спеціальних форматах. Для XML – це стандартний формат XSD (XML Schema Definition) http://www.w3.org/XML/Schema , для JSON – http://json-schema.org/ . Інші формати (наприклад, CSV) подають опис структури у машиночитному форматі у вигляді таблиці.

Як приклад, розглянемо універсальну структуру довідника бази даних. Задачею будь-якого довідника в базі даних є збереження інформації за ключовим виразом, частіше за все – це назва, але інколи у довідниках зберігають декілька полів (кілька назв для різних мов та відображень, інші реквізити). В загальному випадку тип dictionary включає обов'язковий ключ id (тип – integer), один чи декілька полів назви name (тип – string) і необов’язкові поля для інших значень value (тип – variant) з атрибутом назви поля name.

Група
section
Елемент
element
Формат
format
Параметри
attributes
Призначення
annotation
dictionaries dictionary array name:string,
[source:string]
Довідник бази даних dictionary з назвою name, таблиця бази даних – source.
dictionary item object id:integer Псевдоелемент item довідника dictionary з ідентифікатором id. Тип комплексний.
item id integer index:boolean,
[field:string]
Ідентифікатор id запису довідника, назва поля з таблиці бази даних – field, ознака ключового поля, за яким можна шукати – index. Тип – число.
item name{1,} string [lang:string],
[field:string]
Назва name запису довідника. Можна вказати мову lang, якщо довідник багатомовний, або назву поля з таблиці бази даних – field. Тип – рядок.
item value{0,} variant name:string,
[reference:string],
[refId:integer],
[field:string]
Необов'язкове значення value поля з іменем name, можливе посилання на інший довідник reference за ідентифікатором refId. Тип – довільний.

У фігурних дужках «{}» вказується кількість елементів групи. Якщо від 0, то це не обов’язковий елемент (minOccurs="0"), якщо максимальна кількість не вказана, то значить він може повторюватись без обмежень (maxOccurs="unbounded"). По замовчанню – це один елемент {1}. В квадратних дужках «[]» вказуються необов’язкові атрибути (use="optional").

Формати елементів або типи даних можуть бути прості (simpleType) і складні або комплексні (complexType). До простих стандартних типів відносяться: рядок – string, число – integer (byte, short, double), логічне значення – boolean, дата – date, дата з часом – dateTime, посилання URL – anyURI. Інші типи, якщо потрібно, можна визначити окремо або імпортувати у вигляді файлу.

Приклад схеми довідника dictionary.xsd:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<xsd:element name="dictionary" type="dictionaryType"/>
	
	<xsd:complexType name="dictionaryType">
		<xsd:annotation>
			<xsd:documentation xml:lang="en">Database dictionary for Opendata</xsd:documentation>
			<xsd:documentation xml:lang="uk">Довідник бази даних з назвою name, таблиця бази даних – source. Для відкритих даних.</xsd:documentation>
		</xsd:annotation>
		<xsd:sequence>
			<xsd:element name="item" type="itemType" maxOccurs="unbounded"/>
		</xsd:sequence>
		<xsd:attribute name="name" type="xsd:string"/>
		<xsd:attribute name="source" type="xsd:string" use="optional"/>
	</xsd:complexType>
	
	<xsd:complexType name="itemType">
		<xsd:annotation>
			<xsd:documentation xml:lang="en">Dictionary item</xsd:documentation>
			<xsd:documentation xml:lang="uk">Елемент довідника dictionary з ідентифікатором id.</xsd:documentation>
		</xsd:annotation>
		<xsd:sequence>
			<xsd:element name="id">
				<xsd:annotation>
					<xsd:documentation xml:lang="en">Identification number</xsd:documentation>
					<xsd:documentation xml:lang="uk">Ідентифікатор запису довідника, поле з таблиці бази даних – field, ознака index – що це ключове поле, за яким можна шукати. Тип – число.</xsd:documentation>
				</xsd:annotation>
				<xsd:complexType>
					<xsd:simpleContent>
						<xsd:extension base="xsd:integer">
							<xsd:attribute name="index" type="xsd:boolean"/>
							<xsd:attribute name="field" type="xsd:string" use="optional"/>
						</xsd:extension>
					</xsd:simpleContent>
				</xsd:complexType>
			</xsd:element>
			<xsd:element name="name" type="xsd:nameType" minOccurs="1" maxOccurs="unbounded"/>
			<xsd:element name="value" type="xsd:valueType" minOccurs="0" maxOccurs="unbounded"/>
		</xsd:sequence>
		<xsd:attribute name="id" type="xsd:integer"/>
	</xsd:complexType>
	
	<xsd:complexType name="nameType">
		<xsd:annotation>
			<xsd:documentation xml:lang="en">Item's name</xsd:documentation>
			<xsd:documentation xml:lang="uk">Назва запису довідника. Можна вказати мову lang, якщо довідник багатомовний. Тип – рядок.</xsd:documentation>
		</xsd:annotation>
		<xsd:simpleContent>
			<xsd:extension base="xsd:string">
				<xsd:attribute name="lang" type="xsd:string" use="optional"/>
				<xsd:attribute name="field" type="xsd:string" use="optional"/>
			</xsd:extension>
		</xsd:simpleContent>
	</xsd:complexType>

	<xsd:complexType name="valueType">
		<xsd:annotation>
			<xsd:documentation xml:lang="en">Item's value</xsd:documentation>
			<xsd:documentation xml:lang="uk">Будь-яке значення поля field з іменем name, можливе посилання на інший довідник reference за ідентифікатором refId. Тип – довільний.</xsd:documentation>
		</xsd:annotation>
		<xsd:simpleContent>	
			<xsd:extension base="xsd:string">
				<xsd:attribute name="name" type="xsd:string"/>
				<xsd:attribute name="reference" type="xsd:string" use="optional"/>
				<xsd:attribute name="refId" type="xsd:integer" use="optional"/>
				<xsd:attribute name="field" type="xsd:string" use="optional"/>
			</xsd:extension>
		</xsd:simpleContent>
	</xsd:complexType>
</xsd:schema>

Приклади даних в форматі XML по цій структурі будуть виглядати так:

<?xml version="1.0"?>
<dictionary name="orgname" source="ORGAN">
	<item id="1">
		<id field="ORGID" index="true">1</id>
		<name field="NAZPOL">Верховна Рада України</name>
		<name field="NAZKOR">Верховна Рада України</name>
		<name lang="en">Verkhovna Rada of Ukraine</name>
		<name lang="ru">Верховная Рада Украины</name>
	</item>
	<item id="2">
		<id field="ORGID" index="true">2</id>
		<name field="NAZPOL">Кабінет Міністрів України</name>
		<name field="NAZKOR">Кабінет Міністрів України</name>
		<name lang="en">Cabinet of Ministers of Ukraine</name>
		<name lang="ru">Кабинет Министров Украины</name>
	</item>
	<item id="60">
		<id field="ORGID" index="true">60</id>
		<name field="NAZPOL">Міністерство юстиції України</name>
		<name field="NAZKOR">Мін'юст України</name>
		<name lang="en">Ministry of Justice of Ukraine</name>
		<name lang="ru">Министерство юстиции Украины</name>
	</item>
</dictionary>

Параметри елементів source і field в цій схемі допомагають описувати фізичну структуру таблиць бази даних, яка застосовується при обміну інформацією у відкритому форматі між різними базами даних. Якщо структура має окремий файл трансформації або обробка відбувається в одній базі даних, вони не є обов’язковими.

Безумовно, в базах даних одним довідником не обмежуються, тому для зручності обміну довідників між різними базами даних їх можна зберегти в одному файлі у вигляді групи dictionaries.

Ідентифікатори id повинні бути унікальними всередині кожного довідника, але можуть співпадати з іншими довідниками та структурами документу. Для посилання на інший довідник (або іншу структуру) потрібно використовувати пару атрибутів: reference та refId. В цьому випадку ідентифікатор refId буде належати до іншого довідника dictionary групи dictionaries з вказаною назвою name=reference.

Загальна схема dictionary в форматі відкритих даних CSV:

section,element,format,attributes,annotation
dictionaries,dictionary,array,"name:string,[source:string]","Довідник бази даних з назвою name, таблиця бази даних – source."
dictionary,item,object,"id:integer","Елемент довідника dictionary з ідентифікатором id. Тип комплексний."
item,id,integer,"index:boolean,[field:string]","Ідентифікатор запису довідника, поле з таблиці бази даних – field, ознака index – що це ключове поле, за яким можна шукати. Тип – число."
item,"name{1,}",string,"[lang:string],[field:string]","Назва запису довідника. Можна вказати мову lang, якщо довідник багатомовний. Тип – рядок."
item,"value{0,}",variant,"name:string,[reference:string],[refId:integer],[field:string]","Будь-яке значення поля field з іменем name, можливе посилання на інший довідник reference за ідентифікатором refId. Тип – довільний."

Але простий варіант з двох полів (ключа та назви) у форматі з комами CSV буде виглядати так dict-simple.csv:

section,element,format,attributes,annotation
item,id,integer,index,Ідентифікатор
item,name,string,,Назва

Для двох назв (повної та короткої) структура orgname-stru.csv буде така:

section,element,format,attributes,annotation
item,id,integer,index,Ідентифікатор
item,fullname,string,,Повна назва
item,name,string,,Коротка назва

Дерево класифікатора в форматі CSV описується двома файлами. Перший – звичайний довідник назв (наприклад, як dict-simple.csv), а інший – опис деревовидної структури klastree-stru.csv:

section,element,format,attributes,annotation
item,id,integer,index,Ідентифікатор
item,parid,integer,,Ідентифікатор верхнього рівня
item,level,integer,,Рівень дерева
item,code,short,,Код елемента класифікатора
item,codefull,string,,Повний код класифікатора
item,subids,string_array[|],,Ідентифікатори нижнього рівня (розділені символом ‘|’)

Тип string_array[|] в цьому випадку вказує на додаткову обробку рядку, який насправді є масивом елементів, розділених символами в квадратних дужках.

Якщо елементи мають більш складні типи, то ці типи позначаються символом @ та описуються в заголовку структури.
Наприклад так doc-stru.csv:

section,element,format,attributes,annotation
@stan_card,status,short,reference=stan,Стан документа з довідника stan
@stan_card,status_from,date,,Дія стану з (дата)
@stan_card,status_to,date,,Дія стану по (дата)
@org_card,orgid, string_array[|],reference=orgs,Ідентифікатори видавників (через |)
@org_card,orgdat,string_array[|],,Дати прийняття документу (через |)
@org_card,orgnum,string_array[|],,Номери документу (через |)
@min_card,minid, string_array[|],reference=orgs,Ідентифікатори видавників (через |)
@min_card,mindat,string_array[|],,Дати реєстрації документу (через |)
@min_card,minnum,string_array[|],,Номери реєстрації документу (через |)
doc,dokid,integer,index,Ідентифікатор документу
doc,nreg,string,,Системний номер документу
doc,nazva,string,,Назва документу
doc,status,string_array[:],@stan_card,,Стан документу (складний тип)
doc,types,string_array[|],reference=typs,Види документу (розділені символом |)
doc,organs,string_array[:],@org_card,"Видавники документів. Містять інформацію про дати прийняття та номери"
doc,minjust,string_array[:],@min_card,"Реєстрація документів. Включає код органу, дату та номер реєстрації"
doc,npix,byte,,Номер картинки для відображення у списку


вгору