From 65e83ce7803fc850ddb54e939b1bad17ec0953dc Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Tue, 26 Nov 2024 12:49:33 -0500 Subject: [PATCH] Address various review comments. --- .../sections/clause_8_ogc-process-description.adoc | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/core/sections/clause_8_ogc-process-description.adoc b/core/sections/clause_8_ogc-process-description.adoc index 88fb96c3..266f14cd 100644 --- a/core/sections/clause_8_ogc-process-description.adoc +++ b/core/sections/clause_8_ogc-process-description.adoc @@ -161,21 +161,23 @@ The following JSON Schema fragment illustrates the use of the `format` key to in One common input type that a process might accept is a https://docs.ogc.org/is/17-069r4/17-069r4.html#_collection_[feature collection] indicating that the process will somehow operate over the items of the collection. This implies that the process will have certain expections about the structure of the collection with regard to which properties the collection contains, their types, etc. In order to properly handle any arbitrary input collection a process would need to inspect the structure of the collection to ensure that all the expected properties are present with the expected types, etc. To alleviate the server from having to perform such a tedious, and perhaps computationally expensive, schema validation step this Standard introduces the concept of the _Data Class_ via the `dataClasses` parameter. -The value of the `dataClasses` parameter is an array of URIs. Each URI identifies a predefined set of properties or a sub-schema. Two data resources tagged with the same data class URI value can be assumed to each contain all the properties defined by the data class. This equivalence allows a server to quickly validate that an input data resource meets the server's expections in terms of the properties available for processing, their types, etc. simply by comparing data class URI values. If the data class URI of the input data resource matches one of the data class URIs specified in the description of the process input (via the `dataClasses` parameter) then the server can be assured that the process can operate on that data resource. +NOTE: In this context, _type_ can refer the schema type of the property (e.g. integer, string, object, etc.) as well, in the case of geometric properties, as the geometry type (e.g. point, linestring, polygon, etc.). + +The value of the `dataClasses` parameter is an array of URIs. Each URI identifies a predefined set of properties or a sub-schema, with particular semantics. Two data resources tagged with the same data class URI value can be assumed to each contain all the properties defined by the data class. This equivalence allows a server to quickly validate that an input data resource meets the server's expections in terms of the properties available for processing, their types, etc. simply by comparing data class URI values. If the data class URI of the input data resource matches at least one of the data class URIs specified in the description of the process input (via the `dataClasses` parameter) then the server can assume that the process can operate on that data resource. + +NOTE: Care should be take when tagging data resources with a data class URI. Its not only the schemas that need to match but also the semantics need to be consistent. Consider two data resources that both contain fields `a` and `b` with the same data types but differ in, for example, units of measure. In this case, these two data resources should not be tagged with the same data class URI. The `dataClasses` parameter is an array allowing process inputs to be described that can handle a variety of data classes. As long as the data class URI associated with an input data resource matches at least one of the data class URIs listed in the `dataClasses` array the server can assume that the process can operate on that input data process. -This clause started by introducing the concept of the _Data Class_ in relation to a https://docs.ogc.org/is/17-069r4/17-069r4.html#_collection_[feature collection] but the concept is a general one applying to feature collections, coverages, styles, etc. For example, a specific data class might be defined to include a geometry property _fenceLine_ of type _polygon_. Thus, any input feature collection tagged with this data class's URI can be expected to include a _fenceLine_ property and its type can be assumed to be _polygon_. Similarly, a data class could be defined that identifies a set of bands in a coverage, say R, G, B and NIR. Any coverages tagged with this data class's URI can thus be assumed to contain these bands. +This clause started by introducing the concept of the _Data Class_ in relation to a https://docs.ogc.org/is/17-069r4/17-069r4.html#_collection_[feature collection] but the concept is a general one applying to any number of data resources shuch as feature collections, coverages, styles, etc. For example, a specific data class might be defined to include a geometry property _fenceLine_ of type _polygon_. Thus, any input feature collection tagged with this data class's URI can be expected to include a _fenceLine_ property and its type can be assumed to be _polygon_. Similarly, a data class could be defined that identifies a set of bands in a coverage, say R, G, B and NIR. Any coverages tagged with this data class's URI can thus be assumed to contain these bands. The _Data Class_ concept is also independent of the particular encoding used for the data resource. So, applying data class validation applies equally to feature collections encoded as GeoJSON documents as it does to feature collections encodes as SHAPE files. Finally, the _Data Class_ concept is independent of whether data resource values are passed to a process by-value or by-reference. In either case the server goes through the same procedure (i.e. comparing data class URIs) to determine whether a specific input value is suitable for processing as per the process description. [NOTE] ==== -. As defined in <> an input value can be passed to a process by value or by reference. Whether an input value is passed by-value or by-reference is orthogonal to the concept of the _Data Class_. In either case the server goes through the same procedure (i.e. comparing data class URIs) to determine whether a specific input value is suitable for processing as per the process description. - . A data resource tagged with a specific data class will contain all the properties defined for that class but may also contain additional properties that are not members of the class. A process expecting an input value of a particular data class value would simply ignore these extraneous properties. -. A data resource can be tagged with more that one data class URI. +. A data resource can be tagged with more than one data class URI. -. In order for the _Data Class_ concept to be most effective a registry aking to that found at https://schema.org[Schema.org] would need to be created and maintained. The OGC definition server is likely the best place to define and manage _Data Class_ URIs. +. In order for the _Data Class_ concept to be most effective a registry akin to that found at https://schema.org[Schema.org] would need to be created and maintained. The OGC definition server is likely the best place to define and manage _Data Class_ URIs. ==== ==== Cardinality