OWS Common 1.1 Change Request � Nested KVP parameter encoding
OGC Doc 08-011
Open Geospatial Consortium
CR-Form-v3
CHANGE REQUEST
OWS 1.1 CR ?
rev
1.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
Title:
OWS Common 1.1 Change Request – Nested KVP parameter encoding
Source:
Steven Keens, PCI Geomatics
Work item code:
Category:
Other
Date: January 28, 2008
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:
Clauses affected:
Specific OWS specifications will encode variable or dependant KVP parameters
differently.
11.5.6
11.5.5, 11.5.5.1, 11.5.5.2
Other specs
X Other core specifications
Affected:
Any dependant upon OWS Common 1.1
that require nested KVP parameters.
Abstract specifications
Best Practices Document
Supporting Doc.
Other comments:
Status
Disposition
11.5.6 Nested or dependant parameters
Where there is a need for variable or dependant parameter names the specific OWS should encode
the variable parameters nested within a fixed parameter. The name of fixed parameter is
determined by the specific OWS. The entire nested parameter shall be URL encoded (see
subclause Error: Reference source not found) to prevent confusing the fixed parameters with the
variable 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.
Last Revision Date: 2 December 2017
Page 2
Open Geospatial Consortium
CR-Form-v3
CHANGE REQUEST
OWS 1.1 CR ?
rev
1.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
Title:
OWS Common 1.1 Change Request – Nested KVP parameter encoding
Source:
Steven Keens, PCI Geomatics
Work item code:
Category:
Other
Date: January 28, 2008
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:
Clauses affected:
Specific OWS specifications will encode variable or dependant KVP parameters
differently.
11.5.6
11.5.5, 11.5.5.1, 11.5.5.2
Other specs
X Other core specifications
Affected:
Any dependant upon OWS Common 1.1
that require nested KVP parameters.
Abstract specifications
Best Practices Document
Supporting Doc.
Other comments:
Status
Disposition
11.5.6 Nested or dependant parameters
Where there is a need for variable or dependant parameter names the specific OWS should encode
the variable parameters nested within a fixed parameter. The name of fixed parameter is
determined by the specific OWS. The entire nested parameter shall be URL encoded (see
subclause Error: Reference source not found) to prevent confusing the fixed parameters with the
variable 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.
Last Revision Date: 2 December 2017
Page 2