[[WFS_Sync]]
== Peer-to-peer enterprise web feature server synchronization

=== Introduction

This clause describes the peer-to-peer synchronization protocol implemented to 
satisfy the enterprise-to-enterprise data synchronization use case for
OGC® Testbed 12.

[[Components]]
=== Components
Figure 2 illustrates the components involved in the OGC® Testbed 12
enterprise-to-enterprise synchronization experiment. 

[[arch_image]]
.Component diagram for Synchronization experiment
image::includes/images/Sync_Arch.png["Architecture diagram for Synchronization experiment",scaledwidth=70%,align="center"]

The experiment was performed between two WFSs; the Carbon WFS and the CubeWerx
WFS.  _<<Table1,WFS product versions and end points>>_ lists the product
versions and endpoint of the servers.

[[Table1]]
.WFS product versions and end points
[options="header",width="100%",cols="15%,15%,15%,55%"]
|===
| Vendor | Product | Supported WFS Versions | Endpoints

| CubeWerx
| CubeWerx Suite 8.1.1
| 1.0.0 +++++++
| https://tb12.cubewerx.com/a011/cubeserv/default/wfs/2.0.2/sync

| Carbon
| Carbon Cloud WFS     
| 1.0.0 +++++++
| http://ows12.azurewebsites.net/wfs
|===

Both servers implement the WFS standard with the REST binding (see OGC 11-080r1).  Furthermore, each server implements the newly specified Sync resource (see 8.3) which allows the servers to synchronize the state of their features.

_<<Table2,Server capabilities>>_ lists the specific capabilities of each server
used in the experiment. Cross-walking the capabilities resulted in the
experiment being performed using features encoded with GML.  In other words,
when the server exchange features through the "Sync" resource, those features
are encoded using GML.

[[Table2]]
.Server capabilities
[options="header",width="100%",cols="20%,40%,40%"]
|===
| Property | CubeWerx | Carbon

| Versions 
| 1.0.0 +++++++
| 1.0.0 +++++++
| Operations
| GetCapabilities +
DescribeFeatureType +
GetFeature +
ListStoredQueries +
DescribeStoredQueries +
GetPropertyValue +
Transaction +
Sync +
GET +
PUT +
POST +
DELETE
| GetCapabilities +
DescribeFeatureType +
GetFeature +
Sync +
Transaction +
GET +
PUT +
POST +
DELETE
| Output Formats
| GML v3.2 +
GML v3.1.1 +
GML v2.1.2 +
GeoJSON +
KML +
SHAPE +
ATOM +
RSS +
HTML
| GML v3.2 +
GML v3.1.1 +
GML v2.1.2 +
GeoJSON +
KML +
CSV +
TopoJSON
| Spatial operators
| Disjoint +
Equals +
Intersects +
Touches +
Crosses +
Contains +
Overlaps +
BBOX +
Within
| Disjoint +
Equals +
Intersects +
Touches +
Crosses +
Contains +
Overlaps +
BBOX +
Within +
Beyond
| Spatial operands
| gml:Envelope +
gml:Point +
gml:LineString +
gml:Polygon +
gml:CircleByCenterPoint
| gml:Envelope +
gml:Point +
gml:LineString +
gml:Curve +
gml:Polygon +
gml:Surface +
gml:MultiPoint +
gml:MultiLineString +
gml:MultiCurve +
gml:MultiPolygon +
gml:MultiSurface
| Scalar operators
| PropertyIsBetween +
PropertyIsEqualTo +
PropertyIsGreaterThan +
PropertyIsGreaterThanOrEqualTo +
PropertyIsLessThan +
PropertyIsLessThanOrEqualTo +
PropertyIsLike +
PropertyIsNotEqualTo +
PropertyIsNull
| PropertyIsBetween +
PropertyIsEqualTo +
PropertyIsGreaterThan +
PropertyIsGreaterThanOrEqualTo +
PropertyIsLessThan +
PropertyIsLessThanOrEqualTo +
PropertyIsLike +
PropertyIsNotEqualTo +
| Logical
| And, Or, Not
| And, Or
| Available Stored Queries
| GetFeatureById +
NearestNeighbours
| None

| Number of CRSs
| > 10
| > 10

| Support for GML SF
| Yes
| Yes

| REST API
| Yes
| Yes

| GeoJSON
| Yes
| Yes

| ATOM
| Yes
| No

| XSLT vendor extension
| Yes
| No
|===

[[SynchronizingFeatures]]
=== Synchronizing features

==== Introduction

The synchronization protocol assumes that each peer can, upon request, identify
for the other peer which data has changed since a previous checkpoint.  In the
case of web feature services, this means that a responding WFS can identify
which features have changed for a specified feature type since a previous
checkpoint.  This set of changed data, or features in the case of a WFS, is
called the _change set_.

The process of synchronization involves one peer, the requesting or client peer,
requesting from the other peer, the responding or server peer, a change set
from some specified checkpoint.  

This engineering report describes an XML encoding for the change set that
includes a standard wfs:FeatureCollection, for listing all newly created
and modified existing features, and a list of feature identifiers that lists
the features that have been deleted from the server.

The specific focus of Testbed 12 is the web feature service, however the
protocol is sufficiently generic to work between any two peers as long as
the encoding for the change set is defined.  For example, this protocol
could be used to sync geopackages (see GeoPackage Mobile Apps Integrations,
OGC 16-030) in the field where the change set itself is encoded as a geopackage.

[[ChangeSetProcessing]]
==== Change set processing 

===== Introduction

This clause briefly describes how inserted, updated and/or deleted features
appearing in a change set should be processed by a requesting peer.

===== Inserting a new feature

If a requesting peer encounters a feature in the change set that does not
currently exist in its repository, then the requesting peer shall create an
identical new feature in its repository.

The new feature shall be retrievable using the identifier provided by the
responding peer.

NOTE: In general, when creating a new feature, a web feature service may assign
its own identifier to a feature.  This is perfectly fine as long as the
server maintains the relationship between its own identifier and the identifiers
provided by its synchronizing partners.  In other words, a feature in a server
that supports synchronization may be retrievable using any number of gml:id
values in addition to the one that a server natively assigns to the feature.

==== Updating an existing feature

If a requesting peer encounters a feature in the change set that already exists
in its repository then it shall update the state of its copy to match that for
the responding peer.

===== Deleting features

If a requesting peer encounters a feature in the change set that has been
deleted then it shall delete that feature from its repository. The question of
how deleted features are represented in the changeset is discussed in the
_<<SyncResponse,synchronization response>>_ clause.

==== Synchronization protocol

===== Introduction

Servers that implement one or more of the KVP-GET, XML-POST or SOAP bindings
shall implement the Sync operation that may be used to retrieve the change set.
This operation shall be advertised in the server's capabilities document in the
standard way.

Servers implementing the REST architectural style shall provide a _/sync_
resource to which the appropriate query parameters may be appended in order to
retrieve the change set.

==== No prior synchronization between the peers 

This clause describes the messages exchanged between a requesting and responding
peer when there has been no prior synchronization between the peers.  For the
purpose of discussion the requesting peer is called _alpha_ and the responding
peer is called _beta_.  The synchronization proceeds as follows:

* Alpha requests a change set from beta.
* Since alpha and beta have never synchronized before, beta generates a change
  set for alpha that contains all the features of the specified type.
** The canonical format of the response shall be GML 3.2; other formats are
   allowed but they are not defined is this engineering report.
* Alpha reads the checkpoint value from the HTTP header of the response and
  saves it in order to retrieve the next change set.
* Alpha processes the change set and synchronizes its repository with that of
  beta.

For servers implementing a REST architectural style, the following example
sequence diagram illustrates this exchange:

* alpha service Id = 052350f2-70ca-4201-837d-15f2af7ed15c
* beta service Id  = e039611a-198a-474a-800d-763f79bf6ec5

----
alpha                                                                      beta 
  |                                                                          |
  | GET /sync?TYPENAME=InWaterA_1M&SERVICEID=urn:uuid:0523...d15c  HTTP/1.1  |
  | Host: www.alpha.com                                                      |
  | Accept: application/gml+xml; version=3.2                                 |
  +------------------------------------------------------------------------->|
  |                                                                          |
  |  HTTP/1.1 200 OK                                                         |
  |  Host: www.beta.com                                                      |
  |  Content-Type: application/gml+xml; version=3.2                          |
  |  OGC-SYNC-ServiceId: urn:uuid:e039611a-198a-474a-800d-763f79bf6ec5       |
  |  OGC-SYNC-Checkpoint: urn:uuid:4dc01e43-8cf8-4d8b-875e-0ee110eb2a75      |
  |                                                                          |
  |  <?xml version="1.0"?>                                                   |
  |  <wfs:ChangeSet                                                          |
  |     serviceId="urn:uuid:e039611a-198a-474a-800d-763f79bf6ec5"            |
  |     checkPoint="urn:uuid:4dc01e43-8cf8-4d8b-875e-0ee110eb2a75">          |
  |     <wfs:FeatureCollection timestamp="2016-04-08T12:26:25"               |
  |                            numberMatched="525"                           |
  |                            numberReturned="525" ... />                   |
  |        .                                                                 |
  |        .                                                                 |
  |        .                                                                 |
  |        <wfs:member>                                                      |
  |           ...                                                            |
  |           <InWaterA_1M gml:id="1013">                                    |
  |              ...                                                         |
  |           </InWaterA_1M>                                                 |
  |           ...                                                            |
  |        </wfs:member>                                                     |
  |        .                                                                 |
  |        .                                                                 |
  |        .                                                                 |
  |     </wfs:FeatureCollection>                                             |
  |     <wfs:DeletedObjects>                                                 |
  |        <fes:ResourceId fid="1013"/>                                      |
  |     </wfs:DeletedObjects>                                                |
  |  </wfs:ChangeSet>                                                        |
  |<-------------------------------------------------------------------------+
----

NOTE: Practically speaking this initial synchronization scenario is only feasible if beta does not already contain too great a volume of data.  In this more likely scenario, one possible approach would be to export beta's data and define a checkpoint that signifies this point in time and is distributed with the export.  Alpha can then be seeded with beta's data using some other, more rapid, means and normal peer-to-peer synchronization can proceed from then on using the accompanying checkpoint value.

NOTE: A server that implement the sync operation must do two things: (a) it must keep track of changes changes made to all the features that it offers and (b) for each requester, it must keep track of the checkpoints in order to know up to which point each requester has been sync'ed. Requesters are identified using the _<<sync_xml_encoding,serviceId>>_ parameter and the _<<sync_xml_encoding,checkpoints>>_ are pointers into the tracked changes list indicating that the requester is synced to that point

==== Subsequent synchronization between peers

In the case where the participating peers alpha and beta have previously
synchronized, the protocol proceeds as follows.

* Alpha requests a change set from beta using the checkpoint from the previous 
  sync..
* The response is a wfs:FeatureCollection document containing the features that
  have changed since the specified checkpoint value.

For servers implementing a REST architectural style, the following example
sequence diagram illustrates this exchange:

----
alpha                                                                      beta 
  |                                                                          |
  |                                                                          |
  | GET /sync?TYPENAME=InWaterA_1M                                           |
  |     &SERVICEID=urn:uuid:052350f2-70ca-4201-837d-15f2af7ed15c             |
  |     &CHECKPOINT=urn:uuid:4dc01e43-8cf8-4d8b-875e-0ee110eb2a75  HTTP/1.1  |
  | Host: www.alpha.com                                                      |
  | Accept: application/gml+xml; version=3.2                                 |
  +------------------------------------------------------------------------->|
  |                                                                          |
  |  HTTP/1.1 200 OK                                                         |
  |  Host: www.beta.com                                                      |
  |  Content-Type: application/gml+xml; version=3.2                          |
  |  OGC-SYNC-ServiceId: urn:uuid:e039611a-198a-474a-800d-763f79bf6ec5       |
  |  OGC-SYNC-Checkpoint: urn:uuid:a4e9819b-2139-47cf-b297-7656a9da0a00      |
  |                                                                          |
  |  <?xml version="1.0"?>                                                   |
  |  <wfs:ChangeSet                                                          |
  |     serviceId="urn:uuid:e039611a-198a-474a-800d-763f79bf6ec5"            |
  |     checkPoint="urn:uuid:a4e9819b-2139-47cf-b297-7656a9da0a00">          |
  |     <wfs:FeatureCollection timestamp="2016-04-10T12:12:57"               |
  |                            numberMatched="5"                             |
  |                            numberReturned="5" ... />                     |
  |        .                                                                 |
  |        .                                                                 |
  |        .                                                                 |
  |        <wfs:member>                                                      |
  |           <InWaterA_1M gml:id="3764">...</InWaterA_1M>                   |
  |        </wfs:member>                                                     |
  |        <wfs:member>                                                      |
  |           <InWaterA_1M gml:id="1154">...</InWaterA_1M>                   |
  |        </wfs:member>                                                     |
  |        <wfs:member>                                                      |
  |           <InWaterA_1M gml:id="72">...</InWaterA_1M>                     |
  |        </wfs:member>                                                     |
  |        .                                                                 |
  |        .                                                                 |
  |        .                                                                 |
  |     </wfs:FeatureCollection>                                             |
  |     <wfs:DeletedObjects>                                                 |
  |        <fes:ResourceId fid="101"/>                                       |
  |        <fes:ResourceId fid="47625"/>                                     |
  |        <fes:ResourceId fid="1783"/>                                      |
  |        <fes:ResourceId fid="5534"/>                                      |
  |        <fes:ResourceId fid="3"/>                                         |
  |    </wfs:DeletedObjects>                                                 |
  |  </wfs:ChangeSet>                                                        |
  |<-------------------------------------------------------------------------+
----

NOTE: Alpha and beta can reverse roles in order to achieve bi-directional synchronization.

==== Conflict resolution

Conflicts arise when the same feature property is updated with different
values on synchronizing peers during the inter-sync period.  For example,
consider the following sequence of events:

----
        PEER 1                      PEER 2
T1      A=10                        A=10
T2      A=20                        A=30
T3      A=30  <------ SYNC -------- A=30
T4      A=30  ------- SYNC -------> A=30
----

At T1, peer 1 and peer 2 are synchronized.  At T2 an update occurs on each
server that changes the value of A on peer 1 to 20 and the value of A on
peer 2 to 30.  The problem arises when the next synchronization between
peer 1 and peer 2 occurs.  Without intervention one of these updates will
be lost depending on which peer first acts as the server peer on the next
sync.  Say peer 1 initiates the synchronization by executing the Sync operation
on peer 2 at T3.  Peer 1 will receive the value of 30 for A and update its
A value to 30.  When peer 2 performs the subsequent complimentary sync at
T4, it will read the value 30 from peer 1 and do nothing.  The fact that on
peer 1 A had a value of 20 will be lost.  Ideally the synchronizing server
should detect this situation and then perform some sort of conflict resolution.
For Testbed 12, the CubeWerx server can detect this conflict but does not
currently implement any resolution strategy.

This engineering report acknowledges this problem but does not offer a
specific solution since there are a number of conflict resolution strategies -- with the goal of data convergence between the synchronizing peers -- that
would need to be implemented and tested and this work is beyond the scope
of work possible with the time and resources available in TB12.  This is
left as a future work item.

[[AccessingTheChangeSet]]
=== Accessing the change set

==== Introduction

This clause defines how the change set may be retrieved by a requesting peer.

This clause defines the encoding of the Sync operation for servers that
implement KVP-GET, XML-POST or SOAP encoded requests.

This clause also defines the _/sync_ resource for servers that implement a 
REST architectural style.

==== Sync operation 

[[sync_xml_encoding]]
===== XML encoding

The following XML-fragment declares the XML-encoding for the Sync operation:

[source,xml]
----
   <xsd:element name="Sync" type="wfs:SyncType"/>
   <xsd:complexType name="SyncType">
      <xsd:complexContent>
         <xsd:extension base="wfs:GetFeatureType">
            <xsd:attribute name="serviceId"  type="xsd:AnyURI" use="required"/>
            <xsd:attribute name="checkpoint" type="wfs:AnyURI"/>
         </xsd:extension>
      </xsd:complexContent>
   </xsd:complexType>
----

The Sync operation extends the WFS GetFeature only for the purpose of inheriting
syntax because the required encoding of the Sync operation looks very much like
a GetFeature request. However, the semantics of the Sync operation are different
than those of the GetFeature operation in that the Sync operation only operates
on the restricted subset of features that are members of the change set.

The features that are members of a change set is determined independently of the
Sync operation and is a time dependent function of the transaction operations
executed on the server between checkpoints.  This implies that any filter 
specified on the Sync operation, for example,  has no effect on the set of
features that appear in the change set of a feature type between checkpoints.
The filter only has an effect at the time the change set is to be transmitted
from the server to the client.  Consider a client that is only interested in
changes in a particular area.  Without a filter, the entire change set would 
e transmitted to the client and the client would have to prune the change set
keeping only the features of interest and discarding the rest.  The filter on
the Sync operation is simply a way for the client to tell the server to prune
the set before transmitting it.  Regardless of any filter specified on the
Sync operation, the sync checkpoints remain sequential.  This description 
applies generally to all Sync operation parameters in that their scope is
restricted to the features that are members of the change set.

The following table lists the parameters of a Sync operation and describes
how they operate differently (or not) than those used with a GetFeature 
operation:

[[Table2a]]
.Sync request parameter restrictions
[options="header", width="90%",cols="25%,75%"]
|===
|Parameter Name |Description

|service | As described in OGC 14-102, clause 7.6.2

|version | As described in OGC 14-102, clause 7.6.2

|handle | As described in OGC 14-102, clause 7.6.2

|startIndex | As described in OGC 14-102, clause 7.6.3 but its scope is restricted to the features in the change set

|count | As described in OGC 14-102, clause 7.6.3 but its scope is restricted to the features in the change set

|resultType | As described in OGC 14-102, clause 7.6.3 but its scope is restricted to the features in the change set

|outputFormat | As defined in clause _<<SyncResponse,Response>>_; other output formats are allowed but not defined in this document

|resolve | As described in OGC 14-102, clause 7.6.4 but its scope is restricted to the features in the change set

|resolveDepth | As described in OGC 14-102, clause 7.6.4 but its scope is restricted to the features in the change set

|resolveTimeout | As described in OGC 14-102, clause 7.6.4 but its scope is restricted to the features in the change set

|namespaces | As described in OGC 14-102, clause 7.6.6

|vsp | Vendor-specific parameters are allowed for the KVP-encoded Sync request but their meaning is not described in this document

|typeNames | As described in OGC 14-102, clause 7.9.2.4.1 but restricted to a single feature type

|schema-element() | As described in OGC 14-102, clause 7.9.2.4.2

|aliases | As described in OGC 14-102, clause 7.9.2.4.3 but restricted to a single feature type

|srsName | As described in OGC 14-102, clause 7.9.2.4.4

| _projection clause_ | As described in OGC 14-102, clause 7.9.2.4.5, 7.9.2.4.6

|resolution path | As described in OGC 14-102, clause 7.9.2.4.7

|_selection clause_ | As described in OGC 14-102, clause 7.9.2.5 but its scope is restricted to the feature in the changes set and joins of any kind are not supported

| _sorting clause_ | As described in OGC 14-102, clause 7.9.2.5.4 but its scope is restricted to the features in the change set

| _stored query expressions_ | Not considered for this testbed
|===

The following conformance WFS conformance classes from OGC 14-102, related to
retrieving features from the server, are incompatible with the sync operation:

* Locking WFS

* Standard joins

* Spatial joins

* Temporal joins

===== KVP encoding

This clause defines the KVP-encoding for the Sync operation.

The following table, _<<Table3,Keywords for KVP-encoded Sync operation>>, describes the parameters for the KVP-encoding of the Sync operation:

[[Table3]]
.Keywords for KVP-encoded Sync operation
[options="header", width="90%",cols="25%,15%,60%"]
|===
|URL Component |O/M |Description

| _Common KeyWords_ +
  (REQUEST=Sync)
| 
| See Table 4, OGC 14-102 for additional parameters that may be used

| Standard Presentation Parameters
|
| See Table 5, OGC 14-102 

| Standard Resolve Parameters
|
| See Table 6, OGC 14-102

| Additional common keywords
|
| See Table 7, OGC 14-102

| TYPENAMES
| Mandatory
| Name of single, feature type to synchronize (joins not supported)

| SRSNAME 
| Optional
| See 7.9.2.4.2, OGC 14-102

| Projection clause
| Optional
| See Table 9, 14-102

| _Selection clause_ +
  (see <<Table4,KVP-encoding for selection clause>>,
  <<Table5,Additional selection clause parameters>>)
| Optional
| The selection clause may be used to constrain the set of change set of new
  or modified features that are presented to a requesting peer is a response
  document.  The complete syntax for specifying the selection clause is
  presented in _<<Table4,KVP-encoding for selection clause>>_ and
  _<<Table5,Additional selection clause parameters>>_ below.

|===

NOTE: All KVP parameters are subject to the restrictions described the 
_<<Table2a,Sync request parameter restrictions>>_ table.

NOTE: The canonical output format for the _Sync_ operation is GML 3.2 (i.e.  application/gml+xml; version=3.2).  Other output formats are allowed but are not described in this engineering report.

The following tables, <<Table4,KVP-encoding for selection clause>>
and <<Table5,Additional selection clause parameters>> define the parameters
for a selection clause.

[[Table4]]
.KVP-encoding for selection clause (see Table 3, OGC 14-103)
[options="header", width="90%",cols="25%,10%,65%"]
|===
|URL Component |O/M |Description

|FILTER
|O
|The value of the parameter shall be a filter expression encoded using the
 language specified by the FILTER_LANGUAGE parameter

|FILTER_LANGUAGE
|O
|Indicate the predicate language used to encode the filter expression that
 is the value of the FILTER parameter.  The default value of
 urn:ogc:def:queryLanguage:OGC-FES:Filter shall be used to indicate that the
 value of the FILTER parameter is a string encoding the filter using an XML
 fragment as defined in OGC 14-103.
|===

[[Table5]]
.Additional selection clause parameters (see Table 3a, OGC 14-103)
[options="header"]
|===
|Query class|Query subclass|URL Component|OpenSearch Parameter(s)|Description|Data type and value

|Text search^3^
|N/A
|Q
|searchTerms
|A space separated list of search terms that are used to search all text fields
 in a catalogue record.
|Character string

|FeatureById search
|N/A
|RESOURCEIDS
|Uid
|Comma separated list of record identifiers to retrieve.
|Character string

1.9+|Spatial search
|Bounding box search
|BBOX
|Box
|Identifies a bounding box to be used as a spatial predicate
| Character string

1.5+|Arbitrary geometry search^4^
| GEOMETRY
|Geometry
|Identifies a geometry to be used as a spatial predicate
|WKT String (see OGC 06-103r4)

|GEOMETRY_CRS
|N/A
|The CRS used to express the value of GEOMETRY parameter
|URI (The default value is http://www.opengis.net/def/crs/epsg/0.4326

|RELATION
|Relation
|The spatial operator to apply use the value of GEOMETRY parameter
a| - Character string; One of:
   ** Equals
   ** Disjoint
   ** Touches
   ** Within
   ** Overlaps
   ** Crosses
   ** #*Intersects*#
   ** Contains
   ** DWithin
   ** Beyond

|DISTANCE
|N/A
|If the value of relation is DWithin or Beyond, contains the distance value.
|Number

|DISTANCE_UOM
|N/A
|The units of measure used to express the value of the distance parameter
|Character string (see http://unitsofmeasure.org/ucum.html)

1.3+|Proximity search^5^
|LAT
|lat
|Latitude expressed in WGS84
|Number

|LON
|lon
|Longitude expressed in WFS84
|Number

|RADIUS
|radius
|Search radius expressed in meters along the surface of the Earth
|Number

1.2+|Temporal search
1.2+|N/A
|TIME
|start/end
|A time instance or time period
|Character string (see http://www.w3.org/TR/NOTE-datetime)

|TRELATION
|N/A
|The temporal operator to apply using the value of the TIME parameter
a| - Character string; One of:
   ** After
   ** Before
   ** Begins
   ** BegunBy
   ** TContains
   ** During
   ** EndedBy
   ** Ends
   ** #*TEquals*#^1^
   ** Meets
   ** MetBy
   ** TOverlaps
   ** OverlappedBy
   ** #*AnyInteracts*#^2^

6.1+a| 1. Default for a time instance. 
       2. Default of a time period.
       3. Basic text searching using the "q" parameter is expected to proceed as follows:.
          a. Math against the full text of all character-valued properties of a feature.
          b. Matching is case-insensitive.
          c. In the case of multiple search terms, if any of the property values being tested, as per (a), contains at least one of the specified search terms then that feature shall appear in the result set.
          d. Exact phrases can be delimited using quotations (i.e. 0x22 in ASCII).
       4. When specified, the GEOMETRY parameter of the Arbitrary Geometry Search subclass is mandatory.  The other parameters are optional and if not specified on a request assume the default values denoted in the "Data type and value" column.
       5. When specified, the Proximity Search parameters are all mandatory
|===

NOTE: Tables <<Table4,KVP-encoding for selection clause>> and <<Table5,Additional selection clause parameters>> are copied from OGC 14-103, OpenGIS Filter Encoding 2.5 Encoding Standard and are presented here for convenience only.

WARNING: The use of the parameters BBOX and GEOMETRY from Table 5, <<Table5, Additional selection clause parameters>> in conjunction with the SYNC operation between WFS peers is subject to patent restrictions (see US patent 7873697).

The following table, _<<Table6,Sync-specific parameters>>_ lists additional
parameters that shall be appended to a KVP-encoded Sync operation according
to the specified obligation.

[[Table6]]
.Sync-specific parameters
[options="header", width="80%",cols="20%,50%,10%,20%"]
|===
| URL Component | Description | Default Value | Obligation

| SERVICEID
| A unique identifier for the entity making the request.
| None
| Mandatory

| CHECKPOINT
| Identifies that last point of synchronization for the specified serviceId
| None
| Optional on first sync; Mandatory thereafter.

|===

==== /sync resource

For a service implementing the REST architectural style, the resource _/sync_ 
is define and may be accessed by a requesting peer to obtain the change set
from a responding peer.  

Tables _<<Table4,Sync parameters>>_, _<<Table5,Additional selection clause
parameters>>_, <<Table6,Sync-specific parameters>> define parameters that 
may be appended as query parameters to the _/sync_ resource.

==== Custom HTTP headers

The synchronization protocol defined in this engineering report defines two
custom HTTP headers named _OGC-SYNC-ServiceId_ and _OGC-SYNC-Checkpoint_.

The value of the OGC-SYNC-ServiceId header is used by a peer to communicate its
unique service identifier when communicating with its partner peer.

The value of the OGC-SYNC-Checkpoint uniquely identifies a point in time from
which a responding server shall generate a change set.

The format of both these values is opaque.

These headers shall be set by a responding peer to communicate its service
identifier and the checkpoint value to a requesting peer.

The OGC-SYNC-ServiceId header shall be set by a requesting peer to communicate
its service identifier to the responding peer.  The OGC-SYNC-Checkpoint header
shall not be set by a requesting peer on its *initial* sync but shall be set by
the requesting peer on all *subsequent* sync requests.

These parameters may be set by a requesting peer to communicate its service
identifier and a checkpoint value to a responding peer.

NOTE: The query parameters SERVICEID and CHECKPOINT (see <<Table6,Sync-specific parameters>> may also be used to communicate the service identifier and checkpoint values.  If both the query parameters and HTTP headers are set in any communication, then the corresponding values shall match; otherwise an exception shall be generated.

[[SyncResponse]]
==== Response

===== Introduction

The response to accessing the _/sync_ resource or executing a _Sync_ operation
is a change set.  This clause defines the encoding for a change set. 

The response document contains the collection of features that is composed
of the newly created and updated features since a specified checkpoint.  The
response document also contains a list of feature identifiers for features
that have been deleted since that same specified checkpoint.

This encoding is easily adaptable to output formats other than GML (e.g.
GeoJSON).  It is also more easily adaptable to synchronization in a
heterogeneous system where the synchronizing peers are not both web feature
services (e.g. geopackage-to-geopackage synchronization or geopackage-to-wfs
synchronization).  A drawback of this encoding is that it may require more
processing by the requesting peer, especially if that peer is a web feature
service.

===== XML response 

The following XML-fragment defines the default synchronization response (i.e.
the output format is set to application/gml+xml; version=3.2).

The response is a composed of a wfs:FeatureCollection element containing all
the newly created and modified features of a responding peer from a specified
checkpoint and a wfs:DeletedObjects element containing the identifiers of all
deleted features of a responding peer from the same specified checkpoint.

[source,xml]
----
   <xsd:element name="ChangeSet" type="wfs:ChangeSetType"/>
   <xsd:complexType name="ChangeSetType">
      <xsd:complexContent>
         <xsd:sequence>
            <xsd:element ref="wfs:FeatureCollection" minOccurs="0"/>
            <xsd:element name="DeletedObjects" minOccurs="0">
               <xsd:complexType>
                  <xsd:sequence>
                    <xsd:element ref="fes:_Id"
                                 minOccurs="0" maxOccurs="unbounded"/>
                  </xsd:sequence>
               </xsd:complexType>
            </xsd:element>
            <xsd:element name="ConflictObjects" minOccurs="0">
               <xsd:complexType>
                  <xsd:sequence>
                    <xsd:element ref="fes:_Id"
                                 minOccurs="0" maxOccurs="unbounded"/>
                  </xsd:sequence>
               </xsd:complexType>
            </xsd:element>
         </xsd:sequence>
         <xsd:attribute name="serviceId" type="xsd:anyURI" use="required"/>
         <xsd:attribute name="checkPoint" type="xsd:anyURI"/>
         <xsd:attribute name="numberOfFeatures" type="xsd:nonNegativeInteger"/>
      </xsd:complexContent>
   </xsd:complexType>
----

The serviceId parameter contains the unique service identifier of the 
responding peer.  The specific format of this identifier is not specified
in this engineering report but it is strongly recommended that a UUID be used.

The checkPoint parameter contains the new, opaque checkpoint value that may
be used to obtain a subsequent change set.  

If the resultType parameter (see X.X) is set to "hits" when the Sync operation
is executed then the server shall NOT perform a checkpoint but rather return
an empty change set document (see Note below) with the value of the
"numberOfFeatures" parameter set to the number of features that would be
presented to the client if the checkpoint was actually performed.

NOTE: If a server detects conflicts in the course of computing the number of
features that the sync operation would return, those conflicts may be listed
in the ConflictObject section of the response document.

In order for a responding peer to communicate to a requesting peer which
features have been deleted, the synchronization response document shall
contain a list of of feature identifiers (see 7.2, OGC 14-102) from the
responding peer that have been deleted.  These shall be encoded using the
wfs:DeletedObjects element in the change set.  The content of the
wfs:DeletedObject element is simply an unordered list of the feature
identifiers of features (see 7.2, OGC 14-102) that have been deleted.

NOTE: (Point for discussion): Another implementation option for handling deleted features would be to allow a requesting peer to make an additional synchronization request with the same checkpoint that includes a parameter to indicate that the deleted feature identifiers should be returned rather than the complete change set.  This approach is more complicated but has the added benefit that other output formats can be supported without modification.

In the situation where a synchronizing peer has detected conflicts, the 
server shall not synchronize the conflicted feature but shall instead list
their identifiers in the ConflictObject section of the change set document.

===== JSON response

In the OGC® Testbed-11 experiment, the list of changed, modified or deleted
features was encoded using GeoJSON which was an output format that both
participating servers supported.  However, GeoJSON lacks a number of
necessary structures to meet the requirements of peer-to-peer
synchronization and so for Testbed-12 an XML response shall be used
since it allows already-existing structures such as wfs:FeatureCollection
and/or wfs:Transaction to be reused.

=== Relationship to GSS

This clause discusses the relationship between the synchronization protocol
describe herein and the GeoSynchronization Service (GSS, see OGC 10-069r2).  

The purpose of a GeoSynchronization service is to allow organizations to deploy
a transactional WFS to a "crowd" without giving the crowd direct transactional
access to the server.  Rather the GSS mediates the transactional interaction
between members of the crowd and the WFS allowing the organization to validate
data before being committed to the server.  In this sense a GSS is a workflow
manager for crowdsourcing WFSs.  A convenient way to think about GSS is as an
OGC® standards-based version of Open Street Map.  Unlike Open Street Map,
however, which replies on the crowd to verify data, the GSS enforces a more
formal and mandatory approach to data validation. 

In addition to acting as a crowdsourcing manager, the GSS specification
describes a subscription subsystem that allows interested parties to be
notified by a GSS whenever changes are committed to the WFS that the GSS
is managing.  This subscription subsystem can also be used synchronize
interested third-party WFSs with the crowdsourced WFS that is managed by
the GSS. 

The current GSS synchronization subsystem is a master-slave, subscription-based,
push synchronization.  This means that whenever a set of changes is committed
to the crowdsourced WFS server managed by the GSS, the GSS will push those
changes (via a WFS transactions) to whichever third-party servers have
subscribed to the GSS for the purpose of synchronization (see 7.2,
OGC 15-010r4).

By contrast, the enterprise-to-enterprise synchronization capability tested in
the OGC® Testbed-12 describes the mechanism and protocol for synchronizing two
peer WFSs but does not describe when synchronization occurs or how it is
triggered.  It is a more light-weight synchronization capability since no
mediating or coordinating service such as GSS is required.  However, only WFSs
that have implemented the necessary resources and protocol can participate in
the synchronization thus preventing legacy WFSs for being synchronized.  The
GSS, on the other hand, does not require any changes to the WFSs participating
in a synchronization activity and so legacy as well as current WFSs can be
synchronized.
It seems reasonable, moving forward, that the enterprise-to-enterprise
synchronization protocol be integrated into the GSS as part of its
synchronization subsystem.  However, time and resource limitation during
the OGC® Testbed-11 did not allow for this investigation to be performed
and so this is flagged as a future work item.
