• OGF GLUE2 Enumerations procedures and best practices
  • 1. Introduction
    • 1.1. Acknowledgements
  • 2. Naming Schemes
    • 2.1. Services
    • 2.2. Interfaces
    • 2.3. Capabilities
    • 2.4. Sorting out special classes of names
      • In case the organization name is unknown/undefined/short-lived
      • Simplified naming for Services with only one Interface
  • 3. Requesting new Open Enumerations
  • 4. Management of Open Enumerations
    • 4.1. Description of Open Enumerations CSV files
    • 4.2. Statuses
    • 4.3. GLUE2 Working Group Procedures
  • 5. References

OGF GLUE2 Enumerations procedures and best practices¶

Author: Florido Paganelli florido.paganelli_REMOVE!THIS_@hep.lu.se

version:1.0

Document Status: Work in Progress

Last revision: 2014-06-18

1. Introduction¶

This work is an attempt to summarize and generalize the usage of Open Enumerations in GLUE2, and an attempt to set some rules on how the management of these should be carried on.

The key words ‘MUST,” “MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,” “SHOULD NOT,” “RECOMMENDED,” “MAY,” and “OPTIONAL” are to be interpreted as described in RFC 2119 (see http://www.ietf.org/rfc/rfc2119.txt).

1.1. Acknowledgements¶

Thanks to Stephen Burke, David Meredith, Paul Millar and Balazs Konya for kickstart of these ideas and their further development. Thanks to John-Paul Navarro and Shiraz Memon for coordinating this work within the OGF GLUE2 Working Group. Thanks to Andre Merzky for comments.

2. Naming Schemes¶

The following rules apply:

1. Every string is RECOMMENDED to be lowercase.
2. Clients MUST consider these strings case-sensitive as defined in GFD.147.
3. Case MUST NOT be used as a way to distinguish strings; in practice, the group will not accept names that only differ in case.

2.1. Services¶

This applies to the GLUE2 Open Enumeration ServiceType_t.

See also GFD.147, Appendix B.31

<organization_name>.<product_name>.<service_detail>

where

<organization_name>
is the reversed domain name of the organization which provides or maintains the service or a reversed domain name associated with the project.
Presence: RECOMMENDED for new names. Exceptions MUST be justified.

<product_name>
free form string for product names
Presence: MANDATORY

<service_detail>
free form string that SHOULD identify a subservice or a service implementation. It can contain dots.
Presence: OPTIONAL

Decision: RECOMMENDED requirement is

<organization_name>.<product_name>

Examples: org.nordugrid.arex, org.glite.ce.cream

Existing names not following the above rules can be kept, but MAY be Deprecated to be consistent with recommendations. (see Section 2.4 and Section 4.1)

2.2. Interfaces¶

This applies to the GLUE2 Open Enumeration InterfaceName_t.
GFD.147 Appendix B.18 does not define any clear format. The following is RECOMMENDED:

<organization_name>.<interface_name>

where:

<organization_name>
is the reversed domain name of the organization which provides or maintains the service or a reversed domain name associated with the project.
Presence: RECOMMENDED for new names. Exceptions MUST be justified.

<interface_name>
free form string for product names
Presence: MANDATORY

Examples: org.nordugrid.xbes, org.ogf.glue.emies.activitycreation, org.glite.voms

2.3. Capabilities¶

See GFD.147, appendix B.5, on Capability_t.

2.4. Sorting out special classes of names¶

In case the organization name is unknown/undefined/short-lived¶

Use the reserved prefix:

org.ogf.glue.

org.ogf.glue.* SHOULD be used if the proposed domain name is not applicable. Examples are expired/nonexistent/unregistered domains, domains that have been used for other purposes than the proposed product, and so on. The group can decide case by case.

Example:For EMIR, developed during EMI project that now is over, ServiceType_t is: org.ogf.glue.emir

If a project ends and the product has an orphaned reverse domain name, the name can be kept.

Simplified naming for Services with only one Interface¶

A specific Endpoint interface can be bound to a specific Service. In such case, to simplify name creation, InterfaceName_t MAY be the same of a corresponding ServiceType_t.

3. Requesting new Open Enumerations¶

A community willing to submit new open enumeration MUST:

1. Provide the following information about the enumeration to be submitted:
   • Type of the enumeration to be added (i.e. one of the types described in GFD.147, Appendix B )
   • Name of the enumeration as in the guidelines in Section 2;
   • Description of the enumeration. This description is a textual, human readable summary of what the object described by the open enumeration does. It SHOULD be provided in two parts: a concise description that will be stored as part of the definition of the enumerated types, and a (usually) longer description that will explain to the WG what the new type is for.
   • Reference email to be contacted by the OGF group during evaluation of the proposed strings. This email will not be published and will be internal to the group.
2. Send the above information to the OGF group at the address glue-wg@ogf.org with subject “[Enumerations] Request for addition/</nowiki>obsoletion/modification”

NOTE: Requests that are missing the information listed in 1 will be automatically rejected. The proposer will be asked to provide missing information.

4. Management of Open Enumerations¶

The group preserves the current list of Open Enumerations in the git repository at the link

https://github.com/OGF-GLUE/Enumerations

in the form of CSV files. Section 4.1 contains a description of the content of the CSV files.

The groups keeps them updated using the procedures listed in this document, defined in Section 4.3.

4.1. Description of Open Enumerations CSV files¶

CSV filenames in git-hub are of the form:

Filename	Purpose	Example
<EnumerationName_t>.csv	Contains Open Enumerations officially approved by the group.	ServiceType_t.csv
<EnumerationName_t>-draft.csv	Contains Open Enumerations approved by the group AND Open Enumerations pending approval from the group	ServiceType_t-draft.csv

Records contained in the CSV files are as follows:

Field Name	Purpose	Example
EnumerationType	Enumeration Type name. MUST be the same as in the filename.	ServiceType_t
EnumerationValue	It's the enumeration value.	org.nordugrid.arex
Description	Contains the textual description of the object represented by the enumeration name.	NorduGrid Resource Coupled Execution Service
Status	See discussion below.	Recommended
Recommended	If this field is NOT EMPTY, then the contained string SHOULD be used instead of the EnumerationValue.	org.nordugrid.arex
Deprecates	If the field is NOT EMPTY, then the EnumerationValue string SHOULD be used instead of the contained values.	org.nordugrid.execution.arex

4.2. Statuses¶

4.3. GLUE2 Working Group Procedures¶

5. References¶