- Interactive Schema -
Element Dictionary

The ocil element is the root XML element of an OCIL document. It contains information about one or more questionnaires. It may also contain results elements to store prior responses.

Child Elements	Type	MinOccurs	MaxOccurs
generator	inter:GeneratorType	1	1
document	inter:DocumentType	0	1
questionnaires	inter:QuestionnairesType	1	1
test_actions	inter:TestActionsType	1	1
questions	inter:QuestionsType	1	1
artifacts	inter:ArtifactsType	0	1
variables	inter:VariablesType	0	1
results	inter:ResultsType	0	1

The QuestionnairesType type defines a container for a set of questionnaire elements.

Attributes:
-	scope		inter:ScopeType		(optional -- default='FULL')

Child Elements	Type	MinOccurs	MaxOccurs
questionnaire	inter:QuestionnaireType	1	unbounded

The QuestionnaireType type defines a structure that represents specific question or set of questions that evaluate to a single result. A questionnaire may contain multiple test_actions. test_actions may be nested and aggregated thru some acceptable operation to produce the result of a check.

The GeneratorType type defines an element that is used to hold information about when a particular OCIL document was generated, what version of the schema was used, what tool was used to generate the document, and what version of the tool was used.

Additional generator information is also allowed although it is not part of the official OCIL language. Individual organizations can place generator information that they feel are important.

Child Elements	Type	MinOccurs	MaxOccurs
product_name	xsd:string	0	1
product_version	xsd:string	0	1
author	inter:UserType	0	unbounded
schema_version	xsd:decimal	1	1
timestamp	xsd:dateTime	1	1

This type describes structures used to provide document-level information, including title, descriptions, and notices.

Child Elements	Type	MinOccurs	MaxOccurs
title	xsd:string	1	1
description	xsd:string	0	unbounded
notice	xsd:string	0	unbounded

Provides possible scope values that specifies when evaluation stops.

Value	Description
FULL	The FULL value indicates that all questions must be asked regardless of whether or not it they are all needed to produce a result for a questionnaire.
SHORT	The SHORT value indicates that once a result value can be computed for a questionnaire, then it is safe to stop asking questions.

The TestActionsType type defines a container for a set of test action elements.

Child Elements	Type	MinOccurs	MaxOccurs
inter:test_action	inter:ItemBaseType	1	unbounded

The QuestionTestActionType type defines structures that are used to hold handlers for non-standard results (UNKNOWN, NOT_TESTED, NOT_APPLICABLE, and ERROR) received from a referenced question. All children of question_test_action extend this type.

The BooleanQuestionTestActionType type defines a structure that references a boolean_question and includes handlers for TRUE (YES) or FALSE (NO) responses.

The ChoiceQuestionTestActionType type defines a structure that references a choice_question and includes handlers for the various choices set out in the choice_question.

The NumericQuestionTestActionType type defines a structure that references a numeric_question and includes handlers that indicate actions to perform based on whether the user's response matches a particular value or falls within a particular range.

The StringQuestionTestActionType type defines a structure that references a string_question and includes handlers that indicate actions to perform based on whether the user's response matches a given regular expression.

The TestActionRefType type defines a structure that holds a reference (id) to a test_action or questionnaire.

Attributes:
-	negate		xsd:boolean
-	priority		inter:PriorityType		(optional -- default='LOW')

Simple Content

inter:TestActionRefValuePattern

The WhenChoiceType type defines a structure that specifies the action to take in a choice_test_action when a particular choice is selected by a user in response to a choice_question.

The WhenEqualsType defines a structure that specifies the action to take in a numeric_test_action when a particular value is given by a user in response to a numeric_question.

The WhenRangeType type defines a structure that specifies the action to take in a numeric_test_action when a value given by a user in response to a numeric_question falls within the indicated range.

The WhenPatternType type defines a structure that specifies the action to take in a string_test_action when a string given by a user in response to a string_question matches the given regular expression.

The PatternType type defines a structure that specifies a regular expression against which a string will be compared.

Attributes:
-	var_ref		inter:VariableIDPattern		(optional)

Simple Content

xsd:string

The RangeType type defines a structure that specifies a range against which a numeric user response is to be compared.

Child Elements	Type	MinOccurs	MaxOccurs
min	inter:RangeValueType	0	1
max	inter:RangeValueType	0	1

The ResultChoiceType complex type specifies processing instructions - either produce a result or move on to another test. The ResultChoiceType is extended by all handlers ("when_...") in test_actions.

Child Elements	Type	MinOccurs	MaxOccurs
artifacts	inter:ArtifactsType	0	1

Attributes:
-	inclusive		xsd:boolean
-	var_ref		inter:VariableIDPattern		(optional)

Simple Content

xsd:decimal

The QuestionsType type defines structures containing a set of QuestionType and ChoiceGroupType elements.

Child Elements	Type	MinOccurs	MaxOccurs
inter:question	inter:QuestionType	1	unbounded
choice_group	inter:ChoiceGroupType	0	unbounded

The QuestionType complex type defines a structure to describe a question and any instructions to help in determining an answer.

The BooleanQuestionType type defines a question with valid responses of either {TRUE, FALSE} or {YES, NO}.

The ChoiceQuestionType type defines a question with one or more acceptable answers specified by the author. The user will select one of these specified answers as their response. Acceptable answers are specified either explicitly using the choice element or implicitly using the choice_group_ref element to reference a choice_group element. Choices are presented in the order in which they are provided. All the choices in a choice_group are inserted in the order in which they appear within the choice_group.

The NumericQuestionType type defines a question that requires a numeric answer. Acceptable values may be positive or negative and may include decimals.

The StringQuestionType type defines a question that requires a string answer.

Provides the acceptable models (i.e. set of acceptable responses) for a boolean_question.

Value	Description
MODEL_YES_NO	MODEL_YES_NO represents a response set of {YES, NO}.
MODEL_TRUE_FALSE	MODEL_TRUE_FALSE represents a response set of {TRUE, FALSE}.

The ChoiceType type defines structures that hold information about one acceptable answer to a choice_question.

Attributes:
-	id		inter:ChoiceIDPattern		(required)
-	var_ref		inter:VariableIDPattern		(optional)

Simple Content

xsd:string

The ChoiceGroupType type defines a group of choices that may then be reused in multiple choice_question elements. For example, a document may include multiple choice_questions with the options of "Good", "Fair", or "Poor". By defining these choices in a single choice_group, the author would not need to list them out explicitly in every choice_question.

Attributes:
-	id		inter:ChoiceGroupIDPattern		(required)

Child Elements	Type	MinOccurs	MaxOccurs
choice	inter:ChoiceType	1	unbounded

The InstructionsType type defines a series of steps intended to guide the user in answering a question.

Child Elements	Type	MinOccurs	MaxOccurs
title	inter:TextType	1	1
step	inter:StepType	1	unbounded

The ResultsType type defines structures containing results from questionnaires, test actions, questions, artifacts, and metadata about the start/end time of evaluation, any targets, and a short caption or title.

Attributes:
-	start_time		xsd:dateTime		(optional)
-	end_time		xsd:dateTime		(optional)

Child Elements	Type	MinOccurs	MaxOccurs
title	inter:TextType	0	1
questionnaire_results	inter:QuestionnaireResultsType	0	1
test_action_results	inter:TestActionResultsType	0	1
question_results	inter:QuestionResultsType	0	1
artifact_results	inter:ArtifactResultsType	0	1
targets	inter:TargetsType	0	1

The QuestionnaireResultsType type defines structures containing computed results of all the evaluated questionnaires.

Child Elements	Type	MinOccurs	MaxOccurs
questionnaire_result	inter:QuestionnaireResultType	1	unbounded

The TestActionResultsType type defines structures containing computed results of all the evaluated test action types.

Child Elements	Type	MinOccurs	MaxOccurs
test_action_result	inter:TestActionResultType	1	unbounded

The QuestionResultsType type defines structures containing computed results of all evaluated question types.

Child Elements	Type	MinOccurs	MaxOccurs
inter:question_result	inter:QuestionResultType	1	unbounded

The QuestionnaireResultType type defines structures containing the computed result, associated artifacts and targets of a particular questionnaire.

Attributes:
-	questionnaire_ref		inter:QuestionnaireIDPattern		(required)
-	result		inter:ResultType		(required)

Child Elements	Type	MinOccurs	MaxOccurs
artifact_results	inter:ArtifactResultsType	0	1

The TestActionResultType type defines structures containing all computed results of a TestActionType. One of these elements will appear for each test_action evaluated.

Attributes:
-	test_action_ref		inter:TestActionRefValuePattern		(required)
-	result		inter:ResultType		(required)

Child Elements	Type	MinOccurs	MaxOccurs
artifact_results	inter:ArtifactResultsType	0	1

The QuestionResultType complex type defines structures that hold information about a question and the user's response to it.

Attributes:
-	question_ref		inter:QuestionIDPattern		(required)
-	response		inter:UserResponseType		(optional -- default='ANSWERED')

The BooleanQuestionResultType type defines structures containing a reference to a boolean_question, the user's response, and whether the question was successfully posed.

The ChoiceQuestionResultType type defines structures containing a reference to a choice_question, the user's response, and whether the question was successfully posed.

The NumericQuestionResultType type defines structures containing a reference to a numeric_question, the result provided by the user, and whether the question was successfully posed.

A string_question_result element contains a reference to a string_question, the string provided by the user in response, and whether the question was successfully posed.

The ResultType simple type defines acceptable result values for questionnaires and test_actions.

|| P | F | E | U | NT | NA || ---------------||-----------------------------||------------------||------------------------------------------ || 1+ | 0 | 0 | 0 | 0 | 0+ || Pass || 0+ | 1+ | 0+ | 0+ | 0+ | 0+ || Fail AND || 0+ | 0 | 1+ | 0+ | 0+ | 0+ || Error || 0+ | 0 | 0 | 1+ | 0+ | 0+ || Unknown || 0+ | 0 | 0 | 0 | 1+ | 0+ || Not Tested || 0 | 0 | 0 | 0 | 0 | 1+ || Not Applicable || 0 | 0 | 0 | 0 | 0 | 0 || Not Tested ---------------||-----------------------------||------------------||------------------------------------------ || 1+ | 0+ | 0+ | 0+ | 0+ | 0+ || Pass || 0 | 1+ | 0 | 0 | 0 | 0+ || Fail OR || 0 | 0+ | 1+ | 0+ | 0+ | 0+ || Error || 0 | 0+ | 0 | 1+ | 0+ | 0+ || Unknown || 0 | 0+ | 0 | 0 | 1+ | 0+ || Not Tested || 0 | 0 | 0 | 0 | 0 | 1+ || Not Applicable || 0 | 0 | 0 | 0 | 0 | 0 || Not Tested

The ExceptionalResultType type defines possible exceptional results of a question.

Value	Description
UNKNOWN	An UNKNOWN value indicates that the result of a test cannot be determined.
ERROR	An ERROR value indicates that an error occured while processing the check. Among other causes, this can indicate an unexpected response from the user.
NOT_TESTED	A NOT_TESTED value indicates that the check has not been tested yet.
NOT_APPLICABLE	A NOT_APPLICABLE value indicates that the check is not relevant and can be skipped.

The UserResponseType type defines structures containing the type of response made by the user. The user could either have answered the question or have taken any of the ExceptionalResultType values.

The ChoiceAnswerType type defines structures containing a choice_ref attribute that identifies the choice selected by the user.

Attributes:
-	choice_ref		inter:ChoiceIDPattern

The ArtifactsType type defines structures containing a set of artifact elements.

Child Elements	Type	MinOccurs	MaxOccurs
artifact	inter:ArtifactType	1	unbounded

The ArtifactType type defines structures containing information about an artifact such as title, description, persistence, datatype, and/or if it's required to complete an answer to a question.

Attributes:
-	id		inter:ArtifactIDPattern		(required)
-	persistent		xsd:boolean		(optional -- default='true')
-	datatype		inter:ArtifactDataType		(optional -- default='TEXT')
-	required		xsd:boolean		(optional -- default='false')

Child Elements	Type	MinOccurs	MaxOccurs
title	inter:TextType	1	1
description	inter:TextType	1	1

The ArtifactResultsType type defines structures containing a set of artifact_result elements.

Child Elements	Type	MinOccurs	MaxOccurs
artifact_result	inter:ArtifactResultType	1	unbounded

The ArtifactResultType type defines structures containing informaiton about the submitted artifact, its value, who provided and submitted it, and when it was submitted.

Attributes:
-	artifact_ref		inter:ArtifactIDPattern		(required)
-	timestamp		xsd:dateTime		(required)

Child Elements	Type	MinOccurs	MaxOccurs
value	xsd:string	1	1
provider	inter:ProviderValuePattern	1	1
submitter	inter:UserType	1	1

The ArtifactDataType type defines the acceptable data values for an artifact.

Value	Description
TEXT	A TEXT value specifies that the artifact is an essay entered during the evaluation.
REFERENCE	A REFERENCE value specifies that the artifact holds a reference to a file or a URL.

The TargetsType type defines structures containing a set of target elements.

Child Elements	Type	MinOccurs	MaxOccurs
inter:target	inter:NamedItemBaseType	1	unbounded

The UserTargetType type defines structures containing information about a user such as name, organization, position, email, and role.

The SystemTargetType type defines structures containing information about the organization it belongs to, a set of ip addresses of computers/networks included in the system, descrioption about it, and the roles it performs.

The VariablesType type defines structures containing a set of variables.

Child Elements	Type	MinOccurs	MaxOccurs
inter:variable	inter:VariableType	1	unbounded

The VariableType type defines structures used to hold a single value.

The ConstantVariableType type defines structures containing a value defined by the author of the document.

The LocalVariableType type defines structures containing a value determined during evaluation. Value is computed based on the matched pattern, choice_ref, or range value, and the answer to the linked question

The ExternalVariableType type defines structures containing a value defined elsewhere or some external source.

The VariableSetType type defines structures containing information describing how to compute a variable value. It holds the patterns, choice_refs, and range values to be matched; and the appropriate value to be stored on the variable based on the match.

Child Elements	Type	MinOccurs	MaxOccurs
value	n/a	1	1

The VariableDataType simple type defines how a variable data value should be treated or used.

Value	Description
TEXT	The TEXT value specifies that the variable data value should be treated as text.
NUMERIC	The NUMERIC value specifies that the variable data value should be treated as number.

The ReferenceType complex type defines structures used to hold information about an external reference given its URI and description.

This structure may be used to reference other standards such as CVE, CCE, or CPE. To do so, the href attribute would give the relevant namespace. For example, the namespace of the current version of CPE is http://cpe.mitre.org/dictionary/2.0 and the body of this element would hold a specific CPE identifier. References to other information (documents, web pages, etc.) are also permitted.

The StepType complex type defines structures that describe one step (out of possibly multiple steps) that a user should take in order to respond to a question. The steps would appear as part of the question's instructions element.

Attributes:
-	is_done		xsd:boolean		(optional -- default='false')
-	is_required		xsd:boolean		(optional -- default='true')

Child Elements	Type	MinOccurs	MaxOccurs
description	inter:TextType	0	1
reference	inter:ReferenceType	0	unbounded
step	inter:StepType	0	unbounded

The ItemBaseType complex type defines structures allowing a set of notes to be included. This type is inherited by many of the elements in the OCIL language.

Child Elements	Type	MinOccurs	MaxOccurs
notes	xsd:string	0	unbounded

The TargetType type defines the user, role, or system that applies to a questionnaire or the whole OCIL document.

The CompoundTestActionType type describes the structures used to combine multiple test_action elements into a single result.

The ReferenceType complex type contains a set of references.

Child Elements	Type	MinOccurs	MaxOccurs
reference	inter:ReferenceType	1	unbounded

The OperationType type defines structures that hold a set of test_actions and provide instructions as to how to aggregate their individual results into a single result.

Attributes:
-	operation		inter:OperatorType		(optional -- default='AND')
-	negate		xsd:boolean		(optional -- default='false')
-	priority		inter:PriorityType		(optional -- default='LOW')

Child Elements	Type	MinOccurs	MaxOccurs
test_action_ref	inter:TestActionRefType	1	unbounded

The OperatorType simple type provides a list of possible operator values that operates on a set of test_action elements.

Value	Description
AND	The AND operator produces a true result if every argument is true. If one or more arguments are false, the result of the AND is false. See the truth table provided in the ResultType type for a complete list of how the various result types are combined by an AND operation.
OR	The OR operator produces a true result if one or more arguments is true. If every argument is false, the result of the OR is false. See the truth table provided in the ResultType type for a complete list of how the various result types are combined by an AND operation.

The PriorityType simple type provides a list of possible priority attribute values for a set of test_action elements. The notion of importance is left to the author's discretion.

Value	Description
HIGH	A HIGH priority test_action is more important than both MEDIUM and LOW priority test_actions.
MEDIUM	A MEDIUM priority test_action is more important than LOW priority test_actions.
LOW	A LOW priority test_action has less importance compared to MEDIUM and HIGH priority test_actions.

The TextType complex type defines an element that holds any information.

A test_action_ref may refer to either a test_action or a questionnaire. This type represents the union of these two ID patterns.

ocil:[A-Za-z0-9_\-\.]+:testaction:[1-9][0-9]* ocil:[A-Za-z0-9_\-\.]+:questionnaire:[1-9][0-9]*

ID values for questionnaires must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:questionnaire:[1-9][0-9]*

ID values for test_actions must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:testaction:[1-9][0-9]*

ID values for questions must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:question:[1-9][0-9]*

ID values for choices in choice_questions must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:choice:[1-9][0-9]*

ID values for choice_group references in choice_questions must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:choicegroup:[1-9][0-9]*

ID values for variable references must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:variable:[1-9][0-9]*

ID values for artifact references must match this pattern. Each ID must be unique within an OCIL document.

ocil:[A-Za-z0-9_\-\.]+:artifact:[1-9][0-9]*

Provider for artifacts may be a user or a system. This type represents the union of these two ID patterns.

ocil:[A-Za-z0-9_\-\.]+:user:[1-9][0-9]* ocil:[A-Za-z0-9_\-\.]+:system:[1-9][0-9]*