OWS Common Change Request - Simplify specifications
OGC Doc 06-112
Open Geospatial Consortium
CR-Form-v3
CHANGE REQUEST
CR ?
OWS Common
rev
-
Current version:
1.1.0
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:
Eliminate duplication between Implementation Specification documentation and XML
schemas
Source:
Peter Schut
Work item code:
Category:
Date: June 2, 2007
D
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:
Simplify specification creation, eliminate inconsistencies, and improve legibility
of OGC specifications.
Summary of change: Provide guidance to specification editors that all elements and attributes in XML
schemas must be fully documented, and the specification document should not
replicate XML schema contents but rather be restricted to overview and access
descriptions.
Consequences if
not approved:
1. OGC specifications will continue to be time consuming to create.
2. Inconsistencies between XML schemas and Word documents may exist
Clauses affected:
Other specs
X Other core specifications
Affected:
Supporting Doc.
Other comments:
Status
Disposition
New revisions of all implementation
specifications
Abstract specifications
Best Practices Document
This idea has been discussed by a number of OGC members, and reflects
comments received from non-OGC members.
12 Guidance for OWS Implementation Specifications
12.1 General guidance
The OGC Technical Committee Policies & Procedures 05-020r3
This clause provides some guidance for editors of OWS
Implementation Specifications,
plus authors of drafts and change requests. This guidance is in the
form of best practices,
which are not normative but are strongly encouraged.
Some of the recommended practices are:
a) Implementation Specifications should not duplicate common
material. Each
specification should normatively reference all relevant parts of this
document. Such
normative references may take the form of stating: “The
GetCapabilities operation
request shall be as specified in Subclauses 7.2 and 7.3 of OWS
Common [OGC 06121].”
b) Implementation specification documents should not duplicate
information found in XML schemas. XML schemas should contain
complete documentation for each attribute and element. Specification
documents should not duplicate this material in tabular or text form.
b) The “Normative references” Clause of each OGC Implementation
Specification
should list this document, and specify a specific OGC document (which
includes the
version number).
c) The contents of XML documents should be specified using XML
Schemas, not
DTDs. If some of the XML elements or types used are from an external
vocabulary
for which the only official description is a DTD, this recommendation
will not apply.
See Subclauses 12.2 and 12.3 for recommendations on naming and
including XML
Schema Documents.
d) The template for new and revised OGC Implementation
Specifications should be
used.
Last Revision Date: 2 December 2017
Page2
Open Geospatial Consortium
CR-Form-v3
CHANGE REQUEST
CR ?
OWS Common
rev
-
Current version:
1.1.0
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:
Eliminate duplication between Implementation Specification documentation and XML
schemas
Source:
Peter Schut
Work item code:
Category:
Date: June 2, 2007
D
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:
Simplify specification creation, eliminate inconsistencies, and improve legibility
of OGC specifications.
Summary of change: Provide guidance to specification editors that all elements and attributes in XML
schemas must be fully documented, and the specification document should not
replicate XML schema contents but rather be restricted to overview and access
descriptions.
Consequences if
not approved:
1. OGC specifications will continue to be time consuming to create.
2. Inconsistencies between XML schemas and Word documents may exist
Clauses affected:
Other specs
X Other core specifications
Affected:
Supporting Doc.
Other comments:
Status
Disposition
New revisions of all implementation
specifications
Abstract specifications
Best Practices Document
This idea has been discussed by a number of OGC members, and reflects
comments received from non-OGC members.
12 Guidance for OWS Implementation Specifications
12.1 General guidance
The OGC Technical Committee Policies & Procedures 05-020r3
This clause provides some guidance for editors of OWS
Implementation Specifications,
plus authors of drafts and change requests. This guidance is in the
form of best practices,
which are not normative but are strongly encouraged.
Some of the recommended practices are:
a) Implementation Specifications should not duplicate common
material. Each
specification should normatively reference all relevant parts of this
document. Such
normative references may take the form of stating: “The
GetCapabilities operation
request shall be as specified in Subclauses 7.2 and 7.3 of OWS
Common [OGC 06121].”
b) Implementation specification documents should not duplicate
information found in XML schemas. XML schemas should contain
complete documentation for each attribute and element. Specification
documents should not duplicate this material in tabular or text form.
b) The “Normative references” Clause of each OGC Implementation
Specification
should list this document, and specify a specific OGC document (which
includes the
version number).
c) The contents of XML documents should be specified using XML
Schemas, not
DTDs. If some of the XML elements or types used are from an external
vocabulary
for which the only official description is a DTD, this recommendation
will not apply.
See Subclauses 12.2 and 12.3 for recommendations on naming and
including XML
Schema Documents.
d) The template for new and revised OGC Implementation
Specifications should be
used.
Last Revision Date: 2 December 2017
Page2