Open Geospatial Consortium
OGC Doc 06-112
CR-Form-v3
CHANGE REQUEST
OWS Common
CR ?
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: Date: June 2, 2007
Category: 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 New revisions of all implementation specifications
Affected: Abstract specifications Best Practices Document
Supporting Doc.
Other comments: This idea has been discussed by a number of OGC members, and reflects comments received from non-OGC members.
Status
Disposition
12 Guidance for OWS Implementation Specifications
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
06-121].”
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.
