OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

csaf message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [csaf] First question that comes up when creating a JSON schema - what's the naming convention for fields?


Another plus for separating lowercase words with underscores (besides python and c++ core guidelines using them and other prio art):

If you offer left rooted semantics you can easily split from the left by underscore to discover any meaningful relatonships encoded by the producer, splitting on Upercase letters from the left is less robust, not so performant and might trip on the everlasting established acronym creep into keys (like whateverHTTPFoo is harder to dissect in further levels then whatever_HTTP_foo ...).

PS: Length addition of the underscore is IMO no argument, as sparing bytes on the wire does usually end up in CBOR, protobuf, void**, whatnot-protocol but not in JSON ;-)

All the best,
Stefan.

Am 01.05.18 um 02:59 schrieb duncan@sfractal.com:
'common OASIS practices'
I don't know if it's everywhere but I can say that OpenC2 TC copied the
STIX wording that Allan quoted.
Although I like camelCase in wiki's, I understand and agree with the
'all lowercase' requirement for json.

Duncan Sparrell
sFractal Consulting LLC
iPhone, iTypo, iApologize


    -------- Original Message --------
    Subject: Re: [csaf] First question that comes up when creating a JSON
    schema - what's the naming convention for fields?
    From: Allan Thomson <athomson@lookingglasscyber.com
    <mailto:athomson@lookingglasscyber.com>>
    Date: Mon, April 30, 2018 8:24 pm
    To: Eric Johnson <eric@tibco.com <mailto:eric@tibco.com>>,
    "csaf@lists.oasis-open.org <mailto:csaf@lists.oasis-open.org>"
    <csaf@lists.oasis-open.org <mailto:csaf@lists.oasis-open.org>>

    Eric – here’s a copy from STIX2.x specification documents that were
    used and I believe are based on common OASIS practices.

    *​1.6​ Naming Requirements***
    *​1.6.1​ Property Names and String Literals***
    In the JSON serialization all property names and string literals
    *MUST* be exactly the same, including case, as the names listed in
    the property tables in this specification. For example, the SDO
    common property *created_by_ref*must result in the JSON key name
    "created_by_ref". Properties marked required in the property tables
    *MUST* be present in the JSON serialization.

    *1.7​ Document Conventions***
    *​1.7.1​ Naming Conventions***
    All type names, property names and literals are in lowercase, except
    when referencing canonical names defined in another standard (e.g.
    literal values from an IANA registry). Words in property names are
    separated with an underscore (_), while words in type names and
    string enumerations are separated with a hyphen (-). All type names,
    property names, object names, and vocabulary terms are between three
    and 250 characters long.
    *​1.7.2​ Font Colors and Style***
    The following color, font and font style conventions are used in
    this document:

      * The Consolasfont is used for all type names, property names and
        literals.
          o type names are in red with a light red background – threat-actor
          o property names are in bold style – *created_at*
          o literals (values) are in blue with a blue background –
            malicious-activity
          o All relationship types are string literals, therefore they
            will also appear in blue with a blue background – related-to
      * In an object's property table, if a common property is being
        redefined in some way, then the background is dark grey.
      * All examples in this document are expressed in JSON. They are in
        Consolas9-point font, with straight quotes, black text and a
        light grey background, and 2-space indentation. JSON examples in
        this document are representations of JSON Objects. They should
        not be interpreted as string literals. The ordering of object
        keys is insignificant. Whitespace before or after JSON
        structural characters in the examples are insignificant [RFC8259
        <https://docs.google.com/document/d/1ShNq4c3e1CkfANmD9O--mdZ5H0O_GLnjN28a_yrEaco/edit#bookmark=id.mmt4e4p953r5>].
      * Parts of the example may be omitted for conciseness and clarity.
        These omitted parts are denoted with the ellipses (...).
      * The term “hyphen” is used throughout this document to refer to
        the ASCII hyphen or minus character, which in Unicode is
        “hyphen-minus”, U+002D.




    Allan Thomson__
    CTO (+1-408-331-6646)
    LookingGlass Cyber Solutions <http://www.lookingglasscyber.com/>
    *From: *<csaf@lists.oasis-open.org
    <mailto:csaf@lists.oasis-open.org>> on behalf of Eric Johnson
    <eric@tibco.com <mailto:eric@tibco.com>>
    *Date: *Monday, April 30, 2018 at 5:11 PM
    *To: *"csaf@lists.oasis-open.org <mailto:csaf@lists.oasis-open.org>"
    <csaf@lists.oasis-open.org <mailto:csaf@lists.oasis-open.org>>
    *Subject: *[csaf] First question that comes up when creating a JSON
    schema - what's the naming convention for fields?

    Options seem to be:
    "snake_case"
    "camelCase"
    "CamelCase"

    Hyphens definitely a bad idea.

    Javascript convention suggests "camelCase" is the right choice. JSON
    schema itself follows "camelCase".

    Does anyone know if OASIS has established a best practice here, or
    if other TCs have set an OASIS precedent that we should follow?
    (OData appears to use "camelCase").

    Absent feedback from anyone, I'm going to assume "camelCase".

    Eric.

    P.S. Style guides from around the web:
    Google<https://google.github.io/styleguide/jsoncstyleguide.xml>,
    Apiary<https://help.apiary.io/tools/style-guide/>,
    JSON-API<http://jsonapi.org/recommendations/> . I found lots of
    other examples of people using camelCase, but no explicit style
    guides that mention JSON patterns.


--------------------------------------------------------------------- To
unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php


--
Stefan Hagen
read://shagen.de
talk: eventually


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]