Merge pull request #52 from opengeospatial/cmh-edits2

document.adoc conflicts

sources/document.adoc

@@ -5,7 +5,7 @@
 :committee: technical
 :docnumber: 08-131r3
 :edition: 1.1.0
-:received-date: 2024-11-29
+:received-date: 2024-12-10
 :issued-date: 2025-xx-xx
 :published-date: 2025-xx-xx
 :copyright-year: 2024
@@ -16,7 +16,7 @@
 :fullname_3: Chuck Heazel
 :role_3: editor
 :language: en
-:submitting-organizations: Carl Reed, Heazeltech, ImageMatters
+:submitting-organizations: Carl Reed, Charles Heazel, ImageMatters
 :imagesdir: images
 :mn-document-class: ogc
 :mn-output-extensions: xml,html,doc,pdf,rxl
@@ -37,6 +37,8 @@ include::sections/04-terms-and-defs.adoc[]
 
 include::sections/05-conventions.adoc[]
 
+include::sections/06-fundamentals.adoc[]
+
 include::sections/06-req-class.adoc[]
 
 include::sections/07-mapping.adoc[]

sources/sections/01-scope.adoc

@@ -45,6 +45,8 @@ There are numerous examples of requirements/conformance classes that can be used
 
 ==== The ModSpec and the "Form" of a standard
 
+NOTE: This content is duplicated in fundamentals
+
 NOTE: For OGC Standards, the assumptions is that documents are in a commonly used
 logical form (template). 
 
@@ -93,6 +95,8 @@ Future Parts to the ModSpec Standard may include:
 
 ==== Building Blocks
 
+NOTE: This content is covered in Fundamentals.
+
 In software development technology, there is a concept called _building block_. In software development, building blocks are used to support the software build process where source code files/libraries can be accessed from multiple sources, converted into executable code, and linked together in the proper order until a complete set of executable files is generated. The same concept can be applied to OGC Standards development: Requirements classes and/or modules can be linked together from one or more standards to create a new standard not originally envisioned when the requirements were originally defined.
 
 The https://pubs.opengroup.org/architecture/togaf8-doc/arch/chap32.html[Open Group] suggests that building blocks have the following characteristics:

sources/sections/06-fundamentals.adoc

@@ -0,0 +1,130 @@
+[[fundamentals]]
+== Standards Fundamentals
+
+=== Building Blocks
+
+In software development technology, there is a concept called _building block_. In software development, building blocks are used to support the software build process where source code files/libraries can be accessed from multiple sources, converted into executable code, and linked together in the proper order until a complete set of executable files is generated. The same concept can be applied to OGC Standards development: Requirements classes and/or modules can be linked together from one or more standards to create a new standard not originally envisioned when the requirements were originally defined.
+
+The https://pubs.opengroup.org/architecture/togaf8-doc/arch/chap32.html[Open Group] suggests that building blocks have the following characteristics:
+
+. A building block is a package of functionality defined to meet business or domain needs.
+. A building block may interoperate with other, inter-dependent, building blocks.
+. A good building block has the following characteristics:
+.. Considers implementation and usage, and evolves to exploit technology and standards.
+.. May be assembled from other building blocks.
+.. May be a subassembly of other building blocks.
+.. Ideally a building block is re-usable and replaceable, and well specified.
+. A building block may have multiple implementations but with different inter-dependent building blocks.
+
+These characteristics are slightly modified from the Open Group definitions to accommodate the use of the building block concept in standards work.
+
+=== Standardization Context - Goals and Targets
+
+NOTE: Don't forget to add the requirements cited.
+
+Every OGC Standard document shall include a Standardization Goal (see requirement TBD). This is a concise statement of the problem that the Standard helps address and the strategy envisioned for achieving a solution.  This strategy typically identifies real-world entities that need to be modified or constrained.  At the abstract level, those entities are the Standardization Target Types.  These are the classes of entities to be standardized. A Standard defines the requirements levied on one or more Standardization Target Types. 
+
+Instances of a Standardization Target Type are the Standardization Targets.  These are the real-world manifestations of the Standardization Target Type.  In summary:
+
+* Standardization Goal – identifies the problem and identifies the actors and entities involved in solving that problem
+* Standardization Target Type – An abstract representation of one of the actors or entities identified in the Standardization Goal
+* Standardization Target – an implementation of a Standardization Target Type. These are the real-world entities which can be tested for conformance with the requirements documented in the Standard.
+
+Standardization Target Types can be hierarchical.  The Conceptual, Logical, Physical hierarchy is one example where the Standardization Target Types are information models. Another example would be implementations of OGC API - Features Part 2 which support XML data exchange.
+
+Notice that the Standardization Targets and Standardization Target Types no longer form a simple taxonomy. The Standardization Target Types, Standardization Targets, and Standardization Goal provide a well-defined context for the standard.  This will help users of standards to quickly understand the scope of a Standard and to select those Standards appropriate for their needs. It also will help keep Standards developers focused on the intended use of their standards, avoiding standards which are overly broad and/or unfocused.
+
+=== Conformance, Requirements, and key information
+
+In the conformance test suite, there will be a test defined to verify the validity of
+the claim that an implementation of the standard (standardization target) satisfies
+each mandatory requirement specified in the standard. Since the normative language of the body of the standard and the
+conformance test classes both define what conformance to the standard means, they
+will be equivalent in a well-written standard. The ModSpec requires
+a standards document to be well-written, at least in stating requirements and conformance
+tests.
+
+Conformance tests are aggregated into conformance classes that specify how certain
+"certificates of conformance" are achieved. The natural inclination is to aggregate
+the requirements. The issue that blocks this approach is that some requirements are
+optional while others are mandatory. To achieve a cleaner separation of requirements,
+the ModSpec separates them into sets (called "requirements classes"), each of which
+has no optional components. Since the normative statement of each requirement is only 
+declared once and is uniquely identified as such, each requirement will be in a clause associated to its requirements class.
+
+Therefore, the ModSpec defines a "requirements class" as a set of requirements that must
+all be passed to achieve a particular conformance class (see
+<<term-conformance-test-class>>). This document also includes a "middle" structure
+called a conformance test module. Requirements modules
+parallel the conformance test modules. A standard written to the ModSpec may
+use this "module" structure in any manner consistent with the rest of this Policy.
+
+A standard may have mandatory and optional requirements classes.  This allows the options
+in the testing procedure to be grouped into non-varying mandatory and optional conformance classes.
+Each requirement within an optional requirements class is mandatory when that requirements class is
+implemented. When needed, a particular requirements class may contain only a single
+requirement.
+
+However, care must be taken, since the requirements classes may not always in a one-to-one
+correspondence to conformance classes in other standards which may be the source of
+requirements for a standard conformant to the ModSpec. If other standards are
+used, their options shall be specified to be useable within a standard conformant to
+this policy, see <<cls-6-5-1>>.
+
+Conformance classes may contain dependencies on one another. These are represented by
+tests in one conformance class that state that another conformance class must be
+passed to qualify to pass this conformance class. In terms of requirements, that says
+that the dependent conformance class contains tests (by reference) for all
+requirements of the "included" conformance class.
+
+As defined in the ModSpec, one requirements
+class is dependent on another if the other is included through such a reference. In
+this manner, requirements classes can be treated as sets of requirements (each in a
+single requirements class but included in others by reference to its "home"
+requirements class).
+
+In the ModSpec, each conformance requirement is separated in its own labeled
+paragraph, such as <<req-1>> above.
+
+The distribution of the information in a standard is not restricted. The only
+requirement is that requirements be grouped in a manner
+consistent with the conformance test classes, see <<req-6>> and <<req-7>>. 
+
+=== Documenting the Standard
+
+NOTE: For OGC Standards, the assumptions is that documents are in a commonly used
+logical form (template). 
+
+This form should be specified by the following descriptions:
+
+. A standards document contains Clauses (corresponding to numbered sections as they might
+appear in a table of contents) which describe its standardization target and its requirements.
+. A standard contains Annexes or is associated to other documents (both a
+logical type of Clause), one of which is the Conformance Test Suite (which may be an
+abstract description of the test suites to be implemented separately). In OGC Documents, this is Annex A – Abstract Test Suite.
+. All requirements, recommendations, permissions, and models are introduced and defined first in
+the numbered Clauses.
+. All requirements are identifiable as requirements. 
+. All requirements in a document are uniquely numbered.
+. All tests for conformance to those requirements are defined in the Conformance Test Suite.
+. Tests are be grouped for convenience into conformance test classes and if desired the classes are grouped into conformance test modules.
+. The tests, if conducted, determine to some degree of certainty whether an
+implementation meets the requirements which the tests reference.
+. The tests are organized into some number of conformance "classes" where each conformance class has a one to one relationship with a requirements class. If a standard
+does not do this, it is has by default only one "conformance class".
+. Certificates of conformance (see <<term-all-components-schema-document>>) are
+awarded by a testing entity based on these conformance classes.
+. There is a clear distinction between normative and informative parts of the text.
+. Examples and notes are informative, and do not use "normative"
+language.
+
+In informative sections, the use of the word "will" implies that something is an implication of a requirement. The "will" statements are
+not requirements, but explain the consequence of requirements.
+
+The ModSpec defines a "requirement" of a standard as an atomic testable
+criterion. See the formal definition of requirement in <<term-requirement>>
+
+A UML representation of important properties of this model is given in <<annex-B-2>>.
+
+
+

sources/sections/06-req-class.adoc

@@ -1,95 +1,16 @@
 [[cls-6]]
-== Key Concepts and the ModSpec Core Requirements Class
-
-This clause defines the key concepts and requirements that define the ModSpec Core Requirements Class.
-
-[[cls-6-1]]
-=== The ModSpec and the "Form" of a standard
-
-NOTE: For OGC Standards, the assumption is that documents are in a commonly used
-logical form (template). 
-
-In informative sections, the use of the word "will" implies that something is an implication of a requirement. The "will" statements are not requirements but explain the consequence of requirements.
-
-The ModSpec defines a "requirement" of a standard as an atomic testable
-criterion. See the formal definition of requirement in <<term-requirement>>
-
-A UML representation of important properties of this model is given in <<annex-B-2>>.
-
-==== Standardization Context - Goals and Targets
-
-Every OGC Standard document shall include a Standardization Goal. This is a concise statement of the problem that the Standard helps address and the strategy envisioned for achieving a solution.  This strategy typically identifies real-world entities that need to be modified or constrained.  At the abstract level, those entities are the Standardization Target Types.  These are the classes of entities to be standardized. A Standard defines the requirements levied on one or more Standardization Target Types. 
-
-Instances of a Standardization Target Type are the Standardization Targets.  These are the real-world manifestations of the Standardization Target Type.  In summary:
-
-* Standardization Goal – identifies the problem and identifies the actors and entities involved in solving that problem
-* Standardization Target Type – An abstract representation of one of the actors or entities identified in the Standardization Goal
-* Standardization Target – an implementation of a Standardization Target Type. These are the real-world entities which can be tested for conformance with the requirements documented in the Standard.
-
-Standardization Target Types can be hierarchical.  The Conceptual, Logical, Physical hierarchy is one example where the Standardization Target Types are information models. Another example would be implementations of OGC API - Features Part 2 which support XML data exchange.
-
-Notice that the Standardization Targets and Standardization Target Types no longer form a simple taxonomy. The Standardization Target Types, Standardization Targets, and Standardization Goal provide a well-defined context for the standard.  This will help users of standards to quickly understand the scope of a Standard and to select those Standards appropriate for their needs. It also will help keep Standards developers focused on the intended use of their standards, avoiding standards which are overly broad and/or unfocused.
-
-==== Conformance, Requirements, and key information
-
-In the conformance test suite, there will be a test defined to verify the validity of
-the claim that an implementation of the standard (standardization target) satisfies
-each mandatory requirement specified in the standard. Since the normative language of the body of the standard and the
-conformance test classes both define what conformance to the standard means, they
-will be equivalent in a well-written standard. The ModSpec requires
-a standards document to be well-written, at least in stating requirements and conformance
-tests.
-
-Conformance tests are aggregated into conformance classes that specify how certain
-"certificates of conformance" are achieved. The natural inclination is to aggregate
-the requirements. The issue that blocks this approach is that some requirements are
-optional while others are mandatory. To achieve a cleaner separation of requirements,
-the ModSpec separates them into sets (called "requirements classes"), each of which
-has no optional components. Since the normative statement of each requirement is only 
-declared once and is uniquely identified as such, each requirement will be in a clause associated to its requirements class.
-
-Therefore, the ModSpec defines a "requirements class" as a set of requirements that must
-all be passed to achieve a particular conformance class (see
-<<term-conformance-test-class>>). This document also includes a "middle" structure
-called a conformance test module. Requirements modules
-parallel the conformance test modules. A standard written to the ModSpec may
-use this "module" structure in any manner consistent with the rest of this Policy.
-
-A standard may have mandatory and optional requirements classes.  This allows the options
-in the testing procedure to be grouped into non-varying mandatory and optional conformance classes.
-Each requirement within an optional requirements class is mandatory when that requirements class is
-implemented. When needed, a particular requirements class may contain only a single
-requirement.
-
-However, care must be taken, since the requirements classes may not always in a one-to-one
-correspondence to conformance classes in other standards which may be the source of
-requirements for a standard conformant to the ModSpec. If other standards are
-used, their options shall be specified to be useable within a standard conformant to
-this policy, see <<cls-6-5-1>>.
-
-Conformance classes may contain dependencies on one another. These are represented by
-tests in one conformance class that state that another conformance class must be
-passed to qualify to pass this conformance class. In terms of requirements, that says
-that the dependent conformance class contains tests (by reference) for all
-requirements of the "included" conformance class.
-
-As defined in the ModSpec, one requirements
-class is dependent on another if the other is included through such a reference. In
-this manner, requirements classes can be treated as sets of requirements (each in a
-single requirements class but included in others by reference to its "home"
-requirements class).
-
-In the ModSpec, each conformance requirement is separated in its own labeled
-paragraph, such as <<req-1>> above.
-
-The distribution of the information in a standard is not restricted. The only
-requirement is that requirements be grouped in a manner
-consistent with the conformance test classes, see <<req-6>> and <<req-7>>. 
-
-=== ModSpec Requirements Class: Core
+== ModSpec Requirements Class: Core
 
 The following requirements specify the rules for the content and structure of a modular standard. These requirements are also known as the `core` of the ModSpec.
 
+[[req-0]]
+[requirement,model=ogc,type="general"]
+[width="90%",cols="2,6"]
+|===
+|*REQ000* | */req/core/ogc-compliance* +
+Any new OGC Standard, abstract specification that contains requirements, or major revision of an existing OGC Standard _SHALL_ comply with the requirements stated in this document.
+|===
+
 [[req-1]]
 [requirement,model=ogc,type="general"]
 [width="90%",cols="2,6"]