1.1.  Understanding the ModSpec

Reading the Terms and Definitions clause will help in understanding the content and requirements stated in this document.

The Standards Fundamentals clause provides a more detailed introduction to the fundamental concepts used in the creation of this document.

Annex C of this Standard defines the UML model upon which the ModSpec is based. Annex C also contains informal and non-normative definitions ordered for ease of understanding. The two sections contained in Annex C should be read first to aid in the understanding of the rest of the ModSpec.

1.2.  ModSpec document structure

Version 1.1 of the ModSpec is split into a Core standard and multiple Parts. These are:

Future Parts to the ModSpec Standard may include:

5.1.  Building Blocks Terms and Definitions

5.2.  Document Terms and Definitions

5.3.  Core Terms and Definitions

6.1.  Symbols (and abbreviated terms)

All symbols used in this document are either:

6.2.  Identifiers

The normative provisions in this standard are denoted by the URI namespace

https://www.opengis.net/spec/modspec-1/1.1/

All requirements that appear in this document are denoted by partial URIs which are relative to the namespace shown above.

For the sake of brevity, the use of “req” in a requirement URI denotes:

https://www.opengis.net/spec/modspec-1/1.1/

An example might be:

/req/core/crs

All conformance tests that appear in this document are denoted by partial URIs which are relative to the namespace shown above.

For the sake of brevity, the use of “conf” in a requirement URI denotes:

https://www.opengis.net/spec/modspec-1/1.1/

The same convention is used for permissions (per) and recommendations (rec).

6.3.  Abbreviated terms

In this document the following abbreviations and acronyms are used or introduced:

6.4.  Finding requirements and recommendations

Each normative statement in the ModSpec is stated in one and only one place, in a standard format, with a unique label, such as REQ001, REC001, or PER001. A requirement, recommendation, or permission may be repeated for clarification. The statement with the unique label is considered the official statement of the normative requirement or recommendation.

In this document, all requirements are associated with tests specified in the test suite in Annex A. The reference to the requirement in the conformance test is done by a requirements label and/or unique identifier. Recommendations and permissions are not tested although they should still be documented using a standard template and have unique labels and/or identifiers.

Requirements classes are separated into their own clauses and named and specified according to inheritance (direct dependencies). The Conformance test classes in the test suite are similarly named to establish an explicit and link between requirements classes and conformance test classes.

7.1.  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 can be linked together from one or more standards to create a new standard not originally envisioned when the requirements were originally defined.

The Open Group suggests that building blocks have the following characteristics:

These characteristics are slightly modified from the Open Group definitions to accommodate the use of the building block concept in standards work.

7.2.  Standardization Context — Goals, Target Types, and Targets

Every standards document should 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 Target Types can be hierarchical. The Conceptual, Logical, Physical model hierarchy is one example where the Standardization Target Types are information models. Another example would be implementations of OGC API — Features Part 2 that support XML data exchange.

The following are two examples of Target Types and Targets as used in the OGC API suite of standards:

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.

7.3.  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 as per the tests defined in the related conformance class (see Clause 5.3.1). Each requirements class has a one-to-one correspondence with a conformance class. A standard written to conform with the ModSpec mayuse this “module” structure in any manner consistent with the rest of the ModSpec.

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.

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 seen in Requirement 1 below.

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 Requirement 6 and Requirement 7.

7.4.  Documenting the Standard

Standards development should be a repeatable process producing a suite of standards with a common look and feel. In addition, that process should embody the ModSpec principles so that ModSpec conformance is almost automatic. A standardized template is an essential element of such a repeatable process.

This template should be specified by the following descriptions:

A UML representation of important properties of this model is given in Annex C, Section 2.

8.1.  General Requirements

The following requirement states that every requirement in a standards document is associated with one and only one requirements class(es).

There may be one or more requirements in a requirements class.

The following requirement states that every requirement is testable.

Therefore, by definition, any requirements class that contains the requirement that failed to pass also fails to pass.

The following requirement states that every component of a standard will have a unique identifier

The following recommendation encourages the consistent use of these unique identifiers/labels in the standard as well as any external documentation referencing that standard.

While a requirement may be referenced in more than one place in a standard, the normative definition of a requirement is its “home” (see Clause 6.4) and will be the only place where full normative language is used.

The following permissions relate to possible content specified in the core of a standard. In this manner, the core requirements class and its associated content can be thought of not only as the requirements of the core conformance class, but as a form of reference model for establishing core vocabularies and schemas for the entire standard.

The following states how and where vocabularies are specified in relation to a requirements class.

For example, consider the specification of a metadata service in which the Dublin Core concept “Title” and the XML schema structure used for its specification can be in the core of the service standard. How a particular request-response pair uses the data structure to mean the title of a particular document or dataset will be specified in the requirements class in which the request-response pair is defined and set against requirements.

8.2.  Using the model

The primary difficulty in speaking about standards (or candidate standards) as a group is their diverse nature. Some standards use UML to define behavior, others use XML or JSON to define data structures, and others use no specific modeling language at all. However, they all must model the standardization target type to which they apply since they need to use unambiguous language to specify requirements. Thus, the only thing they have in common is that they define testable requirements against some model of an implementation of the standard (the standardization target type). For completeness, they should also specify the conformance tests for these requirements that are to be run for validation of the implementations against those requirements.

The assumption is that each standard has a single (root) standardization target type from which all extensions inherit. If this is not true, then the standard can be logically factored into parts each corresponding to a “root” standardization target type, and that the standard addresses each such part separately (see the definition of requirements class). In this sense, the next requirement divides the standard into parts more than restricting their content.

In practice, the standardization target type of the core requirements class is the root of an inheritance tree where extensions all have the core’s target type as an ancestor, and thus can be considered as belonging to the same “class” or type as the core’s target type.

This means that all requirements are considered as targeting the same entity being tested for a particular certificate of conformance. The test may specify other types as intermediaries or indirect dependencies (see indirect dependency of-a-requirements-class).

A repeated requirement will be in a separate requirements class. This is because it will have a separate standardization target and thus belong to the requirements to be tested by a separate conformance class. For example, in a service interface, a standard may be written that requires both the client and server to use a particular language for data transmission. Since the client and server are different standardization targets types (except in some special circumstances), they will have different conformance test classes.

One solution is to state the requirement twice, once for each target. An alternative is to introduce a new “superclass”.

An example is provided below.

 

Figure 1 — Abstract superclass example

8.3.  The “standards” document

Each standards document is comprised of a set of requirements and their associated conformance tests. Requirements are grouped into requirements classes. Each requirements class is contained within one section/clause in a standards document.

The following requirement states that the sequence of requirements and requirements classes is the same as the sequence of conformance tests and conformance classes in the conformance suite.

If two requirements are in the same requirements class, they should be tested in the same conformance class in the conformance suite. Each requirement is separately identifiable either by a unique label and/or identifier as is done in the ModSpec.

In summary, the structure of the requirements and requirements classes of the model should be reflected in the organization of the conformance tests and classes, and also in the structure of the normative clauses in the specification document.

8.4.  Conformance Test Suite

The requirements specified in this clause will be applied directly to the test suite, and in particular to the conformance classes. By definition, a “test suite” is a collection of identifiable conformance classes. A conformance class is a well-defined set of conformance tests. Each conformance test is a concrete or abstract (depending on the type of suite) description of a test to be performed on each candidate conformant implementation, to determine if it meets a well-defined set of requirements as stated in the normative clauses of the standards document.

Strict parallelism of implementation and governance is the essence of this standard.

8.5.  Requirements for Modularity

The following states that each conformance class tests a complete requirements class

This requirement stops conformance classes from containing optional requirements and tests, and, at least as far as the standard is concerned, makes all certificates of conformance mean that exactly the same tests have been conducted. Standards documents may use recommendations for such options, but the conformance test classes do not test recommendations.

This means that the class’s tests depend on some parameter that must be defined before the tests can be executed. This can be thought of as an “if-then-else” decision tree.

For example, if a conformance class needs to apply tests against a specific data format, such as GML or KML, then XYZ(GML) is XYZ using GML, and XYZ(KML) is XYZ using KML. Because the parameters choose which requirements will be tested, two conformance tests with distinct parameters should be considered as distinct conformance classes.

The most common parameters are the identities of indirect dependencies. For example, if a service uses or produces feature data, the format of that data may be a parameter, such as GML, KML or GeoJSON. When reading a certificate of conformance, the values of such parameters are very important.

Conformance to a particular conformance class means exactly the same thing everywhere.

This means that there is a strict correspondence between the requirements classes and the conformance test classes in the test suite. Recall that a conformance test class may specify dependencies causing other conformance test classes to be used, but this is a result of an explicit requirement in the “home” requirements class.

Such referenced conformance classes may be in the same standard or may be a conformance class of another standard.

The following is an example of an indirect dependency. If a service specifies that a particular output is required to be conformant to a conformance test class in a specific standard (say a normatively referenced XML schema), then the conformance class of that normative reference will be used to test that output. For example, if an OGC Web Feature Service (WFS) implementation instance specifies that its feature collection output is compliant to a particular profile of GML, then that profile of GML will be used to validate that output. This means that the service is indirectly tested using the GML standard. In other words, GML is an indirect dependency of the original service.

Requirements classes may be optional as a whole, but not piecemeal. This means that every implementation that passed a particular conformance class satisfies exactly the same requirements and passes exactly the same conformance tests. Differences between implementations will be determined by which conformance test classes are passed, not by a listing of which options within a class were tested. If a standard’s authors wish to make a particular requirement optional, Requirement 10: /req/core/no-optional-tests forces them to include it in a separate requirements class (and therefore in a separate conformance test class) which can be left untested.

The tracking of the parallelism between requirements and tests should be easy if the standards document is non-ambiguous. To ensure this, by utilizing the names of the two types of classes, the following requirement places a default mapping between the two.

Logically, a requirements class (set of requirements) and a conformance class (set of tests) are not comparable. This can be remedied by noting that both have a consistent relation to a set of requirements. A requirements class is a set of requirements. A conformance class tests a set of requirements. Therefore a requirements class corresponds precisely to a conformance class if they both are related (as described) to the same set of requirements.

The following states that requirements classes contain all requirements tested by a conformance test case

Unless a requirement is referenced in a conformance test and thus in a conformance class, it cannot be considered a requirement since no test has been defined for it.

The above requirement in conjunction with Requirement 10: /req/core/no-optional-tests means that all requirements in a conformant standard will be tested in some conformance class. In the best example, a requirement should be contained explicitly in one and only one requirements class and tested in one and only one conformance class. This is not really a requirement here, since a single requirement can be stated twice in different requirements classes with different standardization target types.

Normally, circular dependencies between implementation components are signs of a poor design, but they often cannot be avoided because of other considerations (code ownership for example).

This requirement is more important and may be more difficult than it seems. It states simply that conformance classes and their associated requirements classes can be put in a one-to-one correspondence to a fully modular implementation of the complete standard (at least against a single standardization target). Implementors who wish to sacrifice modularity for some other benefit can still do what they want. The requirement here only states that if the software requirements classes are properly separated, they can be implemented in a plug and play fashion.

This means, for example, that a UML classifier cannot be redefined in a new extension. If a new version of the classifier is needed it has to be a valid subtype of the original.

In terms of generalization, subclassing, extension and restriction (into a new class or type) are all acceptable, redefinition (of an old class or type) is not.

Clause 8.3 makes suggestions as to how to organize the conformance classes and normative clauses in parallel to make this requirement easier to verify.

Most standards include examples, which are useful for illustrative or pedagogical purposes. However, it is not possible to write a standard “by example” that supports conformance testing. Examples are therefore non-normative, by definition.

8.6.  There is a Defined Core

The following requirements define the content of the core.

The following states that any recommendations applicable to the entire standard are in the core document.

The following states that all non-core requirements classes have a standardization target type that is a sub-type of the core.

The following recommendation is guidance to the group developing a standard to keep the core as simple as possible.

The following enables the development and documentation of anstract standards. Examples of such standards are the OGC Abstract Specification. Typically, an abstract standard cannot be directly implemented.

The following enables the ability of the standard being developed and then implemented to reference, as normative, conformance classes from another standard. An example in the OGC would be OGC API — Records Standard core referencing conformance classes defined in the OGC API — Common Standard. By definition these externally defined conformance classes need to be passed in order to claim compliance.

Since the core requirements class is contained (as a direct dependency) in each other requirements class with a similar standardization target type, the general recommendations are thus universal to all requirements classes.

8.7.  Extensions are requirements classes

A common mechanism to extend the functionality of a standard is to define extensions, which may be either local or encompass other standards.

Standards should use extensions as required and feasible, but should never hinder them.

Since software is evolutionary at its best, it would not be wise to restrict that evolutionary tendency by restricting the specification of extensions. A good standard will thus list the things a standardization target has to do, but will never list things that a standardization target might want to do above and beyond the current design requirements.

The above requirement should not be interpreted as a restriction on quality control. Any efforts by a standard to enforce a level of quality on its standardization targets, when well and properly formed, do not interfere with the proper extension of those targets. So, the standard may require its standardization targets to behave in a certain manner when presented with a logical inconsistency, but that inconsistency must be fundamental to the internal logic of the model, and not a possible extension. Thus, a standard may require a standardization target to accept GML as a feature specification language, but cannot require a standardization target to not accept an alternative, such as KML, or GeoJSON, as long at that alternative can carry viable information consistent with the fundamental intent of the standard.

8.8.  Optional requirements are organized as optional requirements classes

A standard and implementations of that standard are restricted by this requirement.

Requirements of the form “if the implementation does this, it must do it this way” are considered to be options and should be in a separate requirements class.

9.1.  Semantics

The previous section defines requirements for conformance to the ModSpec core requirements. However, testing for that conformance may depend on how the various forms and parts of a conformant standard are viewed. Additional Parts to the ModSpec Standard specify how those views are to be defined. Standards that take an alternative mechanism to the ones defined in the additional Parts must be tested solely on the structure of their conformance test suite until such times as an extension to the ModSpec is defined for that alternate mechanism.

Standards are often structured and documented using some form of modeling language, or implementation paradigm. Additional Parts to the ModSpec define a mechanism to map parts of the model (language, schema, etc.) to the

As suggested in Clause Requirement 23: /req/core/req-class-not-core-stt-subtype-of-core, the structure of the normative clauses in a standard should parallel the structure of the conformance test classes in that standard. The structure of the normative clauses in a well written standard will follow the structure of its model. This means that all three are parallel.

9.2.  A Note on Data Models

If a data model is to be used to define the parameters of operational interfaces, then that model should belong in the core since it can be considered as part of a common reference model and vocabulary.

If a data model is to be used to create “data transfer” elements, the issue is more complex. In the use of parameter names and types in the operational model above, the definition of a common vocabulary in the core is justifiable. In the case where data transfer elements are being defined, it may be that some types and elements are a defining separator between conformance classes and have to exist independently of such data elements defined for non-dependent classes. For these reasons, care should be taken in creating separable data transfer schemas across requirements. Dependencies in the schemas will have to parallel the dependencies in the requirements classes. The mechanism for enforcing this is dependent on the schema language.