Domain Model

• Overview
• Validation
  • DataAcquisitionProject
    • Release
  • Study
    • StudyAttachmentMetadata
  • Survey
    • Population
    • SurveyAttachmentMetadata
  • DataSet
    • SubDataSet
    • DataSetAttachmentMetadata
  • Variable
    • RelatedQuestion
    • FilterDetails
    • GenerationDetails
    • Distribution
      • Statistics
      • Missing
      • ValidResponse
  • Question
    • QuestionImageMetadata
    • TechnicalRepresentation
  • Instrument
    • InstrumentAttachmentMetadata
  • RelatedPublication
  • CodingScheme
    • CodingSchemeAttachmentMetadata
    • Resolution
• DataAcquisitionProject (Post-)Validation
  • DataSet
  • Variable
  • Question
  • Instrument

Overview

The following picture models the relationships and attributes of the domain objects which are managed by our system.

Validation

Before saving an object of the domain model it is validated by our backend. This section describes the validation rules for each attribute of each object.

In addition to the validation per object there will be a DataAcquisitionProject (Post-)Validation which checks the consistency of the data of the entire project.

For Strings and I18nStrings the following abbreviations restrict the max length (number of characters):

• SMALL: 32 characters
• MEDIUM: 512 characters
• LARGE: 2048 characters (2KB)
• X-LARGE: 1 MB

DataAcquisitionProject

Attribute	Validation Rules
id	Mandatory, Max Length SMALL, Lowercase Alphanumeric (english)

Release

Attribute	Validation Rules
version	Mandatory, Max Length SMALL, valid ("major.minor.patch" e.g. "1.0.0"), greater than or equal to previous version
date	Mandatory

Study

Attribute	Validation Rules
id	Mandatory, Max Length SMALL, Lowercase alphanumeric (with German Umlauts and ß), Pattern ("stu-" + dataAcquisitionProjectId + "$")
dataAcquisitionProjectId	Mandatory, equal to id
title	Mandatory (All languages), Max Length LARGE
description	Mandatory, Max Length LARGE
institution	Mandatory, Max Length MEDIUM
studySeries	Max Length MEDIUM
sponsor	Mandatory, Max Length MEDIUM
authors	At least one author, each author must have a first name and a last name
dataAvailability	Mandatory, Must only contain DE: "Verfügbar", "In Aufbereitung", "Nicht verfügbar" and for EN: "Available", "In preparation", "Not available"
surveyDesign	Mandatory, Must only contain DE: "Querschnitt", "Panel" and for EN: "Cross-Section", "Panel"
annotations	Max Length LARGE

StudyAttachmentMetadata

Attribute	Validation Rules
studyId	Mandatory
dataAcquisitionProjectId	Mandatory
type	Mandatory, valid values in german: Daten- und Methodenbericht, Sonstiges. Valid values in english: Method Report, Other
title	Max Length LARGE
description	Mandatory, Max Length MEDIUM
language	Mandatory, Valid ISO 639-1
fileName	Mandatory, Alphanumeric (with German Umlauts) with "_", "-" and "."
indexInStudy	Mandatory

Survey

Attribute	Validation Rules
id	Mandatory, Max Length MEDIUM, Lowercase alphanumeric (with German Umlauts and ß) + "-", Pattern ("sur-" + dataAcquisitionProjectId + "-" + "sy" + survey.number + "$")
number	Mandatory, unique within dataAcquisitionProject
title	Mandatory, Max Length LARGE
fieldPeriod	Mandatory, start before end, Date Format is yyyy-MM-dd (e.g. 2011-12-23)
sample	Mandatory, Max Length LARGE
surveyMethod	Mandatory, Max Length MEDIUM
sampleSize	Mandatory, Minimum 0
grossSampleSize	Minimum 0
responseRate	Minimum 0, Maximum 100
annotations	Max Length LARGE
dataAcquisitionProjectId	Mandatory
studyId	Mandatory
wave	Mandatory
dataType	Mandatory, de: Quantitative Daten or en: Quantitative Data , de: Qualitative Daten or en: Qualitative Data

Population

Attribute	Validation Rules
title	Mandatory Max Length MEDIUM
description	Mandatory, Max Length LARGE

SurveyAttachmentMetadata

Attribute	Validation Rules
surveyId	Mandatory
surveyNumber	Mandatory
dataAcquisitionProjectId	Mandatory
title	Mandatory, Max Length LARGE
description	Mandatory, Max Length MEDIUM
language	Mandatory, Valid ISO 639-1
fileName	Mandatory, Alphanumeric (with German Umlauts) with "_", "-" and "."
indexInSurvey	Mandatory

DataSet

Attribute	Validation Rules
id	Mandatory, Max Length MEDIUM, Lowercase alphanumeric (with German Umlauts and ß) + "-", Pattern ("dat-" + dataAcquisitionProjectId + "-" + "ds" + dataSet.number + "$")
number	Mandatory, unique within dataAcquisitionProject
description	Max Length LARGE
surveyNumbers	Mandatory, Min Size 1
subDataSets	Mandatory, Min Size 1, subDataSets.accessway has to unique within dataSet
type	Mandatory, de = "Personendatensatz", "Episodendatensatz", en = "Individual Data", "Spell Data"
format	de = "breit", "lang", en = "wide", "long"
annotations	Max Length LARGE
dataAcquisitionProjectId	Mandatory
studyId	Mandatory

SubDataSet

Attribute	Validation Rules
name	Mandatory, Max Length SMALL
description	Mandatory, Max Length MEDIUM
accessWay	Mandatory, Must only contain one of "download-cuf", "download-suf", "remote-desktop-suf", "onsite-suf"
citationHint	Max Length LARGE
numberOfObservation	Mandatory

DataSetAttachmentMetadata

Attribute	Validation Rules
dataSetId	Mandatory
dataSetNumber	Mandatory
dataAcquisitionProjectId	Mandatory
title	Mandatory, Max Length LARGE
description	Mandatory, Max Length MEDIUM
language	Mandatory, Valid ISO 639-1
fileName	Mandatory, Alphanumeric (with German Umlauts) with "_", "-" and "."
indexInDataSet	Mandatory

Variable

Attribute	Validation Rules
id	Mandatory, Max Length MEDIUM, Lowercase alphanumeric (with German Umlauts and ß) + "-" + "_", Pattern ("var-" + dataAcquisitionProjectId + "-" + "ds" + variable.dataSetNumber + "-" + variable name + "$")
dataType	Mandatory, de = "string", "datum" or "numerisch", en = "string", "date" or "numeric"
storageType	Mandatory, valid storage types are: "logical", "integer", "double", "complex", "character", "raw", "list", "NULL", "closure", "special", "builtin", "environment", "S4", "symbol", "pairlist", "promise", "language", "char", "...", "any", "expression", "externalptr", "bytecode" and "weakref"
scaleLevel	Mandatory, de = "nominal", "ordinal", "intervall" oder "verhältnis", en = "nominal", "ordinal", "interval" or "ratio"
name	Mandatory, Max Length SMALL, Unique within data set, Lowercase alphanumeric (english) + "_" and must not start with a number
annotations	Max Length LARGE
label	Max Length Medium, either de or en must be present
accessWays	Mandatory, Min Size 1, Must only contain "download-cuf", "download-suf", "remote-desktop-suf", "onsite-suf", "not-accessible"
surveyNumbers	Mandatory, Min Size 1
panelIdentifier	Max Length MEDIUM, Lowercase alphanumeric (with German Umlauts and ß) + "-" + "_", Pattern (DataAcquisitionProjectId + "-" + "ds" + "dataSetNumber" + "-" + string)
derivedVariablesIdentifier	Max Length MEDIUM, Lowercase alphanumeric (with German Umlauts and ß) + "-" + "_", Pattern (DataAcquisitionProjectId + "-" + "ds" + "dataSetNumber" + "-" + string)
indexInDataSet	Mandatory
dataSetNumber	Mandatory
dataSetId	Mandatory
dataAcquisitionProjectId	Mandatory
studyId	Mandatory

RelatedQuestion

Attribute	Validation Rules
instrumentNumber	Mandatory
questionNumber	Mandatory, Max Length SMALL
relatedQuestionStrings	Max Length LARGE

FilterDetails

Attribute	Validation Rules
expression	Mandatory, Max Length LARGE
description	Max Length LARGE
expressionLanguage	Mandatory, either "Stata" or "SpEL"

GenerationDetails

Attribute	Validation Rules
description	Max Length X-LARGE
rule	Mandatory, if there is a ruleExpressionLanguage, max Length LARGE, either rule or description(.de or .en) must be set or all can be set
ruleExpressionLanguage	Mandatory, if there is a rule, either "Stata" or "R"

Distribution

Attribute	Validation Rules
totalAbsoluteFrequency	Mandatory
totalValidAbsoluteFrequency	Mandatory
totalValidRelativeFrequency	Mandatory

Statistics

Attribute	Validation Rules
minimum	Max Length SMALL, has to be numeric, if variable.dataType=numeric, has to be an ISO 8601 Date, if variable.dataType=date
minimum	Max Length SMALL, has to be numeric, if variable.dataType=numeric, has to be an ISO 8601 Date, if variable.dataType=date
median	Max Length SMALL, has to be numeric, if variable.dataType=numeric, has to be an ISO 8601 Date, if variable.dataType=date
firstQuartile	Max Length SMALL, has to be numeric, if variable.dataType=numeric, has to be an ISO 8601 Date, if variable.dataType=date
thirdQuartile	Max Length SMALL, has to be numeric, if variable.dataType=numeric, has to be an ISO 8601 Date, if variable.dataType=date

Missing

Attribute	Validation Rules
code	Mandatory, Unique within one variable
label	Max Length MEDIUM
absoluteFrequency	Mandatory
relativeFrequency	Mandatory
validRelativeFrequency	Mandatory

ValidResponse

Attribute	Validation Rules
label	Max Length LARGE
absoluteFrequency	Mandatory
relativeFrequency	Mandatory
validRelativeFrequency	Mandatory
value	Mandatory, Max Length SMALL, has to be numeric, if variable.dataType=numeric, has to be an ISO 8601 Date, if variable.dataType=date

Question

Attribute	Validation Rules
id	Mandatory, Max Length MEDIUM, Lowercase alphanumeric (with German Umlauts and ß) + "-", Pattern ("que-" + dataAcquisitionProjectId + "-ins" + instrumentNumber + "-" + number + "$") The number can contain dots
number	Mandatory, Max Length SMALL, unique within instrument
questionText	Mandatory, Max Length LARGE
instruction	Max Length X-LARGE
introduction	Max Length LARGE
type	Mandatory, de = "Einfachnennung" or "Offen" or "Mehrfachnennung" or "Itembatterie" or "Matrix", en = "Single Choice" or "Open" or "Multiple Choice" or "Item Set" or "Grid"
additionalQuestionText	Max Length X-LARGE
questionImageMetadata	Mandatory, Min Size 1
topic	Max Length LARGE
annotations	Max Length LARGE
instrumentNumber	Mandatory
dataAcquisitionProjectId	Mandatory
studyId	Mandatory
indexInInstrument	Mandatory

QuestionImageMetadata

Attribute	Validation Rules
imageType	Mandatory, Must be 'PNG'
language	Mandatory, Valid ISO 639-1
fileName	Mandatory, Alphanumeric (with German Umlauts) with "_", "-" and "."
containsAnnotations	Mandatory
indexInQuestion	Mandatory
questionId	Mandatory
dataAcquisitionProjectId	Mandatory

TechnicalRepresentation

Attribute	Validation Rules
type	Mandatory, Max Length SMALL
language	Mandatory, Max Length SMALL
source	Mandatory, Max Length X-LARGE

Instrument

Attribute	Validation Rules
id	Mandatory, Max Length MEDIUM, Lowercase alphanumeric (with German Umlauts and ß) + "-", Pattern ("ins-" + dataAcquisitionProjectId + "-" + "ins" + number + "$")
number	Mandatory, unique within dataAcquisitionProject
title	Mandatory, Max Length LARGE
subtitle	Max Length LARGE
description	Mandatory, Max Length MEDIUM
type	Mandatory, one of the following: PAPI, CAPI, CATI, CAWI
annotations	Max Length LARGE
surveyNumbers	Mandatory, Min size 1
dataAcquisitionProjectId	Mandatory
studyId	Mandatory

InstrumentAttachmentMetadata

Attribute	Validation Rules
instrumentId	Mandatory
instrumentNumber	Mandatory
dataAcquisitionProjectId	Mandatory
type	Mandatory, valid values in german: Fragebogen, Filterführungsdiagramm, Variablenfragebogen, Sonstige. Valid values in english: Questionnaire, Question Flow, Variable Questionnaire, Other
description	Mandatory, Max Length MEDIUM
language	Mandatory, Valid ISO 639-1
fileName	Mandatory, Alphanumeric (with German Umlauts) with "_", "-" and "."
indexInInstrument	Mandatory

RelatedPublication

Attribute	Validation Rules
id	Mandatory, Max Length MEDIUM, no whitespace, Pattern ("pub-" + citaviId + "$")
sourceReference	Mandatory, Max Length LARGE
publicationAbstract	Max Length X-LARGE
doi	Max Length MEDIUM
sourceLink	valid url
title	Mandatory, Max Length LARGE
authors	Mandatory, Max Length LARGE
year	Mandatory, 1960 < year <= current year
abstractSource	Max Length LARGE
language	Mandatory, Valid ISO 639-1
studyIds	If present must exists, either one studyId or one studySeries must be present
studySerieses	If present must exists, either one studyId or one studySeries must be present
surveyIds	If present must exists, if present corresponding studyId must be present as well
instrumentIds	If present must exists, if present corresponding studyId must be present as well
questionIds	If present must exists, if present corresponding studyId must be present as well
dataSetIds	If present must exists, if present corresponding studyId must be present as well
variableIds	If present must exists, if present corresponding studyId must be present as well

CodingScheme

Attribute	Validation Rules
id	Mandatory, Max Length MEDIUM, Lowercase alphanumeric (with German Umlauts and ß), Pattern ("cod-" + Alphanumeric String + "$")
type	Max Length MEDIUM, Mandatory, valid values in german: "einfache Codierliste", "Referenzliste". Valid values in english: "simple coding scheme", "reference scheme"
sourceUrl	Max Length MEDIUM, valid URL
name	Mandatory, Max Length MEDIUM
source	Mandatory, Max Length LARGE
attribute	Mandatory, Max Length MEDIUM
annotations	Max Length LARGE
year	Mandatory, integer
authors	Max Length MEDIUM
institution	Mandatory, Max Length MEDIUM

CodingSchemeAttachmentMetadata

Attribute	Validation Rules
codingSchemeId	Mandatory
title	Mandatory, Max Length LARGE
language	Mandatory, Valid ISO 639-1
fileName	Mandatory, Alphanumeric (with German Umlauts) with "_", "-" and "."
indexInCodingScheme	Mandatory

Resolution

Attribute	Validation Rules
widthX	Mandatory
heightY	Mandatory

DataAcquisitionProject (Post-)Validation

This section describes the validation rules which are applied in order to ensure consistency of the entire DataAcquisitionProject.

Post-Validation performs checks which cannot be performed during the import of a single domain object. These checks are automatically executed before a project will be released.

The following checks are implemented.

DataSet

• dataSet.surveyIds: there must be a survey with that id

Variable

• variable.surveyIds: there must be a survey with that id and the surveyIds must be a subset of the surveyIds of the corresponding dataSet
• variable.relatedQuestions[*].questionId: there must be a question with that id
• variable.dataSetId: there must be a data set with that id
• variable.relatedVariables: Check for variable ids
• variable.codingSchemeId: there must be a coding scheme with that id

Question

• question.instrumentId: there must be an instrument with that id
• question.successors: there must be a question with that id
• Check for a depending question image

Instrument

• instrument.surveyIds: there must be a survey with that id