CLUE C. Groves, Ed. Internet-Draft W. Yang Intended status: Informational R. Even Expires: March 19, 2015 Huawei September 15, 2014 CLUE Partial Updates draft-groves-clue-partial-update-00 Abstract This document proposes a method for using partial updates in CLUE Advertisements to update the CLUE data model. It uses the XML patch operations defined in [RFC5261] Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on March 19, 2015. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Groves, et al. Expires March 19, 2015 [Page 1] Internet-Draft CLUE Partial Updates September 2014 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Partial Notification Format . . . . . . . . . . . . . . . . . 4 3. XML Schema for Partial Negotiations . . . . . . . . . . . . . 5 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.1. Element . . . . . . . . . . . . . . . . . . . . . . 7 4.2. Element . . . . . . . . . . . . . . . . . . . . 7 4.3. Element . . . . . . . . . . . . . . . . . . . . 8 5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 8 6. Procedures . . . . . . . . . . . . . . . . . . . . . . . . . 8 6.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 9 6.1.1. Addition . . . . . . . . . . . . . . . . . . . . . . 9 6.1.2. Replacement . . . . . . . . . . . . . . . . . . . . . 9 6.1.3. Removal . . . . . . . . . . . . . . . . . . . . . . . 9 6.2. Capture Scene . . . . . . . . . . . . . . 9 6.2.1. Addition . . . . . . . . . . . . . . . . . . . . . . 9 6.2.2. Replacement . . . . . . . . . . . . . . . . . . . . . 9 6.2.3. Removal . . . . . . . . . . . . . . . . . . . . . . . 9 6.3. Media Captures . . . . . . . . . . . . . 10 6.3.1. Addition . . . . . . . . . . . . . . . . . . . . . . 10 6.3.2. Replacement . . . . . . . . . . . . . . . . . . . . . 10 6.3.3. Removal . . . . . . . . . . . . . . . . . . . . . . . 10 6.4. Encoding Groups . . . . . . . . . . . . 11 6.4.1. Addition . . . . . . . . . . . . . . . . . . . . . . 11 6.4.2. Replacement . . . . . . . . . . . . . . . . . . . . . 11 6.4.3. Removal . . . . . . . . . . . . . . . . . . . . . . . 11 6.5. Simultaneous Sets . . . . . . . . . . 11 6.6. Global Scene Entries . . . . . . . . 12 6.7. People . . . . . . . . . . . . . . . . . . . . . 12 6.7.1. Addition . . . . . . . . . . . . . . . . . . . . . . 12 6.7.2. Replacement . . . . . . . . . . . . . . . . . . . . . 12 6.7.3. Removal . . . . . . . . . . . . . . . . . . . . . . . 12 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 12 7.1. Additional Presentation Capture . . . . . . . . . . . . . 12 7.2. Capture Removal . . . . . . . . . . . . . . . . . . . . . 13 7.3. Attribute Modification . . . . . . . . . . . . . . . . . 14 8. Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 11. Security Considerations . . . . . . . . . . . . . . . . . . . 15 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 12.1. Normative References . . . . . . . . . . . . . . . . . . 15 12.2. Informative References . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 Groves, et al. Expires March 19, 2015 [Page 2] Internet-Draft CLUE Partial Updates September 2014 1. Introduction As commonly recognised, a large conference using CLUE with many participants and captures will result in large CLUE Advertisement messages. Participants may come and go in conferences which require updates to the CLUE information. Sending large CLUE messages to remove a single capture or scene results in unnecessary bandwidth and processing to compare the existing CLUE description with the updated description. It has been recognised that a method that allows partial updates to the CLUE description is desirable. This document describes procedures for Partial CLUE Advertisements. It does not consider CLUE Configure messages as these are significantly smaller than Advertisement messages. This document defines a "full Advertisement" as one that does not use the partial advertisement syntax and represents a complete description of a Media Provider's media sending capabilities at that point in time. A "partial Advertisement" is one that uses the syntax defined in this document to represent a sub-set of the complete description. As noted in clause 4.3/ [I-D.ietf-clue-protocol], an approach using a "delta" mechanism for advertising changes is suggested. It proposed to leverage the mechanism defined in [RFC5261]. It effectively defines an API for manipulating XML nodes (see clause 6/[http://www.w3.org/TR/xpath-datamodel/#Node]) in an XML document. It utilises XPATH to identify the XML nodes. A basic tutorial on XPATH can be found at: http://www.w3schools.com/XPath/default.asp The procedures are based around the use of XPATH path expressions (see: clause 3.2/[ http://www.w3.org/TR/xpath20/]) to identify a node/s in a CLUE XML document. Several operations are defined that can be used on those nodes. The "add" operation allows the insertion of new XML elements and attributes to the existing XML nodes. The "replace" operation allows the modification of existing XML nodes. The "remove" operation allows the removal of existing XML nodes. This document is based on updates to version 5 of the CLUE Data Model Schema [I-D.ietf-clue-data-model-schema]. The following functions are defined: o Addition: An add operation issued with new elements has the effect of adding the new elements to the CLUEinfo description. Groves, et al. Expires March 19, 2015 [Page 3] Internet-Draft CLUE Partial Updates September 2014 o Replacement: A replacement operation modifies existing element/s with the value/s provided. This may be used to replace child elements without requiring separate add and remove operations. o Removal: A removal operation issued on an element has the effect of deleting that element and any child elements from the CLUEinfo description. Partial updates are implemented using the existing CLUE Advertisement (ADV) message. The difference being that the ADV message for partial updates will not contain a full clue-info description containing all the relevant media provider information but will instead contain a partial update syntax. A Re-Advertisement request (READV/ACK) will result in the media provider's full clue-info being sent. Thus no changes to the protocol message state model are envisaged. This document does not perform a numerical analysis on how many bytes will be saved using an Advertisement with a partial update versus a full Advertisement. The amount of bytes saved will be dependent on the desired operation. The examples in this document show potential partial updates against the examples in [I-D.ietf-clue-data-model-schema]. The basic example in the data model draft is ~6300 characters. It can be seen that the size of the partial updates is considerably less than a full CLUE info description. This document also does not perform an analysis nor give guidelines on how a media provider would determine when to send a partial update versus a full update. It is assumed that the media provider provides an initial full clue-info description and that any subsequent Advertisements contain partial updates. A media provider MAY provide a full Advertisement at any time. Furthermore this document does not describe how the media provider determines the "diff" between an old Advertisement and a new one. This functionality is internal to the media provider. 2. Partial Notification Format The format of the partial updates in based on the XML scheme "patch- ops" defined in [RFC5261]. The partial update XML is defined in a new element "clue-info-diff". The content of the element is an unordered sequence of , , and elements followed by elements from other namespaces for the purposes of extensibility. Any such unknown elements MUST be ignored by the client. The , , and Groves, et al. Expires March 19, 2015 [Page 4] Internet-Draft CLUE Partial Updates September 2014 elements can contain other extension attributes than what are defined in the corresponding base types of [RFC6502]. Author's Note: The introduction of the possibility for extension is consistent with [RFC6502]. This aspect may be removed to simplify the implementation. The elements may appear any number of times and in any order in . However the partial update MUST contain at least one , or element. Any changes are with respect to the base CLUEinfo description. The "base" CLUEinfo description is the result of a previously sent Advertisement with a full CLUEinfo description and any subsequently sent partial updates. Then sending of a full CLUEinfo description will have the effect of resetting the "base" CLUEinfo description. It is not possible for one operation (add/replace/remove) to affect another element in the same clue-info-diff. E.g. an operation may not use an XPATH to reference a previous operation in a clue-info- diff. However attribute values may be referenced across operations. E.g. a Capture Scene ID may be used to add a capture scene and also used in a media capture to reference the scene. If the XPATH cannot be resolved to a single node by the receiver an error response should be generated. Author's Note: XPATH allows quite advanced methods of identifying XML nodes. To simplify implementations it may be advantageous to limit the selector values for specifying nodes. E.g. nodes must be fully specified by name rather than using wildcarding. 3. XML Schema for Partial Negotiations This is the XML proposed for inclusion into the CLUE protocol. It includes the schema for XML patching from [RFC5261] (using [RFC6205] as the basis for the syntax) and defines the add, remove and replacement operations. It is used in CLUE Advertisement messages. Groves, et al. Expires March 19, 2015 [Page 5] Internet-Draft CLUE Partial Updates September 2014 Groves, et al. Expires March 19, 2015 [Page 6] Internet-Draft CLUE Partial Updates September 2014 The XML below is also proposed for inclusion into the CLUE protocol. It includes the schema for XML patch operation errors from [RFC5261]. It is used in CLUE Advertisement ACK messages. 4. Operations 4.1. Element The use of the element is as per section 4.3/[RFC5261] with the exception that the addition of attributes and namespaces is not supported. Thus the 'type' attribute is not supported. Author's Note: Given the nature of the CLUE XML there doesn't seem to be a use case to update namespaces or attributes. When inserting elements, the new nodes are described as they should appear in the CLUEinfo document with respect to the "sel" and any "pos" attribute. 4.2. Element The use of the element is as per section 4.4/[RFC5261]. Groves, et al. Expires March 19, 2015 [Page 7] Internet-Draft CLUE Partial Updates September 2014 When modifying elements the modified nodes must be specified as they should appear info the CLUE info document. The content-to-modify must include the element referenced by the xpath and any child elements. It will have the effect of completely replacing the previous setting of the element. Any child element present in the base document will be removed if not present in the content-to- modify. Any child element, not present in the base document but present in the content-to-modify will be added. XML attributes follow the same behaviour. 4.3. Element The use of the element is as per section 4.5/[RFC5261]. 5. Error Handling When parsing an Advertisement containing a partial update, the Media Consumer may detect an error in the partial update or may not be able to unambiguously apply the update. This may result in an error. In order to support error handling the element should be included in the Advertisement Acknowledgement message. 6. Procedures This section describes the rules associated with partial updates to a CLUE Advertisement. Due to the structure of the CLUE data model there are dependencies between the different elements in the CLUE info document. These procedures are from a syntactic perspective and cover interactions between CLUEinfo elements. Various combinations of operations may or may not make sense from an application perspective, however the application perspective is out of scope of these procedures. Firstly general rules are described that apply to all elements in the CLUEInfo. Procedures specific to the following top level elements are then described: o mediaCaptures o encodingGroups o captureScenes o simultaneousSets o globalSceneEntries o people Groves, et al. Expires March 19, 2015 [Page 8] Internet-Draft CLUE Partial Updates September 2014 6.1. General 6.1.1. Addition When adding a new element, any mandatory child elements must be included. For example: when adding a new media capture the , and elements must be included in the partial update. 6.1.2. Replacement See the specific procedures for replacement in the clauses below. 6.1.3. Removal The deletion of an element will have the effect of deleting all child elements. 6.2. Capture Scene 6.2.1. Addition A partial update may add additional elements to the element. Additional elements may be added to the element. Additional media captures () may be added to the element. 6.2.2. Replacement A partial update may modify the child elements of the . If the element is changed then any elements that reference the sceneID (e.g. by captureSceneIDREF in element) must also be changed in the partial update. 6.2.3. Removal A partial update may remove a capture scene from an existing CLUEInfo description. If the sceneID of the deleted capture scene is used in other elements (e.g. by captureSceneIDREF in ) then these elements must either be removed or the captureSceneIDRef must be changed to another existing capture scene identity in the partial update. A partial update may delete a element. If the sceneEntryID is used in other elements (e.g. by sceneEntryIDREF in and then these elements must either be requested to be removed or the Groves, et al. Expires March 19, 2015 [Page 9] Internet-Draft CLUE Partial Updates September 2014 sceneEntryIDREF must be changed to another existing capture scene entry identity in the partial update. 6.3. Media Captures 6.3.1. Addition A partial update may add additional captures may by specifying additional structures. The partial update must include the mandatory elements of the structure. Therefore the elements must reference existing Capture Scenes or reference Capture Scenes being added in the partial update. The addition of a new media capture may also require that the captureID is added to elements that reference media captures. For example: captureIDREF in the (for multiple content captures), mediaCaptureIDs in the element, captureIDREF in the element and IDREF in the element. The addition of a mediaCapture may also result in a new element (see clause 3.2.1) and possibily an update of the element being needed in the partial update. If the new media capture contains a element containing elements, the referenced must also be added to the element if it has previously not been included. Additional capture attributes may be added to existing media captures. 6.3.2. Replacement A partial update may modify the child elements of the . If the element is changed then any elements that reference the captureID (e.g. by captureIDREF) must also be changed in the partial update. If the partial update modifies the element then the element may need to be updated. See clauses 6.3.1 and 6.3.3. 6.3.3. Removal A partial update may remove a element. The captureID of the removed mediaCapture must also be removed from any elements that reference the captureID in the partial update. For example: captureIDREF in the (for multiple content captures), Groves, et al. Expires March 19, 2015 [Page 10] Internet-Draft CLUE Partial Updates September 2014 mediaCaptureIDs in the element, captureIDREF in the element and IDREF in the element. If the removed media capture contains a element containing elements and the referenced s are not referenced by any other media capture, the referenced persons may removed from the element. 6.4. Encoding Groups 6.4.1. Addition An element may be added to without requiring modification to other top level elements. However if the encoding group is to be used by media captures, the encGroupIDREF of the added encoding group must be added to at least one media capture. Child elements of may be added without impact to other top level elements. Note: The change of an encID may result an SDP Offer/Answer exchange modifying an encoding. 6.4.2. Replacement If the attribute is modified then any media captures that reference the encodingGroupID (through the encGroupIDREF) must also be modified. Note: The change of an encID may result an SDP Offer/Answer exchange modifying an encoding. 6.4.3. Removal If an encodingGroup element is removed any media captures that reference the removed encodingGroup (through the encGroupIDREF element) must be modified to reference a new encoding group ID or the encoding group must be removed in the partial update. Note: The removal of an encID may result an SDP Offer/Answer exchange removing an encoding. 6.5. Simultaneous Sets Operations (Add, Replace, Remove) may be applied the element without any impacts on other top level elements. Any referenced media captures or capture scene entries must exist. Groves, et al. Expires March 19, 2015 [Page 11] Internet-Draft CLUE Partial Updates September 2014 6.6. Global Scene Entries Operations (Add, Replace, Remove) may be applied the element without any impacts on other top level elements. Any referenced capture scene entries must exist. 6.7. People 6.7.1. Addition A new element may be added without affecting other top level elements. However for the new element to be used by the receiver of the CLUE description the of the people defined in that element must be referenced by one or more media captures or capture scenes. 6.7.2. Replacement If the element is modified then any media captures that reference the participant (through the element) must also be modified. 6.7.3. Removal If a element or any instances of the element are removed then any media captures that reference the removed people (through the element) must be modified to remove the personID in question. 7. Examples The following examples are based on partial updates to the sample XML file in clause 22/[I-D.ietf-clue-data-model-schema]. The changes are against the sample XML file. The changes are not cumulative across the examples. 7.1. Additional Presentation Capture A presentation video capture (VC5) is added to the conference for a document camera. As this doesn't share a co-ordinate space a new Capture scene (CS2) is added. The clue-info-diff indicates to add the new capture after media capture VC4. An existing encoding group is used. The new capture is also added to the simultaneous sets SS1 and SS2 as it may be used in conjunction with the other captures. The following shows the additions: Groves, et al. Expires March 19, 2015 [Page 12] Internet-Draft CLUE Partial Updates September 2014 VC5 VC5 VC5 video CS2 EG0 true document camera image 7.2. Capture Removal The video captures VC3 and VC4 are no longer available. As a result the following must be removed from the CLUE information: o mediaCaptures for VC3 and VC4 o sceneEntries for SE2 and SE3 as they only contain VC3 and VC4 o capture identities for VC3 and VC4 from the simultaneousSets The following shows the partial update with the removal: Groves, et al. Expires March 19, 2015 [Page 13] Internet-Draft CLUE Partial Updates September 2014 7.3. Attribute Modification The video capture VC4 zooms in on a particular participant and no longer represents a zoomed out view. As a result the description of VC4 and the participants are changed. The following shows the partial update with the change: zoomed in view on ciccio ciccio 8. Summary The authors believe that the use of partial updates is an efficient way of updating CLUE information minimising the amount of data that needs to be sent in an Advertisement. It is proposed to introduce partial Advertisements into the CLUE protocol. 9. Acknowledgements This template was derived from an initial version written by Pekka Savola and contributed by him to the xml2rfc project. Groves, et al. Expires March 19, 2015 [Page 14] Internet-Draft CLUE Partial Updates September 2014 10. IANA Considerations It is not expected that the proposed changes present the need for any IANA registrations. 11. Security Considerations It is not expected that the proposed changes present any addition security issues to the current framework. 12. References 12.1. Normative References [I-D.ietf-clue-data-model-schema] Presta, R. and S. Romano, "An XML Schema for the CLUE data model", draft-ietf-clue-data-model-schema-06 (work in progress), June 2014. [I-D.ietf-clue-protocol] Presta, R. and S. Romano, "CLUE protocol", draft-ietf- clue-protocol-01 (work in progress), June 2014. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC5261] Urpalainen, J., "An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors", RFC 5261, September 2008. [RFC6502] Camarillo, G., Srinivasan, S., Even, R., and J. Urpalainen, "Conference Event Package Data Format Extension for Centralized Conferencing (XCON)", RFC 6502, March 2012. 12.2. Informative References [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. Authors' Addresses Christian Groves (editor) Huawei Melbourne Australia Email: Christian.Groves@nteczone.com Groves, et al. Expires March 19, 2015 [Page 15] Internet-Draft CLUE Partial Updates September 2014 Weiwei Yang Huawei P.R.China Email: tommy@huawei.com Roni Even Huawei Tel Aviv Isreal Email: roni.even@mail01.huawei.com Groves, et al. Expires March 19, 2015 [Page 16]