[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?
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]