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?

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 Consolas font is used for all type names, property names and literals.
    • type names are in red with a light red background – threat-actor
    • property names are in bold style – created_at
    • literals (values) are in blue with a blue background – malicious-activity
    • 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 Consolas 9-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].
  • 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

From: <csaf@lists.oasis-open.org> on behalf of Eric Johnson <eric@tibco.com>
Date: Monday, April 30, 2018 at 5:11 PM
To: "csaf@lists.oasis-open.org" <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:





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".




P.S. Style guides from around the web: Google, Apiary, JSON-API . I found lots of other examples of people using camelCase, but no explicit style guides that mention JSON patterns.


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