Parsing instructions

This doc describes the parsing/import instructions used in the google sheet tables meant to be imported to inkVisitor DDB1.DDB1, which conforms to DDM (=DISSINET DATA MODEL).

The instructions were mostly improvised in the conversations between DZ and TH, they changed a lot during the development of the inkVisitor data model and parsing. E.g. the system and terminology probably are far from ideal.  Sorry for that. :) 

Prerequisities

It is helpful to understand the issues around properties, metaproperties and 2nd order metaproperties.

Basics

The first four rows of the google sheet table (designated for parsing+import to inkVisitor DDB1) form the parsing header.

The fifth row contain a header row with column labels.

Each other row represents one "main entity", e.g. "Person" or "Location".

The foundational part of import instructions parsing instruction keywords (e.g. discard, inside, ...), sitting in the 4th row. 

The four rows are:

1. comment- anything can be here, it is for humans, mostly used for the definition of the "special" instruction
2. target variableobject  - for parameters of relational instructions, (e.g. "id")
3. target type -  for parameters of relational instructions (e.g. "R0002"),  for the first part of the property type-value pairs, i.e.  dog has "color" (type)  "brown" (value)
4. parsing keyword  (e.g. "referece_partreference_part") - primary information on what to do with the column data
5. the label /name of the column

Generally, there are three types of instructions

• simple, they do not need other parameters (e.g. inside, discard)
  
• relational,  they specify relational data and need other parameters (e.g. propvalue, relation)
• special,  they are specified in natural language in the comment row

Here are all possible keywords:

simple	inside, discard, hooked-inside
relational	relation, reference_part, propvalue, proptype, proptype_2nd, propvalue_2nd, hooked-relationrelation, hooked-propvalue
special	special

All columns in the table meant for parsing and import should have an instruction header!

Meaning of the parsing instruction keywords

Simple

inside	the content in the column is meant to be directly ininside the entity objects, e.g. for columns like "label" or "note", that target entity need to have such attribute specified by the data model
discard	the content in the column is just ignored
hooked-inside	the content in the column is meant to be partinside of some "embedded object"object", which is always defined by the preceding special column

Relational

	description	param1 type	param2 target object	the cell can contain
relation	for making DDM "Relation"	name of the relational type (e.g. "Classification", "Identification")	can be empty but usually contains "id" as a signal that this entity is connected to the main entity	a concept legacyId, e.g. C3166 (defendant deposition)
reference_part	for making DDM references to resources	resource ID (e.g. R0002)	can be empty but usually contains "id" as a signal that this entity is connected to the main entity	string of the pages, e.g. "216 (319)", which is transformed to Value object
propvalue	for making metaproperty, where the type is A. fixed for whole column  OR B. defined by main entity field with proptype instruction	a concept, which defines type, e.g. C0316 (occupation)	empty OR name of the column with proptype	entity legacyId, or string which is transformed to Value object
proptype	for making metaproperty, where the type can differ		empty	the C entity
proptype_2nd	for making 2nd metaproperty, where the type can differ
propvalue_2nd	for making 2nd metaproperty, where the type is A. fixed for whole column  OR B. defined by main entity field with proptype instruction	a concept, which defines type, e.g. reference_partC0316 (occupation)	name of the propvalue column, to which this 2nd order property is hooked	entity legacyId, or string which is transformed to Value object
hooked-relation
hooked-propvalue
proptype
proptype_2nd
propvalue_2nd
hooked-relation

Special

special