Recommendation for dasherizing (kebab-case-ing) namespaced object, such as `Admin::User`

[bf4]

JSON API recommends dasherized keys, so an AdminUser would be represented by admin-user. But, does/should JSON API have an opinion on namespaced objects? That Admin::User would be dasherized as admin/user? (That's the result in Rails of "Admin::User".underscore.dasherize)

[joaomdmoura]

+1

[bf4]

I suppose this would be a PR to http://jsonapi.org/recommendations/#naming ?

[bf4]

Do I understand correctly from the spec that SOLIDUS, "/" is disallowed in a member name, so I'm thinking maybe it has to be _?

Spec recommendations http://jsonapi.org/recommendations/#naming

Member names SHOULD contain only the characters "a-z", "0-9", and the hyphen minus ("-") as separator between multiple words.

Spec Rules http://jsonapi.org/format/#document-member-names, basically:

A-Z, a-z, 0-9, -, _, SPACE (not recommended), any UNICODE character except U+0000 to U+007F (not recommended)
With some disallowed characters http://jsonapi.org/format/#document-member-names-reserved-characters

[ethanresnick]

Yes, the solidus is not allowed and a hyphen, double hyphen, or underscore could be used instead. But I'm hesitant to make any sort of recommendation here, because, given the complexities around hierarchical types, I don't want clients to start inferring any meaning from whatever separator pattern we might recommend.

[bf4]

So, this Ember code not per JSON API?

https://github.com/emberjs/data/blob/aeccf38a5193a9fbf763a835588cc4ad315324b7/packages/ember-data/lib/serializers/json-api-serializer.js#L319-L351

By default JSONAPISerializer follows the format used on the examples of
http://jsonapi.org/format and uses dashes as the word separator in the JSON
attribute keys.

import { pluralize, singularize } from 'ember-inflector/lib/system/string';

var dasherize = Ember.String.dasherize;

keyForAttribute: function(key, method) {
return dasherize(key);
},

Where dasherize is https://github.com/emberjs/ember.js/blob/v2.0.1/packages/ember-runtime/lib/system/string.js#L242-L258

Replaces underscores, spaces, or camelCase with dashes.

'innerHTML'.dasherize(); // 'inner-html'
'action_name'.dasherize(); // 'action-name'
'css-class-name'.dasherize(); // 'css-class-name'
'my favorite items'.dasherize(); // 'my-favorite-items'
'privateDocs/ownerInvoice'.dasherize(); // 'private-docs/owner-invoice'

Where dasherize is defined as:

str.replace(/([a-z\d])([A-Z])/g, '$1_$2').toLowerCase().replace((/[ _]/g, '-');

var STRING_DASHERIZE_REGEXP = (/[ _]/g);

var STRING_DASHERIZE_CACHE = new Cache(1000, function(key) {
return decamelize(key).replace(STRING_DASHERIZE_REGEXP, '-');
});

var STRING_DECAMELIZE_REGEXP = (/([a-z\d])([A-Z])/g);

var DECAMELIZE_CACHE = new Cache(1000, function(str) {
return str.replace(STRING_DECAMELIZE_REGEXP, '$1_$2').toLowerCase();
});

i.e. it leaves slashes alone

[ethanresnick]

Correct, that ember code would be non compliant; good catch there. I'd open an issue on the ember data repo.

[bf4]

Discussing in rails-api/active_model_serializers#1216 Admin::User -> admin--user seems weird. Any idea why / and : are disallowed? (or any non-alphanum, -, _, or ' ')

[youroff]

I think the main concern is that it's non url-safe. So someone would want to use resource type in url. So we could use . here, as it's url-safe and doesn't interfere with other word-separators.

Also we could use completely different approach by moving namespace to its own field next to type (and make it optional), or to the meta (which wouldn't require any standard changes, I assume).

[bf4]

Thanks @youroff but . isn't available either :( http://jsonapi.org/format/#document-member-names-reserved-characters https://github.com/json-api/json-api/blob/gh-pages/_format/1.0/normative-statements.json#L966-L1004

{
         "description": "it is **RECOMMENDED** that member names use only non-reserved, URL safe characters specified in RFC 3986.",
        "description": "The following \"globally allowed characters\" **MAY** be used anywhere in a member name:\\n\\n- U+0061 to U+007A, \"a-z\"\\n- U+0041 to U+005A, \"A-Z\"\\n- U+0030 to U+0039, \"0-9\"\\n- any UNICODE character except U+0000 to U+007F (not recommended, not URL safe)",
        "description": "The following characters **MUST NOT** be used in member names:\\n\\n- U+002B PLUS SIGN, \"+\" (used for ordering)\\n- U+002C COMMA, \",\" (used separator for multiple relationship paths)\\n- U+002E PERIOD, \".\" (used as relationship path separators)\\n- U+005B LEFT SQUARE BRACKET, \"[\" (use in sparse fieldsets)\\n- U+005D RIGHT SQUARE BRACKET, \"]\" (used in sparse fieldsets)\\n- U+0021 EXCLAMATION MARK, \"!\"\\n- U+0022 QUOTATION MARK, '\"'\\n- U+0023 NUMBER SIGN, \"#\"\\n- U+0024 DOLLAR SIGN, \"$\"\\n- U+0025 PERCENT SIGN, \"%\"\\n- U+0026 AMPERSAND, \"&\"\\n- U+0027 APOSTROPHE, \"'\"\\n- U+0028 LEFT PARENTHESIS, \"(\"\\n- U+0029 RIGHT PARENTHESIS, \")\"\\n- U+002A ASTERISK, \"*\"\\n- U+002F SOLIDUS, \"/\"\\n- U+003A COLON, \":\"\\n- U+003B SEMICOLON, \";\"\\n- U+003C LESS-THAN SIGN, \"<\"\\n- U+003D EQUALS SIGN, \"=\"\\n- U+003E GREATER-THAN SIGN, \">\"\\n- U+003F QUESTION MARK, \"?\"\\n- U+0040 COMMERCIAL AT, \"@\"\\n- U+005C REVERSE SOLIDUS, \"\\\"\\n- U+005E CIRCUMFLEX ACCENT, \"^\"\\n- U+0060 GRAVE ACCENT, \"`\"\\n- U+007B LEFT CURLY BRACKET, \"{\"\\n- U+007C VERTICAL LINE, \"|\"\\n- U+007D RIGHT CURLY BRACKET, \"}\"\\n- U+007E TILDE, \"~\""
}

[bf4]

Another answer might be Admin::UserManager -> admin user-manager and require the space be url encoded as %20?

In #567 I see that the intention of reserved is for future use, so maybe we could use /?

sub-references:

• Allowed format/characters for member names #601
• https://en.wikipedia.org/wiki/Naming_convention_%28programming%29#Multiple-word_identifiers
• https://tools.ietf.org/html/rfc3986
• Add naming recommendations to format #583
• Underscored or hyphenated urls? kurko/ember-json-api#53

cc people I think were involved in the discussion of member names @dgeb @ziege @tkellen @kurko