OGC document identifier and its elements

[ronaldtse]

OGC documents are typically given a "document identifier" for unique identification of a document.

So far, they are of the pattern: OGC {2-digits}-{3-digits} (first edition) or OGC {2-digits}-{3-digits}r{edition number}.

These elements are not considered part of the identifier:

• Version
• Document type
• Document stage

Example:

1. "10-129r1" represents "OGC® Geography Markup Language (GML) - Extended schemas and encoding rules version 3.3" (which is an IS)
2. "07-036r1" represents "OpenGIS Geography Markup Language (GML) Encoding Standard - with corrigendum version 3.2.2". (IS)
3. "03-105r1" represents "OpenGIS Geography Markup Language (GML) Encoding Specification version 3.1.1" (D-BP)

We would like to confirm the following:

• If the document stage is changed, will the identifier change? e.g. if Example 3 advanced to BP, will the version number or document identifier change? Or are these elements all independent?
• In ISO the document identifier includes representation of stage, e.g. "ISO/DIS XXXXX", "ISO/WD XXXXX". Does OGC do something like this?
• In ISO, the document identifier includes edition year, e.g. "ISO XXXX:2019". Does OGC do something like this?
• When does a document identifier change from say "17-069" to "17-069r3"? How is it decided that "17-069" uses a "r3" suffix instead of a completely new reference number? Does the "r3" suffix indicate a change in version number?

As you can see I'm confused 😉 We can certainly use a "defined" schema for the document identifier...

Would @ogcscotts @gbuehler @ghobona shed some light on this? Thanks!

(Originally posted in #81)

[ogcscotts]

@ronaldtse This one is really confusing and means we may need to have additional identifying information. The "r" only updates if the content in the document changes (excluding minor editorial changes). So a document could go through all stages without ever updating the "r."

The general practice is to use the same document root for all minor versions and corrigenda. A major version requires a new document number. Not everyone has perfectly followed this practice in the past, but we are working to formalize this convention.

[ronaldtse]

@ogcscotts got it. So the {2-digits}-{3-digits} or {2-digits}-{3-digits}r{edition} number is like the ISO "project number" as it doesn't change during stage procession or minor updates.

Questions:

1. Is there a name for the {2-digits}-{3-digits} or {2-digits}-{3-digits}r{edition} pattern? If not, can we come up with a name, e.g. "document number"? (and what do the 2-digit and 3-digits mean?)

2. Is there a name for the number behind r? Is it the "edition number"?

3. Will OGC want to allow someone to cite an OGC document:

   • at a particular minor version of the document? e.g. "OGC 07-036r1 3.2.2" vs "OGC 07-036r1 3.2.3"
   • of a particular document type? e.g. "OGC BP 03-105r1" (BP) vs "OGC 10-129r1" (IS)?
   • at a particular document stage? e.g. "OGC/WD 10-129r1"

Thanks!

[ogcscotts]

@ronaldtse

1. The number is called the "document number." The first two digits are the year, the last three are sequential in the order in which the documents were reserved for the year. We'll need to rethink in 2099!

2. the "r" standard for "revision"

3. We only cite by the document number as it is unique to a specific version of the document. When someone cites a document that is anywhere in the process prior to approval, they just add "draft" behind the document title.

[ronaldtse]

Thanks @ogcscotts! For 3, is it "OGC 03-105r1 (draft)" or "OGC 03-105r1 draft"?

[ronaldtse]

And within an OGC document, is citing another draft acceptable?

[ogcscotts]

Yes, it happens quite often (but not as a normative reference... even though that has happened)

[ronaldtse]

@ogcscotts two questions on drafts:

1. When we render a draft reference citation within document content, do we go by "OGC 03-105r1 (draft)" or "OGC 03-105r1 draft"?

2. In the Bibliography, does it get shown as something like this?

# STANDARD
[6]  Open Geospatial Consortium: OGC 11-145, Cyberarchitecture for Geosciences White Paper. Open Geospatial Consortium (2014).

# DRAFT
[6]  Open Geospatial Consortium: OGC 11-145 (Draft), Cyberarchitecture for Geosciences White Paper. Open Geospatial Consortium (2014).

[ogcscotts]

convention has been: "OGC 03-105r1 (draft)" and [6] Open Geospatial Consortium: OGC 11-145 (Draft), Cyberarchitecture for Geosciences White Paper. Open Geospatial Consortium (2014).

[ronaldtse]

Thanks @ogcscotts !

[ronaldtse]

We need to document publicly the following:

OGC documents are given a "document number" for unique identification of a document. They are of the following patterns:

• OGC {2-digit-year}-{3-digit-number} (first edition)
• OGC {2-digit-year}-{3-digit-number}r{revision number} (subsequent revisions).

Where:

• {2-digit-year}-{3-digit-number} is called the "document number root".
• The first two digits are the year.
• The last three digits are sequential in the order in which the documents were reserved for the year.

The "r" only updates if the content in the document changes (excluding minor editorial changes). So a document could go through all stages without ever updating the "r."

The same "document number root" is used for all minor versions and corrigenda.

A major version requires a new document number. (which likely has a different year)

[ronaldtse]

Closing in favor of #121.