Change User Guide -> Best Practices

Start a section on surveying other practices.
Delete a bunch of sections of particular use cases that we
are probably never going to populate.

22-053/22-053.adoc

@@ -1,4 +1,4 @@
-= User guide for OGC Points of Interest
+= Best Practices guide for OGC Points of Interest
 :doctype: user-guide
 :status: draft
 :committee: technical
@@ -25,26 +25,10 @@ include::sections/01-introduction.adoc[]
 include::sections/02-usage.adoc[]
 include::sections/03-scope.adoc[]
 include::sections/04-normative-references.adoc[]
-include::sections/05-nonstandard-attributes.adoc[]
-
-include::sections/06-choose-restaurant-use-case.adoc[]
-
-// include::sections/06-construction-site-use-case.adoc[]
-
-// include::sections/06-country-covid-requirements-use-case.adoc[]
-
-// include::sections/06-covid-testing-center-use-case.adoc[]
 
-// include::sections/06-ev-charging-stations-use-case.adoc[]
-
-// include::sections/06-indoor-navigation-use-case.adoc[]
-
-// include::sections/06-military-use-case.adoc[]
-
-// include::sections/06-houses-and-utility-poles-use-case.adoc[]
-
-// include::sections/06-package-dropoff-pickup-service-use-case.adoc[]
+include::sections/05-current-practices.adoc[]
+include::sections/05-nonstandard-attributes.adoc[]
 
-// include::sections/06-poi-publication-use-case.adoc[]
+include::sections/06-public-poi-interchange-use-case.adoc[]
+include::sections/06-poi-publication-use-case.adoc[]
 
-// include::sections/06-smart-tourism-use-case.adoc[]

22-053/sections/00-preface.adoc

@@ -6,5 +6,5 @@ POI-CM is an open conceptual data model for representing information about point
 
 The aim of developing the OGC POI conceptual model is to reach a common definition of the basic entities, attributes, and relations of "points of interest." In the broadest terms, a point of interest is a location about which information of general interest is available. A POI can be as simple as a set of coordinates and an identifier, or more complex such as a three-dimensional model of a building with names in various languages, information about open and closed hours, and a civic address.
 
-This Users Guide provides extended explanations and examples for the individual concepts that are defined in the POI Conceptual Model Standard. Both the Conceptual Model Standard and this Users Guide are mutually linked to facilitate navigation between corresponding sections in these documents.
+This Best Practices Guide provides extended explanations and examples for the individual concepts that are defined in the POI Conceptual Model Standard. Both the Conceptual Model Standard and this Users Guide are mutually linked to facilitate navigation between corresponding sections in these documents.
 

22-053/sections/01-introduction.adoc

@@ -7,7 +7,7 @@ POI data has traditionally been exchanged in proprietary formats by various tran
 
 POI-CM is a common semantic information model for the representation of POI objects that can be shared across many use cases. The ability for a POI using this conceptual model to be shared and reused is especially important with respect to the cost-effective sustainable maintenance of POI set models, allowing the possibility of selling the same data to customers from different application fields.
 
-POI-CM is an open conceptual data model for the storage and exchange of POI models. It is defined through a Unified Modeling Language (UML) object model. This UML model extends the ISO Technical Committee 211 (TC211) https://github.com/ISO-TC211/HMMG[conceptual model standards] for spatial and temporal data. Building on the ISO foundation assures that the features described in the POI Models share the same spatial-temporal universe as features described by related standards (e.g., <<citygml,CityGML..).
+POI-CM is an open conceptual data model for the storage and exchange of POI models. It is defined through a Unified Modeling Language (UML) object model. This UML model extends the ISO Technical Committee 211 (TC211) https://github.com/ISO-TC211/HMMG[conceptual model standards] for spatial and temporal data. Building on the ISO foundation assures that the features described in the POI Models share the same spatial-temporal universe as features described by related standards (e.g., <<citygml,CityGML>>, ...).
 
 A POI is not a dataset. Rather, it is a feature type that enhances an existing dataset of features. POI-CM builds on the ISO General Feature Model (<<iso19109,ISO 10109>>) and the ISO Geometry Model (<<iso19107,ISO 19107>>). To avoid reinventing things, POI-CM also borrows some classes from ISO Common Data Types (<<iso19103,ISO 19103>>) and <<citygml,OGC CityGML 3.0>>.
 

22-053/sections/02-usage.adoc

@@ -1,7 +1,7 @@
 [[ug_usage_section]]
 == How To Use This Resource
 
-The Users Guide to the POI Conceptual Model (POI-CM) Standard is not intended to be read from start to finish. Rather, it is a resource structured to provide quick answers to questions that an implementer may have about the POI-CM Standard. 
+The Best Practices Guide to the POI Conceptual Model (POI-CM) Standard is not intended to be read from start to finish. Rather, it is a resource structured to provide quick answers to questions that an implementer may have about the POI-CM Standard. 
 
 The POI-CM Standard includes hyperlinks that can be used to navigate directly to relevant sections of the User Guide. 
 

22-053/sections/03-scope.adoc

@@ -5,4 +5,4 @@ This document provides Engineering Guidance on the use of the POI Conceptual Mod
 
 The OGC POI Conceptual Model (POI-CM) Standard specifies the representation of POI models. The POI-CM is expected to be the basis for a number of future implementation standards in which subsets of the Conceptual Model can be implemented. These future standards will be published separately to enable consistent and efficient storage and exchange of data. 
 
-The POI Conceptual Model Standard was designed to be concise and easy to use. As a result, most non-normative content has been removed. The purpose of this Users Guide is to capture that non-normative content and make it easy to access when needed.
+The POI Conceptual Model Standard was designed to be concise and easy to use. As a result, most non-normative content has been removed. The purpose of this Best Practices Guide is to capture that non-normative content and make it easy to access when needed.

22-053/sections/05-current-practices.adoc

@@ -0,0 +1,62 @@
+
+[[ug_current_practices_section]]
+== Survey of Selected Current Practices
+
+Most usages of this POI Conceptual Model standard will need to add extra _attributes_ (named properties) in a *POI_Payload* object.
+There are a number of attributes that are likely to come up often. Among the most common are:
+
+* Internationalized names and addresses
+* Categories
+* Business Hours
+* Telephone Number
+
+Since there are extant standards and practices for representing these, this section will survey those.
+The next section will then recommend how to model these attributes in a *POI_Payload*.
+
+=== Some Common POI Information Practices and Standards ===
+
+Before discussing the individual attributes, here are some of the references consulted for this survey:
+
+Indoor Mapping Data Format (IMDF)::
+https://docs.ogc.org/cs/20-094/[IMDF] is an OGC Community Standard, originally developed by Apple, for indoor maps
+It can be used, for example, to map airports, malls, and train stations.
+The concept of an https://docs.ogc.org/cs/20-094/Occupant/[Occupant] is very close to that of a POI representing a business,
+and as a result, the modeling of various Occupant properties is directly relevant to this survey.
+
+OpenStreetMap::
+https://wiki.openstreetmap.org/wiki/Main_Page[OpenStreetMap] is a community-built map of the world.
+Some of its https://wiki.openstreetmap.org/wiki/Map_features[Primary Features] could be called POIs,
+and the https://wiki.openstreetmap.org/wiki/Tags[tags] of such features are similar to our attributes.
+
+Overture Maps::
+https://docs.overturemaps.org/schema/[Overture Maps] is developed by a foundation as a map built on open data.
+It has a schema for https://docs.overturemaps.org/schema/reference/places/place/[places] that are essentially POIs.
+
+CityGML::
+https://www.ogc.org/standard/citygml/[CityGML] is an OGC standard for 3D city models.
+It is mostly about the buildings and other city infrastructure, rather than the occupants of the buildings.
+However, it is useful to see how it models addresses.
+
+Google Hotels::
+Google provides an XML schema for uploading listings, and a public example of this is the
+https://developers.google.com/hotels/hotel-prices/dev-guide/hlf[Hotels listing] schema.
+Hotels are a subset of POIs but are otherwise very similar.
+
+Schema.org::
+https://schema.org/[Schema.org] is a set of recommended schema for modeling various things on the web.
+It specifies markup for various https://schema.org/Property[Properties], some of which are relevant to POIs.
+
+XML Schema::
+https://www.w3.org/TR/xmlschema11-2/[XML Schema Definition Language] models a number of primitive data types,
+some of which (language, dates and times) are relevant to this survey.
+
+=== Internationalized Names and Addresses ===
+
+
+=== Categories ===
+
+
+=== Business Hours ===
+
+
+=== Telephone Number ===

22-053/sections/05-nonstandard-attributes.adoc

@@ -2,17 +2,17 @@
 [[ug_nonstandard_attributes_section]]
 == Payload: Nonstandard Attributes
 
-An _attribute_ is a named property of a feature. While this POI Conceptual Model Standard specifies some standard attributes (e.g., lifetime attributes), most applications will need to define and use some attributes that are not normatively defined by the standard. The mechanism for including non-standard attributes in a POI is to use the *POI_Payload* property.
+An _attribute_ is a named property of a feature. While this POI Conceptual Model Standard specifies some standard attributes (e.g., lifetime attributes), most applications will need to define and use some attributes that are not normatively defined by the standard. The mechanism for including non-standard attributes in a POI is to use the *hasPayload* property, whose type is zero or more *POI_Payload* values.
 
 === Using POI_Payload
 
 A *POI_Payload* is only partially specified in this POI Conceptual Model Standard. These properties are specified:
 
-usesSchema:: The value identifies a _schema_ for the payload. How this identification is done and what the schema looks like depends on the implementation technology used. We'll see some examples below. The schema describes the _syntax_ for the other properties of the payload, and the value for identifying the schema is typically a _URI_.
+usesSchema:: The value identifies a _schema_ for the payload. How this identification is done and what the schema looks like depends on the implementation technology used. We'll see some examples below. The schema describes the _syntax_ for the other properties of the payload, and the value for identifying the schema is typically a _URI_. There can be more than one schema, but the intent is that these will represent the same conceptual model of a payload, perhaps for different implementation technologies.
 
 hasDefinition:: The value is a companion to the schema referenced by *usesSchema*, and it describes the _semantics_ of the various payload fields. Typically, this will be plain text descriptions of the properties, what standards they adhere to, etc.
 
-representsFoI:: This indicates the Feature of Interest that the payload is for. It is required.
+hasFeatureOfInterest:: This indicates the Feature of Interest that the payload is for. There can be zero or more of these.
 
 For example, suppose an application needed an attribute called *isPublic*, whose value is true or false depending on whether or not the POI is something the general public can visit. A particular POI could include a *hasPayload* association to a *POI_Payload* that looks like this in conceptual form:
 
@@ -89,35 +89,43 @@ The value of the *hasDefinition" property should reference a file that describes
 
 There are a number of attributes that commonly are needed in use cases for POIs yet are not standardized in the POI-CM. This section suggests a recommended schema for these common nonstandard attributes.
 
-This POI Conceptual Model Standard has an Informative Annex which contains several conceptual model fragments taken from other OGC Standards which may be useful and recommended for use in payloads when the corresponding concept needs modeling. Among the useful ones are:
-
-[none]
-* Date, Time, Decimal, Integer, Number, Real, Vector, CharacterString, URI, Boolean, DateTime, CI_Address, CI_Contact, CI_Date, CI_OnlineResource, CI_Organisation, CI_Telephone, MD_Identification, MD_Keywords
-
-The rest of this section recommends how to handle four common POI attribute: address, telephone number, opening hours, and category.
-
 ==== Address
 
 An address is a structured or semi-structured way of expressing where a place on earth can be found, usually referencing political areas, route (street) names, and numbers on routes. These are the things one uses to specify where mail is to be delivered, or packages are to be picked up. Special software called _geocoders_ can convert an address into (latitude, longitude) position on earth.
 
-There are many addressing systems in use in the world. A schema to represent them all precisely would be quite complicated.  The recommendation here is to use the *CI_Address* class from the Informative Annex:
+There are many addressing systems in use in the world. A schema to represent them all precisely would be quite complicated.  The recommendation here is to use a modification of *CI_Address* class from the ISO 19115 (Citation Information) standard.
+The modification is to allow cardinality of all the text strings to be more than 1 if desired: this allows for multiple languages to be used.
 
-.CI_Address Schema
+.Address Schema
 [source,JSON]
 ----
-    "CI_Address" {
-        "administrativeArea": "CharacterString" [0..1],
-        "city": "CharacterString" [0..1],
-        "country": "CharacterString" [0..1],
-        "deliveryPoint": "CharacterString" [0..1],
-        "electronicMailAddress": "CharacterString" [0..1],
-        "postalCode": "CharacterString" [0..1]
+    "Address" {
+        "administrativeArea": "CharacterString" [0..],
+        "city": "CharacterString" [0..],
+        "country": "CharacterString" [0..],
+        "deliveryPoint": "CharacterString" [0..],
+        "electronicMailAddress": "CharacterString" [0..],
+        "postalCode": "CharacterString" [0..]
         }
 ----
 
-where the *country*, *adminstrativeArea* (state or province), and *city* give a structuring of three of the political areas containing the POI, and the *postalCode* is the postal or zipcode that some countries use in addresses (varies by country). The *deliveryPoint* is an unstructured way of expressing the rest of the address. E.g., it might be "123 Main St., Unit 3" or "Market Square". The language of the address should be either a common language implicit in the entire dataset (e.g., English), or a language in use in the country in question.
+where the *country*, *adminstrativeArea* (state or province), and *city* give a structuring of three of the political areas containing the POI, and the *postalCode* is the postal or zipcode that some countries use in addresses (varies by country). The *deliveryPoint* is an unstructured way of expressing the rest of the address. E.g., it might be "123 Main St., Unit 3" or "Market Square". 
+If there are not multiple CharacterStrings for the properties, then the language of the address should be either a common language implicit in the entire dataset (e.g., English), or a language in use in the country in question.
+For international datasets, it is recommended that the language of each string in the address be annotated with its language, using the facilities available in the particular implementation technology used.
+
+For example, if the implementation technology is JSON, this could be the way to express the address of the Empire State Building in several languages:
+
+.Example Address Value
+[source,JSON]
+----
+    {
+      "administrativeArea": [
+         
+      ]
+    }
+----
 
-_TODO: check out ISO 19160:1 A conceptual model for addressing_
+// _TODO: check out ISO 19160:1 A conceptual model for addressing_
 
 ==== Telephone Number