Towards a TC211 good practice on document style

[PeterParslow]

PMG would like to know from AHG Automated Documentation whether the 'style' for requirements proposed in this draft is achievable automatically.

If not, could this AHG suggest changes to the document, preferably ahead of it being presented to PMG in December 2021?

Thanks
Towards a TC211 good practice on document style.docx

@jetgeo

[jetgeo]

Thanks, @PeterParslow
To AHG members: This is the same document as sent out through ISO/Documents as N17, for discussion in the meeting tomorrow.

[jetgeo]

Some comments from Reese Plews (@ReesePlews )
Comments on AHG5 N17Reese Plews 2021.docx
e

[jetgeo]

@PeterParslow : See https://github.com/ISO-TC211/AutomatedDocumentation/wiki/Meeting-%239-2021-10-28#towards-a-tc211-good-practice-on-document-style-9

[PeterParslow]

Thanks.

"URIs should be resolvable URLs.
URIs should lead to an address where the requirement is described. For example, for automated conformance testing: An error message could link to the requirement for further explanation."

Basically, this is impossible at present for ISO to allow. You'll see that the Maintenance Agency ToR has deliberately not included your/Ron's suggestion of this, because ISO said 'no'. I did wonder whether all the requirements URIs could lead to a simple statement e.g. "this URI represents a requirement in ....".

Agneta, Mats, and I consider that we should not put the whole 'maintenance of resources' at risk by continuing (for now) to push for ISO to publish the requirements from their document on the web.

If we put that idea on hold for now, would AHG8 feel the same about: "URIs should be complete, not fragments", given that routinely leads to ISO/CS automatically converting them to links?

[ronaldtse]

@PeterParslow I'm fine with the change. However:

Basically, this is impossible at present for ISO to allow.

We can provide informative content, e.g. guidance, at the URL for a particular requirement that is not in the standard.

There is always the alternative of a URN, if URIs are too confusingly similar to URLs. ISO does provide a URN scheme in RFC 5141 that we could use (https://datatracker.ietf.org/doc/html/rfc5141).

The pattern for TC specified resources look like this:

urn:iso:std:iso:{std-number}:tech:{anything}

So for requirements we could do, e.g.

urn:iso:std:iso:19xxx:tech:req:content/specification-language

In this case we can have a resolver at standards.isotc211.org to resolve those URNs, e.g. https://standards.isotc211.org/req/urn:iso:std:iso:19xxx:tech:req:content/specification-language

[jetgeo]

I would say that AHG 8 still have the same opinion. So, ideally:

• URIs should be complete, not fragments.
• URIs should be resolvable URLs.
• URIs should lead to an address where the requirement is described.

However, we also need to be pragamtic and strive for a solution. Therefore, if we need to accept fragments, we'll do that.
But, perhaps: could the full URLs still be resolvable, even though not shown in the documents, and lead to somthing like what's on OGC's site for ISO 19170: http://defs.opengis.net/vocprez/object?uri=http://www.opengis.net/def/DGGS/2.0/req/cc/zone/geometry ?
Besides, can we get acceptance for the core URI for a specification to be resolvable?

[ronaldtse]

1. Fragments are not ideal because it does not have the chance to be resolvable to a resource in the future. By definition in the RFC, a fragment is "not resolvable", only the base resource is (a fragment is to be interpreted within media type of the base resource).
2. I have to say that http://defs.opengis.net/vocprez/object?uri=http://www.opengis.net/def/DGGS/2.0/req/cc/zone/geometry is intensely confusing.
3. Agree that the core URI for a specification should be resolvable.

[dr-shorthair]

I have to say that http://defs.opengis.net/vocprez/object?uri=http://www.opengis.net/def/DGGS/2.0/req/cc/zone/geometry is intensely confusing.

Why? it is a common URL pattern seen in many services.

[ronaldtse]

It is certainly a URL pattern seen in certain communities. I'm just not sure if it is "common" in most web services.

It's confusing because it contains more than one instance of http:// which is a protocol specifier (HTTP). The first http:// is the protocol identifier (URL component), the second http:// is an identifier namespace (URI component).

[dr-shorthair]

Indeed - it is a common pattern to support resolution of persistent URIs.

The first http:// specifies the protocol for the hosting service.
The second http:// is part of the persistent URI for the item.
You can read this as 'what http://defs.opengis.net/vocprez/object knows about the resource http://www.opengis.net/def/DGGS/2.0/req/cc/zone/geometry' .
That's why I called it a URL pattern (it is a locator).

If this hosting service is currently the 'preferred' source of definitions denoted by URIs in the namespace http://www.opengis.net/def/ etc, then the host at http://www.opengis.net should be configured to redirect requests over to that hosting service.
If the hosting service changes, then the redirect can be rewired without changing the persistent URI of the resource.

[dr-shorthair]

Also: the ? is the separator for a query string, # is the separator for a fragment. A query string is passed through by http.

[PeterParslow]

I agree that AHG 8's view would be the ideal result.

But regarding text to put in a good practice, it needs to be text that will work now - i.e. ISO will be willing to publish documents that are written like that.

• We could go for complete URIs for each statement, and just work harder on getting ISO/CS's process not to convert them to links.

• Is it workable (in our current system) to arrange that all the normative statement URIs "in" a particular standard dereference to the same place, which could contain a little general information - perhaps being a link to the document as it appears on the OBP (once published). Or a general statement like "requirement X of ISO 19xxx:YYYY, which is viewable at " (or enquiry draft link, earlier in the process). I can't see ISO objecting to that.

• the OGC example you give is an odd one. ISO 19170-1 / OGC DGGS claims it as a Requirement identifier, but when you dereference it, their server identifies it as a concept & gives no information about what the requirement actually is. If you/we/AHG 8/HMMG think that would be useful in some way, I guess we could get Mats to ask.

• I assume "core URI" is what I talk about as "the root" e.g. the https://standards.isotc211.org/19131/-/2 part of https://standards.isotc211.org/19131/-/2/req/content/specification-language etc. I would hope that dereferencing this is OK (it is a slightly more generalised version of what I've suggested above). We should be able to set all of them up, perhaps redirecting/linking to the document on the OBP?

[jetgeo]

My suggestion for a good (not best :)) practice would be:

• Each document shall contain a core URI to be used for the modular specification.
• The core URI for each document shall be resolvable, leading to a page that simply contains a list of requirements (only identifier and name) for this document, but no further information
• URIs for requirements shall be written as fragments and not formatted as hyperlinks
• Each identified requirement shall have one specified requirement. Several parts can be handled as linked requirements.

Would that work?

[ronaldtse]

URIs for requirements shall be written as fragments and not formatted as hyperlinks

I think we should keep the identification of requirements as proper paths (not fragments). To prevent them being marked as URLs, we can keep the base identifier (https://standards.isotc211.org/19131/-/2) in some place, and all subsequent IDs for requirements use a relative path (/req/content/specification-language). This is how it's done in OGC too.

e.g.

[jetgeo]

@ronaldtse : I'm sorry if I misunderstand, but isn't the example you show here exactly the kind of fragment we're talking about? Keep the core URI in one place, and use only the remaining part for requirement IDs?

[PeterParslow]

We're only creating 'good practice' guidance. I think it's sensible that we record somewhere (AHG 8 report?) what we would prefer.

A list question: what do you see as the "name" of a requirement?

[PeterParslow]

I was going from the link you posted five days ago (https://github.com/ISO-TC211/AutomatedDocumentation/wiki/Meeting-%239-2021-10-28#towards-a-tc211-good-practice-on-document-style-9), not the rest of the meeting record.

I do see that from the AHG 8 perspective, the numbers are less important. But I think from the PMG perspective, they are important - perhaps equally important - because they are much more human friendly, whilst the URIs serve the purpose well in machine readable contexts. Just imaging speaking in a meeting / call, and needing to say "Requirement h t t p "colon slash slash" .....", rather than "Requirement 21 (of ISO 19xxx)"!

Should we consider the point about modelling the requirements in the good practice now? Or should that wait a bit, until the AHG 8 report has been received/discussed/put into practice?

[jetgeo]

I would prefer that we can finalize the report from AHG 5 first. I see what you mean by the importance of the number for human readability.

[PeterParslow]

I did of course mean AHG 5 in my last few comments ("my" AHG 8 on smart cities isn't relevant to this discussion!)

[ronaldtse]

But I think from the PMG perspective [...] Just imaging speaking in a meeting / call, and needing to say "Requirement h t t p "colon slash slash" .....", rather than "Requirement 21 (of ISO 19xxx)"!

I think the bare minimum to identify a requirement is having:

• a document identifier (which includes versioning) (e.g. ISO 19xxx-zz:yyyy)
• a requirement identifier within that document (e.g. multi-curve)

The "h t t p" part is not technically necessary to be spelled out in communication...?

The sequential number reference to a requirement should really be made as (un-)important as Figures and Tables. These are all local element references of which importance is limited to within the context of the document.

[PeterParslow]

So, if someone can guarantee unique short names for requirements within each document, then I can see they could work as well as numbers. "Requirement multi-curve in ISO 19xx-zz:yyyy". For most in speech there would be a temptation to make it sound more natural, in English "The multi-curve requirement in ISO 19xx-zz:yyy" - with the consequent problem that it isn't then obvious that the name is a name, rather than just a word.

Yes, spelling out "http://" wasn't serious - the issue is ease of verbal transmission.

[PeterParslow]

My "confusion" with http://www.opengis.net/def/DGGS/2.0/req/cc/zone/geometry is that the thing it resolves to is a concept, not a requirement, but DGGS uses it as a requirement identifier.

A clearer example is http://www.opengis.net/spec/ogcapi-features-2/1.0/req/crs. OGC redirects this to http://docs.ogc.org/is/18-058/18-058.html#rc_crs, which does resolve to quite bit of description - because OGC are funded to publish the text, whilst ISO are not & have to get their income by charging for it.

So OGC handles this by redirecting the requirement identifier to the document fragment that contains the text of the requirement. Could we in the ISO context redirect them all to the document description?