[ENERGYINTEROP-633] IPKeys Feedback on OpenADR Core Profile and Related Schemas - OASIS Technical Committees Issue Tracker

Details

Type: Improvement
Status: Deferred
Priority: Minor
Resolution: Unresolved
Affects Version/s: wd30
Fix Version/s: 1.1
Component/s: None
Labels:
None
Environment:

IPKeys Bill Walker

Proposal:
Hide

Refactored Payload Example

Here is the sample EiCreateEventPayload message. We leave out some of the namespace/schema location attribute for clarity:

[ size 3650 bytes ]

<?xml version="1.0" encoding="UTF-8"?>
<payloads:eiCreateEventPayload>
<eitc:eiEvent eitc:schemaVersion="text">
<eitc:eventDescriptor>
<eitc:eventID>text</eitc:eventID>
<eitc:eventStatus>none</eitc:eventStatus>
<eitc:modificationNumber>1</eitc:modificationNumber>
<eitc:priority>0</eitc:priority>
<eitc:createdDateTime>2001-12-17T09:30:47Z</eitc:createdDateTime>
<eitc:uid>0</eitc:uid>
<eitc:eiMarketContext>
<eitc:uid>text</eitc:uid>
<eitc:marketName>text</eitc:marketName>
</eitc:eiMarketContext>
<eitc:testEvent>text</eitc:testEvent>
<eitc:vtnComment>text</eitc:vtnComment>
</eitc:eventDescriptor>
<eitc:eventSchedules>
<eitc:eiEventSignal eitc:schemaVersion="text">
<eitc:vcalendar>
<eitc:interval>
<xcal:uid>
<xcal:text>0</xcal:text>
</xcal:uid>
<eitc:duration>P3H</eitc:duration>
<eitc:signalValue>
<eitc:value>0</eitc:value>
</eitc:signalValue>
</eitc:interval>
</eitc:vcalendar>
<eitc:signalName>text</eitc:signalName>
<eitc:signalType>signalLevel</eitc:signalType>
<eitc:uid>text</eitc:uid>
<eitc:currentValue>
<eitc:signalValue>
<eitc:value>0</eitc:value>
</eitc:signalValue>
</eitc:currentValue>
</eitc:eiEventSignal>
</eitc:eventSchedules>
<eitc:eiEventSchedule>
<xcal:components>
<eitc:eiActivePeriod>
<xcal:properties>
<xcal:dtstart>
<xcal:date-time>2001-12-17T09:30:47Z</xcal:date-time>
</xcal:dtstart>
<xcal:duration>
<xcal:duration>P3H</xcal:duration>
</xcal:duration>
<eitc:eiNotification>
<xcal:duration>P3H</xcal:duration>
</eitc:eiNotification>
<eitc:eiRampUpLimit>
<xcal:duration>P3H</xcal:duration>
</eitc:eiRampUpLimit>
<eitc:eiRecoveryLimit>
<xcal:duration>P3H</xcal:duration>
</eitc:eiRecoveryLimit>
</xcal:properties>
</eitc:eiActivePeriod>
</xcal:components>
</eitc:eiEventSchedule>
<eitc:resourceID>text</eitc:resourceID>
</eitc:eiEvent>
</payloads:eiCreateEventPayload>

The first refactored version with items described above is:

[ size 2420 bytes ]

<?xml version="1.0" encoding="UTF-8"?>
<payloads:createEvent>
<eitc:event eitc:schemaVersion="text" eitc:id="text">
<eitc:status>none</eitc:status>
<eitc:modificationNumber>1</eitc:modificationNumber>
<eitc:priority>0</eitc:priority>
<eitc:createdDateTime>2001-12-17T09:30:47Z</eitc:createdDateTime>
<eitc:marketContext uid="text">
<eitc:marketName>text</eitc:marketName>
</eitc:marketContext>
<eitc:testEvent>text</eitc:testEvent>
<eitc:vtnComment>text</eitc:vtnComment>
<eitc:schedules>
<eitc:eventSignal eitc:schemaVersion="text" uid="text" name="text" type="signalLevel">
<eitc:interval uid="0" duration="P3H">
<eitc:signalValue>0</eitc:signalValue>
</eitc:interval>
<eitc:currentValue>0</eitc:currentValue>
</eitc:eventSignal>
</eitc:schedules>
<eitc:schedule>
<eitc:eiActivePeriod dtstart="2001-12-17T09:30:47Z" duration="P3H">
<eitc:eiNotification duration="P3H"/>
<eitc:eiRampUpLimit duration="P3H"/>
<eitc:eiRecoveryLimit duration="P3H"/>
</eitc:eiActivePeriod>
</eitc:schedule>
<eitc:resourceID>text</eitc:resourceID>
</eitc:event>
</payloads:createEvent>

The second version, with schedules removed is:

[ size 2120 bytes ]

<?xml version="1.0" encoding="UTF-8"?>
<payloads:createEvent>
<eitc:event eitc:schemaVersion="text">
<eitc:id>text</eitc:id>
<eitc:status>none</eitc:status>
<eitc:modificationNumber>1</eitc:modificationNumber>
<eitc:priority>0</eitc:priority>
<eitc:created>2001-12-17T09:30:47Z</eitc:created>
<eitc:marketContext uid="text">
<eitc:marketName>text</eitc:marketName>
</eitc:marketContext>
<eitc:testEvent>text</eitc:testEvent>
<eitc:vtnComment>text</eitc:vtnComment>
<eitc:eventSignal eitc:schemaVersion="text" uid="text" name="text" type="signalLevel">
<eitc:signalValue>0</eitc:signalValue>
</eitc:eventSignal>
<eitc:schedule>
<eitc:eiActivePeriod dtstart="2001-12-17T09:30:47Z" duration="P3H">
<eitc:eiNotification duration="P3H"/>
<eitc:eiRampUpLimit duration="P3H"/>
<eitc:eiRecoveryLimit duration="P3H"/>
</eitc:eiActivePeriod>
</eitc:schedule>
<eitc:resourceID>text</eitc:resourceID>
</eitc:event>
</payloads:createEvent>

Note that we also specified dtstart as an attribute. A possible reason to use an element would be to support different time of times, as iCalendar has date and date-time. As an element, this might be:

<dtstart format="date-time">2001-12-17T09:30:47Z</dtstart>

As with duration, we still prefer an attribute defined to be a date-time if this is the intent. This approach allows intervals with start times and durations to be expressed in a simplified fashion.

A further reduction could be to remove the signalValue element as:

<ei:eventSignal type="level">0</ei:eventSignal>

These changes will simplify the manipulation of EiEvent data structures at the programatic level. For example, it is common practice for Java developers to use JAXB for converting XSD to class representations. A sample output from the current XSD relating to intervals is:

/**

Create an instance of

EiEvent.EventSchedules.EiEventSignal.Vcalendar.Interval }
*
*/
public EiEvent.EventSchedules.EiEventSignal.Vcalendar.Interval createEiEventEventSchedulesEiEventSignalVcalendarInterval() { return new EiEvent.EventSchedules.EiEventSignal.Vcalendar.Interval(); }

The proposed changes will result in a simpler representation.
Show
Refactored Payload Example Here is the sample EiCreateEventPayload message. We leave out some of the namespace/schema location attribute for clarity: [ size 3650 bytes ] <?xml version="1.0" encoding="UTF-8"?> <payloads:eiCreateEventPayload> <eitc:eiEvent eitc:schemaVersion="text"> <eitc:eventDescriptor> <eitc:eventID>text</eitc:eventID> <eitc:eventStatus>none</eitc:eventStatus> <eitc:modificationNumber>1</eitc:modificationNumber> <eitc:priority>0</eitc:priority> <eitc:createdDateTime>2001-12-17T09:30:47Z</eitc:createdDateTime> <eitc:uid>0</eitc:uid> <eitc:eiMarketContext> <eitc:uid>text</eitc:uid> <eitc:marketName>text</eitc:marketName> </eitc:eiMarketContext> <eitc:testEvent>text</eitc:testEvent> <eitc:vtnComment>text</eitc:vtnComment> </eitc:eventDescriptor> <eitc:eventSchedules> <eitc:eiEventSignal eitc:schemaVersion="text"> <eitc:vcalendar> <eitc:interval> <xcal:uid> <xcal:text>0</xcal:text> </xcal:uid> <eitc:duration>P3H</eitc:duration> <eitc:signalValue> <eitc:value>0</eitc:value> </eitc:signalValue> </eitc:interval> </eitc:vcalendar> <eitc:signalName>text</eitc:signalName> <eitc:signalType>signalLevel</eitc:signalType> <eitc:uid>text</eitc:uid> <eitc:currentValue> <eitc:signalValue> <eitc:value>0</eitc:value> </eitc:signalValue> </eitc:currentValue> </eitc:eiEventSignal> </eitc:eventSchedules> <eitc:eiEventSchedule> <xcal:components> <eitc:eiActivePeriod> <xcal:properties> <xcal:dtstart> <xcal:date-time>2001-12-17T09:30:47Z</xcal:date-time> </xcal:dtstart> <xcal:duration> <xcal:duration>P3H</xcal:duration> </xcal:duration> <eitc:eiNotification> <xcal:duration>P3H</xcal:duration> </eitc:eiNotification> <eitc:eiRampUpLimit> <xcal:duration>P3H</xcal:duration> </eitc:eiRampUpLimit> <eitc:eiRecoveryLimit> <xcal:duration>P3H</xcal:duration> </eitc:eiRecoveryLimit> </xcal:properties> </eitc:eiActivePeriod> </xcal:components> </eitc:eiEventSchedule> <eitc:resourceID>text</eitc:resourceID> </eitc:eiEvent> </payloads:eiCreateEventPayload> The first refactored version with items described above is: [ size 2420 bytes ] <?xml version="1.0" encoding="UTF-8"?> <payloads:createEvent> <eitc:event eitc:schemaVersion="text" eitc:id="text"> <eitc:status>none</eitc:status> <eitc:modificationNumber>1</eitc:modificationNumber> <eitc:priority>0</eitc:priority> <eitc:createdDateTime>2001-12-17T09:30:47Z</eitc:createdDateTime> <eitc:marketContext uid="text"> <eitc:marketName>text</eitc:marketName> </eitc:marketContext> <eitc:testEvent>text</eitc:testEvent> <eitc:vtnComment>text</eitc:vtnComment> <eitc:schedules> <eitc:eventSignal eitc:schemaVersion="text" uid="text" name="text" type="signalLevel"> <eitc:interval uid="0" duration="P3H"> <eitc:signalValue>0</eitc:signalValue> </eitc:interval> <eitc:currentValue>0</eitc:currentValue> </eitc:eventSignal> </eitc:schedules> <eitc:schedule> <eitc:eiActivePeriod dtstart="2001-12-17T09:30:47Z" duration="P3H"> <eitc:eiNotification duration="P3H"/> <eitc:eiRampUpLimit duration="P3H"/> <eitc:eiRecoveryLimit duration="P3H"/> </eitc:eiActivePeriod> </eitc:schedule> <eitc:resourceID>text</eitc:resourceID> </eitc:event> </payloads:createEvent> The second version, with schedules removed is: [ size 2120 bytes ] <?xml version="1.0" encoding="UTF-8"?> <payloads:createEvent> <eitc:event eitc:schemaVersion="text"> <eitc:id>text</eitc:id> <eitc:status>none</eitc:status> <eitc:modificationNumber>1</eitc:modificationNumber> <eitc:priority>0</eitc:priority> <eitc:created>2001-12-17T09:30:47Z</eitc:created> <eitc:marketContext uid="text"> <eitc:marketName>text</eitc:marketName> </eitc:marketContext> <eitc:testEvent>text</eitc:testEvent> <eitc:vtnComment>text</eitc:vtnComment> <eitc:eventSignal eitc:schemaVersion="text" uid="text" name="text" type="signalLevel"> <eitc:signalValue>0</eitc:signalValue> </eitc:eventSignal> <eitc:schedule> <eitc:eiActivePeriod dtstart="2001-12-17T09:30:47Z" duration="P3H"> <eitc:eiNotification duration="P3H"/> <eitc:eiRampUpLimit duration="P3H"/> <eitc:eiRecoveryLimit duration="P3H"/> </eitc:eiActivePeriod> </eitc:schedule> <eitc:resourceID>text</eitc:resourceID> </eitc:event> </payloads:createEvent> Note that we also specified dtstart as an attribute. A possible reason to use an element would be to support different time of times, as iCalendar has date and date-time. As an element, this might be: <dtstart format="date-time">2001-12-17T09:30:47Z</dtstart> As with duration, we still prefer an attribute defined to be a date-time if this is the intent. This approach allows intervals with start times and durations to be expressed in a simplified fashion. A further reduction could be to remove the signalValue element as: <ei:eventSignal type="level">0</ei:eventSignal> These changes will simplify the manipulation of EiEvent data structures at the programatic level. For example, it is common practice for Java developers to use JAXB for converting XSD to class representations. A sample output from the current XSD relating to intervals is: /** Create an instance of EiEvent.EventSchedules.EiEventSignal.Vcalendar.Interval } * */ public EiEvent.EventSchedules.EiEventSignal.Vcalendar.Interval createEiEventEventSchedulesEiEventSignalVcalendarInterval() { return new EiEvent.EventSchedules.EiEventSignal.Vcalendar.Interval(); } The proposed changes will result in a simpler representation.
Resolution:

Hide

Defer post-1.0.

Show
Defer post-1.0.

Description

In reviewing the EI schemas relating to the OpenADR profile, we have identified areas that we believe could be optimized for exchange of messages with end point devices. This document also addresses items related to practical implementations. Our feedback addresses the following areas:

1. Redundancy in element naming and the use of attributes versus elements.
2. Deeply nested structures.
3. Use of general purpose scheduling (WS-Calender) in a core profile where only intervals, sequences, and durations are required.

The feedback is directed not at the semantics of the messages (except possibly for number 3, explained below) but the way some of the elements are structured. The first priority is the semantics of the problem domain, followed by the structural representation of messages. We believe that a more efficient structure is possible. Our definition of efficiency pertains not just to packet size, but more widely to:

1. Network bandwidth, memory, and CPU processing related to message size and structure.
2. Human readability of messages. This is extremely important to developers, testers, and engineers who need to design test data and monitor and troubleshoot network traces, and server message logs.
3. The structure of programs that must consume these messages. The sole purpose of Web services is to support program to program communication. Developers use standard tools like JAXB and XML parsers to represent message content inside programs. Any decisions made regarding message structure must seriously consider the impact on the end-consumer, the program, with regard to code development and maintenance.

It turns out that much of this concern is directed at RFC-6321 (xCal) upon which WS-Calendar is based. The original iCalendar spec defined components, properties, parameters, and values. It appears that xCal chose to nest properties and components. The iCalendar components could simply be top level elements, and properties applying to individual elements could be child elements. Furthermore, xCal chose elements for where attributes would be more appropriate (uid) and unnecessary elements (text).

Here is an example from the xCal specification representing an iCalendar VEVENT:

<?xml version="1.0" encoding="UTF-8"?>
<vevent>
<properties>
<dtstamp>
<date-time>2006-02-06T00:11:21Z</date-time>
</dtstamp>
<dtstart>
<parameters>
<tzid>
<text>US/Eastern</text>
</tzid>
</parameters>
<date-time>2006-01-04T14:00:00</date-time>
</dtstart>
<duration>
<duration>PT1H</duration>
</duration>
<recurrence-id>
<parameters>
<tzid>
<text>US/Eastern</text>
</tzid>
</parameters>
<date-time>2006-01-04T12:00:00</date-time>
</recurrence-id>
<summary>
<text>Event #2 bis</text>
</summary>
<uid>
<text>00959BC664CA650E933C892C@example.com</text>
</uid>
</properties>
</vevent>

A more efficient representation would be:

<vevent uid="00959BC664CA650E933C892C@example.com">
<dtstamp type="date-time">2006-02-06T00:11:21Z</dtstamp>
<dtstart tzid="US/Eastern" type="date-time">2006-01-04T14:00:00</dtstart>
<duration>PT1H</duration>
<recurrence-id tzid="US/Eastern" type="date-time">2006-01-04T12:00:00</recurrence-id>
<summary>Event #2 bis</summary>
</vevent>

Here is another example from the WS-Calendar specification describing a single interval, with a start time and duration:

<xcal:interval>
<xcal:properties>
<xcal:uid>
<xcal:text>bfe8069a-0c94-4b53-852f-6a2f12639c7e</xcal:text>
</xcal:uid>
<xcal:duration>
<xcal:duration>PT10H</xcal:duration>
</xcal:duration>
</xcal:properties>
</xcal:interval>

This could be expressed directly as a single element:

<xcal:interval xcal:uid="bfe8069a-0c94-4b53-852f-6a2f12639c7e" ical:duration="PT10H"/>

Clearly the uid is metadata, and best-practices indicate that it should be an attribute, not an element. One could argue that duration could be represented as a child element, in which case this would be:

<xcal:interval xcal:uid="bfe8069a-0c94-4b53-852f-6a2f12639c7e">
<xcal:duration>PT10H</xcal:duration>
</xcal:interval>

We still prefer the first representation, as durations are simple iCalendar strings and will not contain other structured information. They can be applied to other elements including the event itself.

IPKeys Feedback on OpenADR Core Profile and Related Schemas

Details

Description

Attachments

Activity

People

Dates