unified should output multi-word, dash-delimited descriptors with appropriate case

[corntoole]

When unified is given descriptors with multi-word, dash-delimited identifiers e.g. date-time, it outputs types and RPCs with invalid names in SDL and ProtocolBuffer syntax.

Example 1

alps:
  version: "1.0"
  descriptor:
    - id: "date-time"
    -
      id: "message-post"
      type: unsafe
      rt: empty
      descriptor:
        - href: "#message-text"

syntax = "proto3";
package microblogging;

// *******************************************************************
// generated by "unified" from microblogging.yaml
// date: Sun Dec 27 2020 11:20:57 GMT-0600 (Central Standard Time)
// http://github.com/mamund/2020-11-unified
// *******************************************************************
message date-timeParams {
  string date-time = 1;
}

# *******************************************************************
# generated by "unified" from microblogging.yaml
# date: Sun Dec 27 2020 11:35:12 GMT-0600 (Central Standard Time)
# http://github.com/mamund/2020-11-unified
# *******************************************************************

type Mutation {
  message-post(message-text: String!): empty
  message-reply(user-text: String!): empty
}
// ...

Descriptors for state transitions should use camel-case; data descriptors should use camel-case or snake-case as appropriate.

Here is the full ALPS yaml that I'm testing. I converted it from alps-io/profiles/xml/microblogging.xml

alps:
  version: "1.0"
  name: microblogging
  doc: "The example profile here contains details on customizing any representation media type for a specific \n    application domain: Micro-blogging. It contains descriptions of valid data and transition values that \n    can appear within resource representations. This document is presented as a complete blueprint for \n    implementing a compliant client or server that supports the basic features of the target application \n    domain (Micro-blogging)."
  # metadata
  ext:
    - type: metadata
      name: title
      value: microblogging
      tags: "oas"
    - type: metadata
      name: id
      value: https://corntoole.github.io/api-profiles/microblogging
      tags: "oas"
    - type: metadata
      name: root
      value: http://api.example.org/microblogging
      tags: "oas"
  link:
    rel: help
    href: "http://amundsen.com/hypermedia/profiles/"
  descriptor:
    - doc: "Contains the UTC date-time the message was posted. When present, it SHOULD be valid per RFC3339."
      id: "date-time"
      type: semantic
    - doc: "Contains the text description of a user."
      id: description
      type: semantic
    - doc: ""
      id: xx
      type: semantic
    - doc: "A list representation of unfiltered results."
      id: all
      type: semantic
      descriptor:
        - href: "#users"
        - href: "#messages"
    - id: friends
      type: semantic
      doc: "A list representation."
      descriptor:
        - href: "#users"
        - href: "#messages"
    - id: followers
      type: semantic
      doc: "A list representation of all the users from the designated user's friends list."
      descriptor:
        href: "#users"
    - id: me
      type: semantic
      doc: "Contains the list of messages posted by the designated user or contains\n      the designated user's profile."
      descriptor:
        - href: "#users"
        - href: "#messages"
    - id: mentions
      type: semantic
      doc: "A list representation of all the messages that mention the designated user"
      descriptor:
        href: "#messages"
    - id: message
      type: semantic
      doc: "A representation of a single message."
      descriptor:
        - href: "#user-text"
        - href: "#user-link"
        - href: "#message-text"
        - href: "#message-link"
        - href: "#user-image"
        - href: "#date-time"
    - id: empty
    - doc: "A link template to add a new message to the system by the designated (logged-in) user."
      descriptor:
        - href: "#message-text"
      rt: empty
      id: "message-post"
      type: unsafe
    - doc: "A link template to reply to an existing message."
      descriptor:
        - doc: "the author of the post to be replied-to"
          href: "#user-text"
          name: user
        - href: "#message-text"
          name: message
      id: "message-reply"
      type: unsafe
      rt: empty
    # - doc: ""
    #   id: xx
    #   type: semantic

[mamund]

good catch, @corntoole.

[mamund]

Descriptors for state transitions should use camel-case; data descriptors should use camel-case or snake-case as appropriate.

I assume this is "best/oreferred practice" for proto files, right?

any chance you can scaratch out some simple "rules" (e.g. when to use camelCase vs. snake_case) here in the thread to inform the transformation?

i'd be happy to code up the rules into the tool.

thx.

[corntoole]

Yes, the suggested naming convention for protocol buffers is for message names to be camel-case, e.g. date-time -> DateTime; whereas, field names should be snake-case, e.g. date-time -> string date_time.

I haven't yet found an official style guide for graphQL, but it seems that types names should be capitalized-camel-case and all other identifiers camel-case.

[mamund]

@corntoole:

very good. thanks for the great proto styleguide reference![1]

so, for .proto files we'll use upper camel case (aka Pascal case[2]) for MessageNames, ServiceNames, and MethodNames. Then snake case for field_names. if/when Enums come up, i'll know where to look.

if/when you find a solid style guide for SDL/GraphQL or OpenAPI feel free to start a new issue for them, too.

thanks.

[1] https://developers.google.com/protocol-buffers/docs/style#message_and_field_names [2] https://en.wikipedia.org/wiki/Camel_case#Variations_and_synonyms

[mamund]

@corntoole:

added a branch w/ your suggested changes: https://github.com/mamund/alps-unified/pull/13

can you check this out and add remarks?

if all is good, i'll do the merge when you're ready.

[mamund]

@corntoole

sorry for the radio silence. i got stumped as i was working to incorporate some of the work of @mmuller88 and his WSD CDK project.

i'll circle back and see where we can pick up on this in the next week or so.

hope to see you on the mailing list and at one of our ALPS Open Office Hours sometime soon, too.

-- @mamund