Subject: [urn] gbs Name space identifier

From: Philip R Brenan <[email-masked]>
Date: Wed, 11 Sep 2019 11:06:25 +0100

Per: https://tools.ietf.org/html/rfc8141

Namespace ID:

   gbs

Registration Information:

   Version 1
   Date: 2019-09-10

Declared registrant of the namespace:

   Name:           Ryffine Inc.
   Address:        445 N Broadway, Denver, CO 80203
   Contact:        Philip R Brenan
   E-mail:         [email-masked]
   www:            http://www.ryffine.com

Purpose:

   To allow organizations to share content written to the Dita Standard:

http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html
   without the exponential duplication that occurs without name space
   standardization.

Syntax:

   urn: gbs : <T> : <G> : <B>

   where:

   <T> is a string of one or more characters drawn from: [a-zA-Z0-9_] which
   identifies the type of content from a list of types published by the
   registrant at https://metacpan.org/pod/Dita::GB::Standard::Types . The
user
   of this standard chooses the most appropriate type by inspection. The
number
   of types is expected to be very small but, never-the-less, greater than
one.

   <G> is a string of one or more characters: [a-zA-Z0-9_] chosen
   algorithmically depending on the value of the <T> component. The possible
   algorithms will be published on https://metacpan.org by the registrant.
The
   user is directed to the appropriate algorithm by a link published beside
the
   description of type <T> at:
   https://metacpan.org/pod/Dita::GB::Standard::Types

   <B> is the MD5 sum https://en.wikipedia.org/wiki/MD5 of the content being
   identified presented as a 32 character lowercase hexadecimal string drawn
   from: [a-z0-9]{32}

Assignment:

   Identifier uniqueness considerations:

       Uniqueness is guaranteed by the <B> component being an MD5 sum and is
       thus guaranteed to be identical for identical content and very
probably
       different for differing content.

   Identifier persistence considerations:

       Persistence is guaranteed by the immutability over time of the MD5
sum
       of the <B> component.

   Process of identifier assignment:

       <T> is chosen by the user of this standard by visual inspection of
the
       current possibilities published by the registrant on
       https://metacpan.org/pod/Dita::GB::Standard::Types .

       <G> is chosen algorithmically using the content as input to the open
       source code published on https://metacpan.org by the registrant
       appropriate to the chosen type <T>.

       <B> is chosen by computing the MD5 sum of the content.

       e.g.
urn:gbs:dita:Introduction_to_the_GB_Standard:dddb7e2c29d2c8b9d87187fdf52a2702

Resolution:

    Content cannot be directly located by this standard.

    Equivalence is determined by comparing the <G> components of the two
items
    to be compared.  If they are equal the two items are considered to be
equal.
    Otherwise they are considered to be unequal even if the underlying
content
    is in fact identical.

Security and Privacy

   The validity of the urn can be checked as follows:

   Check that the <T> component is on the published list of possibilities.

   Check that the <G> component is computed correctly when the algorithm
named
   by the <T> component is applied to the content.

   Check the the <B> component matches the MD5 sum of the content.

Interoperability

   No special considerations.

Additional Information

   Definition of the Gearhart-Brenan Standard as applied to DITA content at:

   https://metacpan.org/pod/Dita::GB::Standard

References:

   GB Standard types available:
https://metacpan.org/pod/Dita::GB::Standard::Types

   MD5 Sum: https://en.wikipedia.org/wiki/MD5

   Dita specification:
http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html

-- 

Philip R Brenan <https://opentokrtc.com/room/phil>

---

From: [email-masked] (Dale R. Worley)
Date: Wed, 11 Sep 2019 22:12:07 -0400

Certainly an interesing idea, but there are some things that need to be
clarified:

One thing you want to clarify is what sort of resources the URNs
specify.  From the way you write, I believe that they are intended to be
what are called BLOBs, finite sequences of octets, or files as a Unix
user thinks of them, with no metadata.  But that should be stated
explicitly.

>    registrant at https://metacpan.org/pod/Dita::GB::Standard::Types .

I attempted to obtain the list of valid types at the given URL, but was
unsuccessful.  That page seemed to be a very top-level discussion of
"The GB Standard".

>    algorithms will be published on https://metacpan.org by the registrant. The
>    user is directed to the appropriate algorithm by a link published beside the

As written, this provides no real constraint on the <G> value, other
than its character set, because there seems to be no constraint on the
algorithms involved.

I think the approach you want to take is to state that for each type <T>
there will be a published algorithm, and <G> has to conform to the
algorithm for <T>.

>        Persistence is guaranteed by the immutability over time of the MD5 sum
>        of the <B> component.

Because of <B>, there is a guarantee that if a URN refers to a resource
at a time, and at another time refers to a resource, then the two
resources are identical.  And that is the minimum needed for a URN
definition.

But there are no statements that types will not be removed from the list
of types, or that users might decide to use a different type for the
same resource, leaving two URNs referring to the same resource.
Similarly, what guarantees are there regarding the <G> algorithms over
time?

None of these questions are critical, but it would be much better if
you declared your intentions.

>     Equivalence is determined by comparing the <G> components of the two items
>     to be compared.  If they are equal the two items are considered to be equal.
>     Otherwise they are considered to be unequal even if the underlying content
>     is in fact identical.

If equivalence is determined solely by the <G> values, why are the <T>
and <B> values present in the URN?

>    Check that the <G> component is computed correctly when the algorithm named

That last item is ill-defined, as it requires one has the resource for
the URN, but there is no algorithm for constructing the resource from
the URN.

Dale

---

From: [email-masked]
Date: Tue, 24 Sep 2019 13:51:09 +0200

> unsuccessful.  That page seemed to be a very top-level discussion of

That URL gives me a 404...

Best,

Lars

---

From: "Hakala, Juha E" <[email-masked]>
Date: Wed, 25 Sep 2019 04:52:13 +0000

Hello, 

DITA is an OASIS standard which was first approved in 2005. GB standard for naming DITA topic files seems to be a recent extension to DITA version 1.3. in order to " enable global collaboration (especially within the meta::cpan platform) through uncoordinated content sharing". 

The scope of this proposal looks clear to me in general (if I have understood DITA correctly) and registering a URN namespace for this purpose is OK. 

Please add a list of types to the specification of DITA GB standard at https://metacpan.org/pod/Dita::GB::Standard, and specify how the list will be maintained.  

 As Dale writes below, the registration should provide more information about how <G> is constructed. A link to the appropriate algorithm is OK, but some background information about these algorithms is IMO required, so that the users will be well informed about how these URNs are constructed. 

Best regards, 

Juha Hakala 

-----Alkuperäinen viesti-----
Lähettäjä: urn <[email-masked]> Puolesta Dale R. Worley
Lähetetty: torstai 12. syyskuuta 2019 5.12
Vastaanottaja: Philip R Brenan <[email-masked]>
Kopio: [email-masked]
Aihe: Re: [urn] gbs Name space identifier

One thing you want to clarify is what sort of resources the URNs specify.  >From the way you write, I believe that they are intended to be what are called BLOBs, finite sequences of octets, or files as a Unix user thinks of them, with no metadata.  But that should be stated explicitly.

>    registrant at https://metacpan.org/pod/Dita::GB::Standard::Types .

I attempted to obtain the list of valid types at the given URL, but was unsuccessful.  That page seemed to be a very top-level discussion of "The GB Standard".

>    https://metacpan.org/pod/Dita::GB::Standard::Types

As written, this provides no real constraint on the <G> value, other than its character set, because there seems to be no constraint on the algorithms involved.

I think the approach you want to take is to state that for each type <T> there will be a published algorithm, and <G> has to conform to the algorithm for <T>.

>        Persistence is guaranteed by the immutability over time of the MD5 sum

Because of <B>, there is a guarantee that if a URN refers to a resource at a time, and at another time refers to a resource, then the two resources are identical.  And that is the minimum needed for a URN definition.

But there are no statements that types will not be removed from the list of types, or that users might decide to use a different type for the same resource, leaving two URNs referring to the same resource.
Similarly, what guarantees are there regarding the <G> algorithms over time?

None of these questions are critical, but it would be much better if you declared your intentions.

>     Otherwise they are considered to be unequal even if the underlying content

If equivalence is determined solely by the <G> values, why are the <T> and <B> values present in the URN?

>    Check the the <B> component matches the MD5 sum of the content.

That last item is ill-defined, as it requires one has the resource for the URN, but there is no algorithm for constructing the resource from the URN.

Dale

_______________________________________________
urn mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/urn

---

From: Philip R Brenan <[email-masked]>
Date: Wed, 25 Sep 2019 19:46:25 +0100

I have removed the link in question as the explanation of the derivation of
the *<T>* component was deemed unsatisfactory.  Here is what I was trying
to achieve:

It is anticipated that the GB Standard represented by the *urn:* *gbs* name
space could be usefully applied to a number of different document types,
such as Dita, DocBook, Word, Html etc.  The <T> component is designed to
separate these various name spaces. At the moment the only <T> in active
use  is *dita* for Dita documents.  Within the Dita space the algorithm for
computing the *<G>* component is included in:

as gbStandardFileName().

The computation of the <G> component is performed by examining the text
between which ever of the following *xml* tags exist in a particular Dita
document in the order in which they appear:

 title mainbooktitle booktitlealt

The text between these tags is used to form the <G> component after
converting runs of all characters other than a-zA-Z0-9 to single
underscores. This method was chosen because it produces the most readable
names that are closely aligned with what authors expect to see as a file
name.

The purpose of the GB Standard is to control the explosion of duplicate
Dita topics that tends to occur as documents evolve.  Typically when a new
product is documented, the author takes the existing set of linked topic
files comprising the documentation of the product, duplicates all of these
files to preserve the linkage structure,  then makes a small number of
changes to a few of the duplicated files, leaving the bulk of the topic
files unchanged.  It is difficult to reuse the original topic files in situ
because of the need to maintain the links between them.

The GB Standard seeks to reduce this exponential growth of topic files by
giving each topic a unique deterministic name so that links between topics
can be expressed in a way that endures as the topic files are copied over
time.

As proposed, the GB Standard allows a server to quickly determine whether
it has a copy of a file by computing the GB Standard name of an incoming
file and comparing it to the names of all such files stored locally.   If
the name already exists then that file is reused, if the name does not
exist on the server then the server adds the incoming file to its list of
files available.

It is not the current intention to use the GB Standard name to locate off
site copies of a file - as things stand this could only be achieved by
querying each server known to store files in this manner in turn.  Please
tell me whether it is necessary for a *urn* to be able to uniquely locate
files as well as classify them?  If it is a requirement that a *urn *can be
used to locate a topic file anywhere in the world then I need to rethink
this aspect of the GB Standard and update my application for the *gbs*
namespace accordingly.  If location is not necessarily required then the
description of the computation of the <G> component and adequate
documentation of the standard names in the <T> would be seem to be the
elements that need work to progress this application further?

-- 
Thanks,

Phil <https://opentokrtc.com/room/phil>

---

From: "Hakala, Juha E" <[email-masked]>
Date: Thu, 26 Sep 2019 04:15:51 +0000

Hello Philip,

as regards this:

Please tell me whether it is necessary for a urn to be able to uniquely locate files as well as classify them?

URNs don’t have to be provide resolution services, so the resolver (if any) does not need to know the location or locations of the identified resource, or to link the URN to these URL / URLs. You may want to mention in the urn:gbs namespace registration request that no resolution services are anticipated.

It might be useful to add to the request the sentences below on document types and <T> values, with a note that for the time being only Dita documents are within scope. And some background information about Dita might be useful as well, for those who are not familiar with it.

Best regards,

Juha

Lähettäjä: urn <[email-masked]> Puolesta Philip R Brenan
Lähetetty: keskiviikko 25. syyskuuta 2019 21.46
Vastaanottaja: [email-masked]
Kopio: [email-masked]; Dale R. Worley <[email-masked]>
Aihe: Re: [urn] gbs Name space identifier

I have removed the link in question as the explanation of the derivation of the <T> component was deemed unsatisfactory.  Here is what I was trying to achieve:

It is anticipated that the GB Standard represented by the urn: gbs name space could be usefully applied to a number of different document types, such as Dita, DocBook, Word, Html etc.  The <T> component is designed to separate these various name spaces. At the moment the only <T> in active use  is dita for Dita documents.  Within the Dita space the algorithm for computing the <G> component is included in:

as gbStandardFileName().

The computation of the <G> component is performed by examining the text between which ever of the following xml tags exist in a particular Dita document in the order in which they appear:

The text between these tags is used to form the <G> component after converting runs of all characters other than a-zA-Z0-9 to single underscores. This method was chosen because it produces the most readable names that are closely aligned with what authors expect to see as a file name.

The purpose of the GB Standard is to control the explosion of duplicate Dita topics that tends to occur as documents evolve.  Typically when a new product is documented, the author takes the existing set of linked topic files comprising the documentation of the product, duplicates all of these files to preserve the linkage structure,  then makes a small number of changes to a few of the duplicated files, leaving the bulk of the topic files unchanged.  It is difficult to reuse the original topic files in situ because of the need to maintain the links between them.

The GB Standard seeks to reduce this exponential growth of topic files by giving each topic a unique deterministic name so that links between topics can be expressed in a way that endures as the topic files are copied over time.

As proposed, the GB Standard allows a server to quickly determine whether it has a copy of a file by computing the GB Standard name of an incoming file and comparing it to the names of all such files stored locally.   If the name already exists then that file is reused, if the name does not exist on the server then the server adds the incoming file to its list of files available.

It is not the current intention to use the GB Standard name to locate off site copies of a file - as things stand this could only be achieved by querying each server known to store files in this manner in turn.  Please tell me whether it is necessary for a urn to be able to uniquely locate files as well as classify them?  If it is a requirement that a urn can be used to locate a topic file anywhere in the world then I need to rethink this aspect of the GB Standard and update my application for the gbs namespace accordingly.  If location is not necessarily required then the description of the computation of the <G> component and adequate documentation of the standard names in the <T> would be seem to be the elements that need work to progress this application further?

Best,

Lars

--
Thanks,
Phil<https://opentokrtc.com/room/phil>
Philip R Brenan<https://opentokrtc.com/room/phil>

---

From: Philip R Brenan <[email-masked]>
Date: Sun, 29 Sep 2019 14:57:25 +0100

Hi *Juha*:

Thank you for your helpful comments.

I have updated this document based on the email discussion as follows:

1 - Clarified that the principle purpose of the URN being applied for is for
naming topics rather than locating them.

2 - Specified that currently there is only one <T> type active, namely
"dita".

3 - Specified the computation of the <G> component in this document rather
than
by reference elsewhere.

4 - Expanded the discussion of the purpose of the URN.

5 - Expanded the discussion on naming versus location and why naming is so
useful in this context.

6 - Expanded the discussion of inter-operability.

Please let me know which areas of this application might require further
elaboration?

Namespace ID:

   gbs

   Version: 1
   Date:    2019-09-27

   Name:    Ryffine Inc.

Purpose:

   To allow organizations to share content written in Xml to the Dita
Standard:

http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html
   without the exponential duplication that occurs without the name space
   standardization provided by a URN.

   Dita is a technical documentation standard promulgated by OASIS: a
nonprofit
   consortium that drives the development, convergence and adoption of open
   standards for the global information society as noted at
   https://www.oasis-open.org/org

   A major goal of Dita is to enable authors to build documents from small
   reusable components called topics and then to share and reuse these
topics
   via collections to enable other documents to be be built more rapidly.

   As a consequence of the current addressing mechanism used to link Dita
   topics together within a document the number of such topics in existence
   tends to grow exponentially over time as documents evolve.  Typically
when a
   new version of a product is documented the author takes the existing set
of
   linked topic files comprising the documentation of the product,
duplicates
   all of these files to preserve the complex linkage structure between
these
   topics, then makes a small number of changes to a few of the duplicated
   files, leaving the bulk of the topic files unchanged.  At the moment it
is
   difficult to reuse the original topic files in situ because of the need
to
   maintain the links between them.

   The GB Standard as currently implemented at:

   hhttps://metacpan.org/pod/Dita::GB::Standard

   seeks to reduce this exponential growth of topic files by giving each
topic
   a unique deterministic name so that links between topics can be
expressed in
   a way that endures as the topic files are copied over time.

   As proposed, the GB Standard allows a collection of Dita topics to
quickly
   determine whether it already has a copy of an incoming topic by computing
   the GB Standard name of the topic and comparing it to the names of all
such
   topics already collected locally ready for publication. If the name
already
   exists then the incoming topic is discarded and the existing topic is
   reused, if the name does not exist in the collection then the collection
   adds the incoming topic to its list of topics available for publication.

   At the same time, the GB standard provides a human readable name for each
   topic which assists authors in selecting topics from each collection for
   reuse.

   The GB standard has been used by the applicant since 2016 to successfully
   build and maintain several large collections of topics.

   The purpose of this application then is to formalize the GB Standard
naming
   convention as a globally recognized URN to enable standardized topic
naming
   among organizations collaborating on the production of collections of
   technical documentation using Dita.  The proposed URN will not, as it
   stands, provide immediate global location of topics so named, instead, it
   provides a standardized method of querying one or more collections of
such
   topics by both humans and computers in an efficient manner.

Syntax:

   where:

   <T> is a string of one or more characters drawn from: [a-zA-Z0-9_] which
   identifies the type of content being classified. At this point in time
only
   one such type is in active use: the "dita" type. It is possible that
further
   types might be required in the future, if so, this document will be
updated
   to reflect these new types.

   <G> is a string of 1 to 64 characters drawn from: [a-zA-Z0-9_].  When <T>
   has the value: "dita" (currently the only permissible value),  <G> is
   computed by concatenating the text between which ever of the following
Xml
   tags exist in a the Dita topic in the order in which they appear in that
   topic:

     <title>  <mainbooktitle>  <booktitlealt>

   The text between these tags is used to form the <G> component after
   converting runs of all characters other than a-zA-Z0-9 to single
underscores
   and truncating after character 64 if the resulting string is longer than
64
   characters in length. This method was chosen based on operational
experience
   as it produces readable names that are closely aligned with what authors
   expect to see as a topic name.

   <B> is the MD5 sum https://en.wikipedia.org/wiki/MD5 of the content being
   identified presented as a 32 character lowercase hexadecimal string drawn
   from: [a-z0-9]{32} . Presenting the MD5 sum in lowercase, last and
therefore
   to the right has the beneficial side effect of allowing authors to
visually
   ignore it and concentrate instead on the <G> component in the majority of
   cases where the <G> component happens to be (almost) unique.  This
   arrangement makes the GB Standard name useful to both humans and
computers.

Assignment:

       <T> is currently set to "dita".

       <G> is chosen algorithmically depending on the value of <T> using the
       topic as input as described above.

  For example:

Resolution:

    Content cannot be directly located by this standard.  However, URN's are
    not necessarily required to provide locations services initially:
providing
    a globally unique name is valuable in its own right because it
encourages
    the development of, and convergence on, a small number of large, shared,
    inter-operable, global collections of topics within each of which the
    uniqueness of the URN is sufficient to provide a location service.

    Equivalence is determined by comparing (ignoring case) the <B>
components
    of the two topics to be compared.  If they are equal the two topics are
    considered to be equal. Otherwise they are considered to be unequal
even if
    the underlying content is in fact identical. The characteristics of the
MD5
    sum ensure that only a small number of topics will be unnecessarily
    duplicated as a result of such false positive equivalences.

Security and Privacy:

   The validity of the URN can be checked as follows:

   Check that the <T> component is "dita".

   Check that the <G> component is computed correctly as described above.

Inter-operability:

   The case of the letters chosen is immaterial and can be safely ignored in
   all computations on the proposed URN as only the <B> component is used
for
   comparisons.

   Dita topics that do not contain ASCII characters suitable for
constructing
   the <G> component will be accommodated by adding a new value to the list
of
   values accepted by the <T> component and specifying the corresponding
   algorithm for computing the <G> component in an update to this document.

Additional Information:

   An implementation in Perl of the GB Standard as specified above  when
<T> is
   equal to "dita" is located at:

References:

   ASCII: https://en.wikipedia.org/wiki/ASCII

   Dita specification:

   XML: https://en.wikipedia.org/wiki/XML

On Thu, Sep 26, 2019 at 5:15 AM Hakala, Juha E <[email-masked]>
wrote:

> Hello Philip,
>
>
>
> as regards this:
>
>
>
> Please tell me whether it is necessary for a *urn* to be able to uniquely
> locate files as well as classify them?
>
>
>
> URNs don’t have to be provide resolution services, so the resolver (if
> any) does not need to know the location or locations of the identified
> resource, or to link the URN to these URL / URLs. You may want to mention
> in the urn:gbs namespace registration request that no resolution services
> are anticipated.
>
>
>
> It might be useful to add to the request the sentences below on document
> types and <T> values, with a note that for the time being only Dita
> documents are within scope. And some background information about Dita
> might be useful as well, for those who are not familiar with it.
>
>
>
> Best regards,
>
>
>
> Juha
>
>
>
> *Lähettäjä:* urn <[email-masked]> *Puolesta *Philip R Brenan
> *Lähetetty:* keskiviikko 25. syyskuuta 2019 21.46
> *Vastaanottaja:* [email-masked]
> *Kopio:* [email-masked]; Dale R. Worley <[email-masked]>
> *Aihe:* Re: [urn] gbs Name space identifier
>
>
>
> I have removed the link in question as the explanation of the derivation
> of the *<T>* component was deemed unsatisfactory.  Here is what I was
> trying to achieve:
>
>
>
> It is anticipated that the GB Standard represented by the *urn:* *gbs*
> name space could be usefully applied to a number of different document
> types, such as Dita, DocBook, Word, Html etc.  The <T> component is
> designed to separate these various name spaces. At the moment the only <T>
> in active use  is *dita* for Dita documents.  Within the Dita space the
> algorithm for computing the *<G>* component is included in:
>
>
>
> files as well as classify them?  If it is a requirement that a *urn *can
> be used to locate a topic file anywhere in the world then I need to rethink

-- 
Thanks,