Changes between Version 73 and Version 74 of GAPI_AM_API_DRAFT

Timestamp:

09/24/12 09:09:32 (12 years ago)

Author:

Aaron Helsinger

Comment:

--

GAPI_AM_API_DRAFT

@@ -62 +62 @@
 
 This change set proposes adding `geni_am_code_version` to the return from `GetVersion`.
- * The field is optional.
+ * The field is optional. Aggregate developers are expected to include this option, but site operators may select not to expose it.
  * The value is a string. 
  * Legal characters are: alphanumeric, space, `-` (hyphen), `.`, `:` (colon), `#`, `_` (underscore), `+`, `(`, `)`
@@ -115 +115 @@
 Various fields in the AM API specification are defined only as strings, without explicit limits on legal characters. This makes it awkward to pass these values to and from scripts. In particular, many fields should only be alphanumeric, plus some limited number of separator characters. 
 
-Note that in general, where this API says 'alphanumeric' or explicitly identifies `a-zA-Z`, we would ''like'' to expand this to non-ASCII letters, to support internationalization - making these into unicode strings. Therefore, aggregates are encouraged to support non-ASCII letters as input. Clients are encouraged to support non-ASCII returns from aggregates. However, this change set does not require that either aggregates or clients support non-ASCII strings, and aggregates should not require clients to accept non-ASCII results where the API does not explicitly require it.
-
 This change set proposes constraining several options/return values that are currently defined only as 'string'.
 
@@ -131 +129 @@
 
  5. From the return of multiple methods, `geni_operational_status`: alphanumeric
+
+=== Change Set O3: Allow unicode values ===
+Many values defined by this API appear to be limited to ASCII characters - both arguments and returns. We would like to support internationalization. Some values in this API (e.g. those defined as URLs) implicitly support unicode. Currently, a well behaved aggregate should be able to handle unicode values in at least some arguments. Similarly, a well behaved client should be able to handle unicode returns. 
+
+This change would clarify the support for internationalization in this API, and allow aggregates to specify unicode support. This change would specify:
+
+  Aggregates are encouraged to support non-ASCII letters as input. Clients are encouraged to support non-ASCII returns from aggregates. However, this change set does not require that either aggregates or clients support non-ASCII strings, and aggregates should not require clients to accept non-ASCII results where the API does not explicitly require it.
+
+This change would allow an aggregate to explicitly specify that arguments and returns should be treated as unicode. By default, aggregates are expected to use the ASCII only regular expressions that the rest of this API specification uses, and to limit returns to ASCII characters where possible. This change would add an optional return from `GetVersion` that allows an aggregate to specify that all returns must be handled as unicode. Specifically, this change adds `geni_unicode_compliant` to the return from `GetVersion`. 
+ - This field is optional.
+ - Default is `false`. All strings specified in this API are to be treated as ASCII unless otherwise specified, (e.g. the format explicitly references a standard that supports unicode). This includes both arguments and returns.
+ - When `true`, all strings specified in this API are to be treated as unicode. In particular, regular expressions that limit to ASCII characters shall be interpreted to include the unicode equivalents.
 
 == Older Proposals ==