CIM Issues #6677

Document Class Generalization Refinement

Added by Henry Dotson 3 months ago. Updated 2 months ago.

Solution Version:
Breaking Change:
Breaking Change Description:
CIM Impacted Groups:
WG14, WG16
Henry B. Dotson, III

IEC61968-11 Edition 4, IEC62325-301 Edition 4

Origination Date:
Origination ID:
Originally Assigned To:


There is a desire to modify the Document class by removing the Document.type string attribute and replacing it with the Document.documentKind enumeration attribute and the Document.documentKindOther string attribute. This would apply best practices to the model and maintain model consistency with the Document.documentKindOther being used when the DocumentKind enumeration class includes "other" as one of the literals in its list of enumerations.

However, the Document.type string attribute is used in IEC62325 profiles, so removing it would break existing IEC62325 profiles.



The proposed solution is to move the Document.type string attribute to the MarketDocument class (i.e. add the MarketDocument.type string attribute to the MarketDocument class).


Updated by Alvaro Marciel 3 months ago

What is the reason behind moving the type attribute outside the Document class? What was the reason of adding the DocumentKind enumeration in the Document class instead of leaving the type attribute as a free String? As you know, in Europe we are relying in our enumerations and therefore you are doing a restriction in the canonical CIM which for us is not acceptable.

ENTSO-E is totally against this change because we are using the type attribute in every market profile in Europe, which would imply modifying all of them. Although moving the type to attribute to the MarketDocument class does not have semantical implications, I foresee several troubles with the GUID consistency in the Enterprise Architect file which we really want to avoid.

Please leave the type attribute as it is. Thanks!


Updated by Svein Olsen 3 months ago

I support Alvaro's commons that it is important to understand the use case behind the proposed changes.
I am concern that we have "overloaded" cim:Document by having it to be a general class to all of the following classes:

- Agreement
- Analytic
- AssetGroup
- AssetModelCatalogueItem
- AuxiliaryAccount
- BankAccount
- BaseWork
- Bid
- BillDeterminant
- BusinessPlan
- ChargeType
- CongestionRevenueRight
- CustomerAccount
- CustomerBillingInfo
- EnergyTransaction
- ErpDocument
- Incident
- MarketDocument
- MarketFactors
- MarketSkill
- MarketStatment
- MerchantAccount
- MeterReadSchedule
- OperationRestriction
- OperationalTag
- Outage
- OutageOrder
- OutagePlan
- PassThroughBill
- PlannedOutageNotification
- PowerQualityPricing
- PricingStructure
- Procedure
- ProcedureDataSet
- SafetyDocument
- ServiceGuarantee
- Settlement
- Skill
- Specification
- StandardIndustryCode
- SwitchingOrder
- SwirtchingPlan
- SwitchingPlanRequest
- Tariff
- TariffProfile
- TimeSchedule
- TroubleOrder
- TroubleTicket
- WorkBillingInfo
- WorkDocument
- WorkOrder
- WorkRequest

I have a problem to see that all the added information is relevant for all the specialization of Document. If we agree to make update to cim:Document, we should consider to create a general class between IdentifiedObject and Document.

Current note on cim:Document:
Parent class for different groupings of information collected and managed as a part of a business process. It will frequently contain references to other objects, such as assets, people and power system resources.

Current note on cim:Incident:
Description of a problem in the field that may be reported in a trouble ticket or come from another source. It may have to do with an outage.

I am proposing to call this cim:Record with the following note:
Generalized class that represent the registration and manage records of different types. This class serves as a foundation for creating specific record instances across different contexts, providing a consistent structure for managing and tracking relevant information. It encapsulates essential information that is common for all specialisation of a record.

Relevant attribute are:
- created: DataTime
- lastModified : DataTime
- version: String
- recordStatus: recordStatusKind
- Editor > Editor
Approver -> Approver

Updated definition of cim:Document:
Generalized class that represent and managed the encapsulated of specialised document that refers to a digital or electronic record that contains information, often structured in a specific format. Document class serves as a blueprint for creating instances of documents, providing a standardized way to manage, organize, and manipulate a collection of one or more objects of different classes content within the application.

The definition of the cim:Document do depend of the inclusion of cim:Record.


Updated by Becky Iverson 2 months ago

From CIM Feature Proposal Mtg: 2/8/2024: This issue is described as "There is a desire to modify the Document class" please include in the issue the described use case requirements to justify a proposed change.

Also available in: Atom PDF