 
 (s/defschema DirectImpactSummary
   "See http://stixproject.github.io/data-model/1.2/incident/DirectImpactSummaryType/"
-  {(s/optional-key :asset_losses) v/ImpactRating
-   (s/optional-key :business_mission_distruption) v/ImpactRating
-   (s/optional-key :response_and_recovery_costs) v/ImpactRating})
+  {(s/optional-key :asset_losses)
+   (describe v/ImpactRating "level of asset-related losses that occured in the Incident")
+   (s/optional-key :business_mission_distruption)
+   (describe v/ImpactRating "characterizes (at a high level) the level of business or mission disruption impact that occured in the Incident")
+   (s/optional-key :response_and_recovery_costs)
+   (describe v/ImpactRating "characterizes (at a high level) the level of response and recovery related costs that occured in the Incident")})
 
 (s/defschema IndirectImpactSummary
   "See http://stixproject.github.io/data-model/1.2/incident/IndirectImpactSummaryType/"
-  {(s/optional-key :loss_of_competitive_advantage) v/SecurityCompromise
-   (s/optional-key :brand_and_market_damage) v/SecurityCompromise
-   (s/optional-key :increased_operating_costs) v/SecurityCompromise
+  {(s/optional-key :loss_of_competitive_advantage)
+   (describe v/SecurityCompromise "characterizes (at a high level) the level of impact based on loss of competitive advantage that occured in the Incident")
+   (s/optional-key :brand_and_market_damage)
+   (describe v/SecurityCompromise "characterizes (at a high level) the level of impact based on brand or market damage that occured in the Incident")
+   (s/optional-key :increased_operating_costs)
+   (describe v/SecurityCompromise "characterizes (at a high level) the level of impact based on increased operating costs that occured in the Incident")
    (s/optional-key :local_and_regulatory_costs) v/SecurityCompromise})
 
 (s/defschema LossEstimation
   "See http://stixproject.github.io/data-model/1.2/incident/LossEstimationType/"
-  {(s/optional-key :amount) s/Num
-   (s/optional-key :iso_currency_code) s/Str})
+  {(s/optional-key :amount)
+   (describe s/Num "the estimated financial loss for the Incident")
+   (s/optional-key :iso_currency_code)
+   (describe s/Str "ISO 4217 currency code if other than USD")})
 
 (s/defschema TotalLossEstimation
   "See http://stixproject.github.io/data-model/1.2/incident/TotalLossEstimationType/"
-  {(s/optional-key :initial_reported_total_loss_estimation) LossEstimation
-   (s/optional-key :actual_total_loss_estimation) LossEstimation})
+  {(s/optional-key :initial_reported_total_loss_estimation)
+   (describe LossEstimation "specifies the initially reported level of total estimated financial loss for the Incident")
+   (s/optional-key :actual_total_loss_estimation)
+   (describe LossEstimation "specifies the actual level of total estimated financial loss for the Incident")})
 
 (s/defschema ImpactAssessment
   "See http://stixproject.github.io/data-model/1.2/incident/ImpactAssessmentType/"
-  {(s/optional-key :direct_impact_summary) DirectImpactSummary
-   (s/optional-key :indirect_impact_summary) IndirectImpactSummary
-   (s/optional-key :total_loss_estimation) TotalLossEstimation
-   (s/optional-key :impact_qualification) v/ImpactQualification
-   (s/optional-key :effects) [v/Effect]
+  {(s/optional-key :direct_impact_summary)
+   (describe DirectImpactSummary "characterizes (at a high level) losses directly resulting from the ThreatActor's actions against organizational assets within the Incident")
+   (s/optional-key :indirect_impact_summary)
+   (describe IndirectImpactSummary "characterizes (at a high level) losses from other stakeholder reactions to the Incident")
+   (s/optional-key :total_loss_estimation)
+   (describe TotalLossEstimation "specifies the total estimated financial loss for the Incident")
+   (s/optional-key :impact_qualification)
+   (describe v/ImpactQualification "summarizes the subjective level of impact of the Incident")
+   (s/optional-key :effects)
+   (describe [v/Effect] "list of effects of this incident from a controlled vocabulary")
    ;; Not provided: external_impact_assessment_model
    })
 

            [cia.schemas.relationships :as rel]
            [cia.schemas.vocabularies :as v]
            [schema.core :as s]
            [schema-tools.core :as st]))

(s/defschema COARequested
  "See http://stixproject.github.io/data-model/1.2/incident/COARequestedType/
   and http://stixproject.github.io/data-model/1.2/incident/COATakenType/"
  {(s/optional-key :time) c/Time
   (s/optional-key :contributors) [c/Contributor]
   :COA rel/COAReference})

(s/defschema NonPublicDataCompromised
  "See http://stixproject.github.io/data-model/1.2/incident/NonPublicDataCompromisedType/"
  ;; Simplified schema
  {:security_compromise v/SecurityCompromise
   (s/optional-key :data_encrypted) s/Bool})

(s/defschema PropertyAffected
  "See http://stixproject.github.io/data-model/1.2/incident/PropertyAffectedType/"
  {(s/optional-key :property) v/LossProperty
   (s/optional-key :description_of_effect) s/Str
   (s/optional-key :type_of_availability_loss) s/Str ;; Vocab is empty
   (s/optional-key :duration_of_availability_loss) v/LossDuration
   (s/optional-key :non_public_data_compromised) NonPublicDataCompromised})

(s/defschema AffectedAsset
  "See http://stixproject.github.io/data-model/1.2/incident/AffectedAssetType/"
  {(s/optional-key :type) s/Str
   (s/optional-key :description) s/Str
   (s/optional-key :ownership_class) v/OwnershipClass
   (s/optional-key :management_class) v/ManagementClass
   (s/optional-key :location_class) v/LocationClass
   (s/optional-key :property_affected) PropertyAffected ;; Unnested NatureOfSecurityEffect
   (s/optional-key :identifying_observables) [c/Observable]
   ;; Not Provided: business_function_or_role
   ;; Not Provided: location (undefined/abstract type); Could be [s/Str]


(s/defschema History
  "See http://stixproject.github.io/data-model/1.2/incident/HistoryItemType/"
  {(s/optional-key :action_entry)
   (describe [COARequested] "a record of actions taken during the handling of the Incident")
   (s/optional-key :journal_entry)
   (describe s/Str "journal notes for information discovered during the handling of the Incident") ;; simplified
   })

(s/defschema Incident
