From a16ad20ab893e767c3aad622373dc089d161ec61 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Tue, 10 Dec 2024 21:27:34 -0500 Subject: [PATCH 1/3] document.adoc conflicts --- sources/document.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/sources/document.adoc b/sources/document.adoc index 8166da7..56bb5ba 100644 --- a/sources/document.adoc +++ b/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[] From 3204834c61e9fd0fbe95968191de930f79d07d0e Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Tue, 10 Dec 2024 21:44:10 -0500 Subject: [PATCH 2/3] Deconfliction Stripped down scope. Much of this content is covered in fundamentals. Added fundamentals Stripped down req-class to only include requirements. Other content was moved to fundamentals. --- sources/sections/01-scope.adoc | 113 ++-------------------- sources/sections/06-fundamentals.adoc | 130 ++++++++++++++++++++++++++ sources/sections/06-req-class.adoc | 97 ++----------------- 3 files changed, 146 insertions(+), 194 deletions(-) create mode 100644 sources/sections/06-fundamentals.adoc diff --git a/sources/sections/01-scope.adoc b/sources/sections/01-scope.adoc index 02a7512..f03f1c3 100644 --- a/sources/sections/01-scope.adoc +++ b/sources/sections/01-scope.adoc @@ -1,112 +1,13 @@ [[cls-1]] == Scope -The OGC Standard for Designing and Writing Modular Standards, also known as the `ModSpec`: -- Specifies rules for the internal structure and organization of a standard. -- Defines requirements for specifying the structure of a standards document as organized sets of criteria, those that are to be tested ("requirements") and those that are not tested ("recommendations" and "permissions"). -- Is designed to enable the clear and concise specification of requirements (the _shalls_ or _musts_ in a standard) that fully supports the ability to define implementable conformance tests. -- Formalizes implementing the requirements specified in the ModSpec so that reusable, modular standards can be developed. - -The standardization goal of the ModSpec is to define characteristics and a structure for the specification of Standards +The ModSpec defines characteristics and structure for the specification of Standards that will encourage implementation by minimizing difficulty determining -requirements, mimicking implementation structure, and maximizing usability and -interoperability.The goal of this approach is to enable implementations of a standard to be tested and deemed _conformant_ or not. - -NOTE: For OGC Standards work, the word “standard” in the ModSpec applies to all OGC draft standards, approved standards, draft Abstract Specifications, and approved Abstract Specifications. The exceptions are OGC Abstract Specifications that originate in ISO or Community Standards that are developed external to the OGC and then submitted to the OGC. - -Therefore, a standard that follows the rules specified in the ModSpec presents requirements organized in requirements classes which must be satisfied by passing the tests defined in a conformance suite (also known as the Abstract Test Suite in an OGC Standard). These tests are organized into conformance classes, each of which represents a mechanism for partial satisfaction of the standard. This results in a standard having a modular structure, where each requirements class has a corresponding conformance (test) class. In a well written standard, the normative clauses and any model or schema are organized in a manner that parallels the requirements and conformance clauses. A goal of the design pattern is the ability to define requirements classes and associated conformance classes that can be used across multiple standards. - -<> defines the UML model upon which the ModSpec is -based. Annex C also contains informal and non-normative definitions ordered for ease -of understanding. These two sections can be read first to aid in the understanding of -the rest of the document. - -NOTE: Please note that the ModSpec has been approved by the OGC Membership as a policy directive for the development and revision of any OGC Standard or Abstract Specification that has requirements. However, the ModSpec is written to be non-OGC specific and can be used by any Standards Development Organization (SDO) as a formal guide for structuring a standards document. - -[[things-to-know]] -=== Things to know - -NOTE: Reading the Terms and Definitions clause and Clause will help understanding the content and -requirements stated in this document. - -This OGC document, also known as the `ModSpec`: - -- Specifies rules for the internal structure and organization of a standard. -- Defines requirements for specifying the structure of a standards document as organized sets of criteria, those that are to be tested ("requirements") and those that are not tested ("recommendations" and "permissions"). -- Designed to enable the clear and concise specification of requirements (the _shalls_ or _musts_ in a standard) that fully supports the ability to define implementable conformance tests. - -The goal of this approach is to enable implementations of a standard to be tested and deemed _conformant_ or not. - -NOTE: Please note that the ModSpec has been approved by the OGC Membership as a policy directive for the development and revision of any OGC Standard or Abstract Specification that has requirements. However, the ModSpec is written to be non-OGC specific and can be used by any Standards Development Organization (SDO) as a formal guide for structuring a standards document. - -A standard that follows the rules specified in the ModSpec presents requirements organized in requirements classes which must be satisfied by passing the tests defined in a conformance suite (also known as the Abstract Test Suite in an OGC Standard). These tests are organized into conformance classes, each of which represents a mechanism for partial satisfaction of the standard. This results in a standard having a modular structure, where each requirements class has a corresponding conformance (test) class. In a well written standard, the normative clauses and any model or schema are organized in a manner that parallels the requirements and conformance clauses. A goal of the design pattern is the ability to define requirements classes and associated conformance classes that can be used across multiple standards. - -There are numerous examples of requirements/conformance classes that can be used not only in OGC Standards, but for geospatially focused standards defined by other organizations and Standards Development Organizations (SDOs). Some OGC examples can be found in the https://docs.ogc.org/is/19-072/19-072.html[OGC API - Common Part 1: Core Standard] and in the https://github.com/opengeospatial/cdbswg/blob/master/cdb-2.0/cdb-core-crs-requirements-class.adoc[CDB 2.0 Standard CRS Requirements Module]. By formally implementing the requirements specified in the ModSpec, reusable, modular standards can be developed. - -==== The ModSpec and the "Form" of a 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 <>) 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 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 <> - -A UML representation of important properties of this model is given in <>. - -==== ModSpec document structure - -Version 2.0 of the ModSpec is split into a Core standard and multiple Parts. These are: - -- Core: contains all the core requirements and informational text that define the model and internal structure of a standard. -- Part 1: UML Model requirements -- Part 2: XML and Schematron Model requirements - -Future Parts to the ModSpec Standard may include: - -- Part 5: RDF/OWL requirements - -==== 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. +requirements, mimicking implementation structure and maximizing usability and +interoperability. -These characteristics are slightly modified from the Open Group definitions to accommodate the use of the building block concept in standards work. +NOTE: For OGC Standards work, the word “standard” in this document applies to all OGC draft standards, approved standards, draft Abstract Specifications, and approved Abstract Specifications. The exceptions are OGC Abstract Specifications that originate in ISO or Community Standards that are developed external to the OGC and then submitted to the OGC. -NOTE: The approach modelled in the ModSpec has been referred to as the "core and extension model" due to its -insistence on a modular structure throughout all parts of a standard and its implementation. +<> defines the UML model upon which the ModSpec is +based. Annex B also contains informal and non-normative definitions ordered for ease +of understanding. These two sections can be read first to aid in the understanding of the rest of the document. diff --git a/sources/sections/06-fundamentals.adoc b/sources/sections/06-fundamentals.adoc new file mode 100644 index 0000000..5924729 --- /dev/null +++ b/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 +<>). 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 <>. + +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 <> 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 <> and <>. + +=== 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 <>) 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 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 <> + +A UML representation of important properties of this model is given in <>. + + + diff --git a/sources/sections/06-req-class.adoc b/sources/sections/06-req-class.adoc index 1ac8c8b..2b1dfc9 100644 --- a/sources/sections/06-req-class.adoc +++ b/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 <> - -A UML representation of important properties of this model is given in <>. - -==== 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 -<>). 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 <>. - -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 <> 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 <> and <>. - -=== ModSpec Requirements Class: Core +== 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"] From 71ab6ff07193747cc371b8583efaa0b796f789be Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Tue, 10 Dec 2024 22:20:48 -0500 Subject: [PATCH 3/3] Content preservation Reviewed the history of the main branch. Restored potentially duplicate content to Scope. This will allow us to confirm that the content is fully addressed elsewhere before it is deleted from Scope. Additional minor changes extracted from the history. --- sources/sections/01-scope.adoc | 117 ++++++++++++++++++++++++-- sources/sections/06-fundamentals.adoc | 2 +- sources/sections/06-req-class.adoc | 2 +- 3 files changed, 112 insertions(+), 9 deletions(-) diff --git a/sources/sections/01-scope.adoc b/sources/sections/01-scope.adoc index f03f1c3..78d67f6 100644 --- a/sources/sections/01-scope.adoc +++ b/sources/sections/01-scope.adoc @@ -1,13 +1,116 @@ [[cls-1]] == Scope +The OGC Standard for Designing and Writing Modular Standards, also known as the `ModSpec`: -The ModSpec defines characteristics and structure for the specification of Standards +- Specifies rules for the internal structure and organization of a standard. +- Defines requirements for specifying the structure of a standards document as organized sets of criteria, those that are to be tested ("requirements") and those that are not tested ("recommendations" and "permissions"). +- Is designed to enable the clear and concise specification of requirements (the _shalls_ or _musts_ in a standard) that fully supports the ability to define implementable conformance tests. +- Formalizes implementing the requirements specified in the ModSpec so that reusable, modular standards can be developed. + +The standardization goal of the ModSpec is to define characteristics and a structure for the specification of Standards that will encourage implementation by minimizing difficulty determining -requirements, mimicking implementation structure and maximizing usability and -interoperability. +requirements, mimicking implementation structure, and maximizing usability and +interoperability.The goal of this approach is to enable implementations of a standard to be tested and deemed _conformant_ or not. + +NOTE: For OGC Standards work, the word “standard” in the ModSpec applies to all OGC draft standards, approved standards, draft Abstract Specifications, and approved Abstract Specifications. The exceptions are OGC Abstract Specifications that originate in ISO or Community Standards that are developed external to the OGC and then submitted to the OGC. + +Therefore, a standard that follows the rules specified in the ModSpec presents requirements organized in requirements classes which must be satisfied by passing the tests defined in a conformance suite (also known as the Abstract Test Suite in an OGC Standard). These tests are organized into conformance classes, each of which represents a mechanism for partial satisfaction of the standard. This results in a standard having a modular structure, where each requirements class has a corresponding conformance (test) class. In a well written standard, the normative clauses and any model or schema are organized in a manner that parallels the requirements and conformance clauses. A goal of the design pattern is the ability to define requirements classes and associated conformance classes that can be used across multiple standards. + +<> defines the UML model upon which the ModSpec is +based. Annex C also contains informal and non-normative definitions ordered for ease +of understanding. These two sections can be read first to aid in the understanding of +the rest of the document. + +NOTE: Please note that the ModSpec has been approved by the OGC Membership as a policy directive for the development and revision of any OGC Standard or Abstract Specification that has requirements. However, the ModSpec is written to be non-OGC specific and can be used by any Standards Development Organization (SDO) as a formal guide for structuring a standards document. + +[[things-to-know]] +=== Things to know + +NOTE: Reading the Terms and Definitions clause and Clause will help understanding the content and +requirements stated in this document. + +This OGC document, also known as the `ModSpec`: + +- Specifies rules for the internal structure and organization of a standard. +- Defines requirements for specifying the structure of a standards document as organized sets of criteria, those that are to be tested ("requirements") and those that are not tested ("recommendations" and "permissions"). +- Designed to enable the clear and concise specification of requirements (the _shalls_ or _musts_ in a standard) that fully supports the ability to define implementable conformance tests. + +The goal of this approach is to enable implementations of a standard to be tested and deemed _conformant_ or not. + +NOTE: Please note that the ModSpec has been approved by the OGC Membership as a policy directive for the development and revision of any OGC Standard or Abstract Specification that has requirements. However, the ModSpec is written to be non-OGC specific and can be used by any Standards Development Organization (SDO) as a formal guide for structuring a standards document. + +A standard that follows the rules specified in the ModSpec presents requirements organized in requirements classes which must be satisfied by passing the tests defined in a conformance suite (also known as the Abstract Test Suite in an OGC Standard). These tests are organized into conformance classes, each of which represents a mechanism for partial satisfaction of the standard. This results in a standard having a modular structure, where each requirements class has a corresponding conformance (test) class. In a well written standard, the normative clauses and any model or schema are organized in a manner that parallels the requirements and conformance clauses. A goal of the design pattern is the ability to define requirements classes and associated conformance classes that can be used across multiple standards. + +There are numerous examples of requirements/conformance classes that can be used not only in OGC Standards, but for geospatially focused standards defined by other organizations and Standards Development Organizations (SDOs). Some OGC examples can be found in the https://docs.ogc.org/is/19-072/19-072.html[OGC API - Common Part 1: Core Standard] and in the https://github.com/opengeospatial/cdbswg/blob/master/cdb-2.0/cdb-core-crs-requirements-class.adoc[CDB 2.0 Standard CRS Requirements Module]. By formally implementing the requirements specified in the ModSpec, reusable, modular standards can be developed. + +==== 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). + +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 <>) 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 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 <> + +A UML representation of important properties of this model is given in <>. + +==== ModSpec document structure + +Version 2.0 of the ModSpec is split into a Core standard and multiple Parts. These are: + +- Core: contains all the core requirements and informational text that define the model and internal structure of a standard. +- Part 1: UML Model requirements +- Part 2: XML and Schematron Model requirements + +Future Parts to the ModSpec Standard may include: + +- Part 5: RDF/OWL requirements + +==== 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: + +. 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. -NOTE: For OGC Standards work, the word “standard” in this document applies to all OGC draft standards, approved standards, draft Abstract Specifications, and approved Abstract Specifications. The exceptions are OGC Abstract Specifications that originate in ISO or Community Standards that are developed external to the OGC and then submitted to the OGC. +These characteristics are slightly modified from the Open Group definitions to accommodate the use of the building block concept in standards work. -<> defines the UML model upon which the ModSpec is -based. Annex B also contains informal and non-normative definitions ordered for ease -of understanding. These two sections can be read first to aid in the understanding of the rest of the document. +NOTE: The approach modelled in the ModSpec has been referred to as the "core and extension model" due to its +insistence on a modular structure throughout all parts of a standard and its implementation. diff --git a/sources/sections/06-fundamentals.adoc b/sources/sections/06-fundamentals.adoc index 5924729..550cc44 100644 --- a/sources/sections/06-fundamentals.adoc +++ b/sources/sections/06-fundamentals.adoc @@ -118,7 +118,7 @@ awarded by a testing entity based on these conformance classes. . Examples and notes are informative, and do not use "normative" language. -In informative sections, the word "will" implies that something is an implication of a requirement. The "will" statements are +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 diff --git a/sources/sections/06-req-class.adoc b/sources/sections/06-req-class.adoc index 2b1dfc9..d729d03 100644 --- a/sources/sections/06-req-class.adoc +++ b/sources/sections/06-req-class.adoc @@ -1,5 +1,5 @@ [[cls-6]] -== 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.