Open Geospatial Consortium
OGC Doc 08-011
CR-Form-v3
CHANGE REQUEST
OWS 1.1 CR ?
rev1.1
Current version: 1.1 For
HELP
on using this form, see bottom of this page or look at the pop-up text over the symbols.Proposed change affects: AS Imp Spec X Best Practices Paper Other
Title: OWS Common 1.1 Change Request – Nested KVP parameter encoding
Source: Steven Keens, PCI Geomatics
Work item code: Date: January 28, 2008
Category: B
Use one of the following categories:
F (Critical correction)
A (corresponds to a correction in an earlier release)
B (Addition of feature),
C (Functional modification of feature)
D (Editorial modification)
Detailed explanations of the above categories can be found in the TC Policies and Procedures.
Reason for change: To provide a standard mechanism to support nested KVP parameters
Summary of change: Use the & and = characters and URL encoding to support nesting variable and dependant parameters.
Consequences if
not approved: Specific OWS specifications will encode variable or dependant KVP parameters differently. 11.5.6
Clauses affected: 11.5.5, 11.5.5.1, 11.5.5.2
Other specs X Other core specifications Any dependant upon OWS Common 1.1 that require nested KVP parameters. Affected: Abstract specifications
Best Practices Document Supporting Doc.
Other comments: Status
Disposition
11.5.6 Nested or dependant parameters
The OGC Technical Committee Policies & Procedures 05-020r3
When there is more than one nested or dependant parameter then those variable parameters should be nested and encoded within one fixed parameter. The value of the fixed parameter should use the KVP encoding technique described in subclause Error: Reference source not found. The value of the fixed parameter shall also be URL encoded to escape the special characters.
EXAMPLE 1: The following example URLs are simplified to highlight the relevant parts. The URLs are WCS 1.0.0 GetCoverage requests using KVP encoding where the parameter named BAND is dependant upon the coverage’s range description. BAND could be a name like TEMP or RADIANCE.
Old style WCS URL:
request=GetCoverage&coverage=C1&BAND=1
Instead the WCS 1.0.0 could have used nested KVP parameters. Modifying the WCS example to reflect this clause would result in:
1. Nest BAND parameter into a new parameter named RANGE resulting in:
REQUEST=GetCoverage&coverage=C1&RANGE=BAND=1 2. URL Encode entire value of RANGE parameter resulting in:
REQUEST=GetCoverage&coverage=C1&RANGE=BAND%3D1
EXAMPLE 2: The WPS specifies the fixed parameter named DataInputs using the comma as a separator between variable or dependant parameters. An example WPS Execute request is:
DATAINPUTS=Buffer,http://foo.bar/foo1,BufferDistance,100
That is an alternative method of encoding nested parameters enabling compliance with subclause 11.5.5. However, it requires new code to parse it. Instead the WPS could have used nested KVP parameters. Modifying the WPS example to reflect this clause would result in:
1. Covert commas to = or & depending upon nested parameters:
DATAINPUTS=Buffer=http://foo.bar/foo1&BufferDistance=100 2. URL Encode entire value of DataInputs parameter
DATAINPUTS=Buffer%3Dhttp%3A//foo.bar/foo1%26BufferDistance
%3D100
Note: The character sequence %3D and %26 are the URL encoded versions of the “=” and “&” characters, respectively.
To access the dependant parameters a server simply needs to extract the value of the fixed parameter, URL Decode the value, then parse the value using the sample parsing code for parsing the fixed values.
Note: It is possible to nest parameters recursively to any level but nesting more than one level deep is likely impractically and unnecessary.
