Design Rules For JSON V1.0.1

Design Rules for JSON Revision / Date: Page:
Version 1.1 (Draft) / 18 July 2018 1 of 32
DESIGN RULES FOR JSON
30 July 2018
Draft Version 1.1
Document Summary
This document describes the International Forecourt Standards Forum

(IFSF) and Conexxus style guidelines for the use of JSON based APIs,
including element and object naming conventions. These guidelines are
based on best practice gleaned from OMG (IXRetail), W3C, Amazon,
Open API Standard and other industry bodies.
Design Rules for JSON V1.0.1 Page 1 of 32

Contributors
Axel Mammes, OrionTech

Gonzalo Gomez, OrionTech
Linda Toth, Conexxus
John Carrier, IFSF

Revision History
Revision Date Revision Revision Editor(s) Revision Changes

Number
April 2016 Draft V0.5 Gonzalo Gomez, Initial Draft for DI WG Review
OrionTech
John Carrier, IFSF
Nov 2016 Draft V0.6 Gonzalo Gomez, Segregation of pure JSON design rules as
OrionTech agreed with Conexxus
Carlos Salvatore,
OrionTech
February 2017 V1.0 John Carrier, IFSF First Release (document name and version
identification changes only)
30 July 2018 Draft V1.1 John Carrier, IFSF Layout changed to Joint IFSF/Conexxus
format.
Updates for additional Industry Best Practise
and guideline “rationale” added (based on
W3C Vehicle API Creation Guidelines and
Rationale)

Copyright Statement
The content (content being images, text or other medium contained within this document which is
eligible of copyright protection) are jointly copyrighted by Conexxus and IFSF. All rights are expressly
reserved.
IF YOU ACQUIRE THIS DOCUMENT FROM IFSF, THE FOLLOWING STATEMENT ON THE USE OF
COPYRIGHTED MATERIAL APPLIES:
You may print or download to a local hard disk extracts for yoiur own business use. Any other
redistribution or reproduction of part or all of the contents in any form is prohibited.
You may not, without our express written permission, distribute t o any third party. Where permission
to distribute is granted by IFSF, the material must be acknowledged as IFSF copyright and the document
title specified. Where third party material has been identified, perm,ission from the respective copyright
holder must be sought.
You agree to abide by all copyright notices and restrictions attached to the content and not to remove
or alter such notice or restriction.
Subject to the following paragraph, you may design, develop and offer for sale products which embody
the functionality described in this document.
No part of the content of this document may be claimed as Intellectual property of any organisation other
than IFSF Ltd, and you specifically agree not to claim patent rights or other IPR protectiuoin that relates
to:
a) The content of this document,
b) Any design or part thereof that embodies th3e content of this document whether in whole or part.
For further copies of this document and amendments to this document please contact: IFSF Technical
Services via the IFSF web Site (www.ifsf.org).
IF YOU ACQUIRE THIS DOCUMENT FROM IFSF, THE FOLLOWING STATEMENT ON THE USE OF
COPYRIGHTED MATERIAL APPLIES:
Conexxus members may use this document for purposes consistent with the adoption of the Conexxus
Standards (and/or the related documentation); however Conexxus musrt pre-approve any inconsistent
uses in writing.
Conexxus recognises that a member may wish to create a derivative work that comments on, r otherwise
explains or assists in implementation, including citing or referring to the standard, sopecification,
protocol, schema, or guideline, in whole or in part. The member may do so, but may share such derivative
work ONLY with another Conexxus Member who possesses appropriate document rights (i.e., Gold or
Silver Members) or with a direct contractor who is resaoponsible for implementing the standard for the
Member. In so doing, a Conexxus member should require its development partners to download
Conexxus documents and Schemas directly from the Conexxus website. A Conexxus Member may not
furnish this document in any form, along with derivative works, to non-members of Conexxus or to
Conexxus Members who do not possess document rights (e.g. Bronze Members) or who are not direct

contractors of the Member. A member may demonstrate its Conexxus membership at a level that
includes document rights by presenting an unexpired signed membership certificate.
This document may not be modified in any way, including removal of the copyruight notice or references
to Conexxus. However, a Member has the right to make draft changes to schema for trial use before
submission to Conexxus for consideration to be included in the existing standard. Translations of this
document into languages other than English shall continue to reflect the Conexxus copyright notice.
The limited permissions granted above are perpetual and will nopt be revoiked by Conexxus, Inc. or its
successors or assigns, except in the circumstances where an entity, who is no longer a member in good
standing but who rightfully obtained Conexxus Standards as a former member, is acquired by a non-
member entity. In such circumstances, Conexxus may rvoke the grant of limited permissions or require
the acquiring entity to establish rightful access to Conexxus Stanards through membership.
Disclaimers
IF YOU ACQUIRE THIS DOCUMENT FROM CONEXXUS, THE FOLLOWING DISCLAIMER STATEMENT
APPLIES:
Conexxus makes no warranty, express or implied, about, nor does it assume any legal liability or
responsibility for the accuracy, completeness, or usefulness of any information, product, or process
described in these materials. Although Conexxus uses reasonable best efforts to ensure this work
product is free of any third party intellectual property rights (IPR) encumbrances, it cannot guarantee
that such IPR does not exist now or in the future. Conexxus further notifies all users of this standard
that their individual method of implementation may result in infringement of the IPR of others.
Accordingly, all users are encouraged to carefully review their implementation of this standard and
obtain appropriate licenses where needed.

1 Document Contents
1 DOCUMENT CONTENTS .............................................................................................................. 6
2 REFERENCES ............................................................................................................................... 8
3 GLOSSARY ................................................................................................................................... 9
4 INTRODUCTION......................................................................................................................... 10
4.1 AUDIENCE ................................................................................................................................... 10
4.2 BACKGROUND .............................................................................................................................. 10
4.3 WHAT IS REST? ........................................................................................................................... 10
4.4 USAGE OF JSON........................................................................................................................... 10
5 DESIGN OBJECTIVES .................................................................................................................. 11
5.1 OVERALL JSON DESIGN ................................................................................................................. 11
5.2 COMMERCIAL MESSAGES ............................................................................................................... 11
6 VERSIONING.............................................................................................................................. 11
6.1 BACKWARD COMPATIBILITY ............................................................................................................ 11
6.2 FORWARD COMPATIBILITY .............................................................................................................. 12
6.3 VERSION NUMBERING ................................................................................................................... 12
6.3.1 Examples of Changes that can be incorporated in a Revision ................................................. 13
6.3.2 Examples of Changes that can be incorporated in a Minor Version ....................................... 13
6.3.3 Examples of Changes that Dictate a Major Version (new Release) ......................................... 13
6.3.4 Reflecting the Version Numbers for Data Types...................................................................... 13
7 THE COMMON LIBRARY ............................................................................................................ 14
7.1 DESIGNING THE COMMON LIBRARY.................................................................................................. 14
7.2 GUIDELINES FOR STRUCTURING LIBRARIES ......................................................................................... 15
7.3 VERSIONING OF THE COMMON LIBRARY ............................................................................................ 15
7.4 CODE LIST MANAGEMENT .............................................................................................................. 15
7.5 HIERARCHY OF DATA TYPE COMMON LIBRARY DOCUMENTS................................................................. 15
7.6 FILE NAMING CONVENTION ............................................................................................................ 16
8 DATA TYPE IMPLEMENTATION RULES ....................................................................................... 16
8.1 DOCUMENTATION......................................................................................................................... 16
8.1.1 Annotation Requirements ....................................................................................................... 16
8.1.2 Naming Conventions ................................................................................................................ 17
8.2 DOCUMENT ENCODING ................................................................................................................. 18
8.3 ELEMENT TAG NAMES ................................................................................................................... 18
8.3.1 Attribute and Types Names Use Lower Camel Case ................................................................ 18
8.3.2 Enumeration Rules ................................................................................................................... 18
8.3.3 Acronyms and Identifiers ......................................................................................................... 18
8.3.4 Attribute value ranges and increments ................................................................................... 19
8.3.5 Update Frequency.................................................................................................................... 19
8.4 REUSING DATA TYPES ..................................................................................................................... 20

8.5 REFERENCING DATA TYPES FROM OTHER DATA TYPE DOCUMENTS........................................................ 20

8.6 ELEMENTS ORDER ......................................................................................................................... 20
8.7 DATA TYPES ................................................................................................................................. 20
8.7.1 Use of Nillability ....................................................................................................................... 20
8.7.2 Boolean values ......................................................................................................................... 22
8.7.3 Numeric values ........................................................................................................................ 22
8.7.4 String values ............................................................................................................................. 23
8.7.5 Arrays ....................................................................................................................................... 24
8.7.6 Date time values ...................................................................................................................... 24
8.7.7 Hard and Soft Enumerations.................................................................................................... 25
8.7.7.1 Updating Hard Enumerations ........................................................................................................................................ 27
8.7.7.2 Updating Soft Enumerations ......................................................................................................................................... 27
8.7.8 Object Lists ............................................................................................................................... 28
9 PROPRIETARY EXTENSIONS ....................................................................................................... 29
9.1 EXTENSIONS EXAMPLE ................................................................................................................... 30
9.2 CLASS EXTENSIBILITY PROMOTION IN IFSF: ........................................................................................ 31
10 RULES SUMMARY...................................................................................................................... 32

2 References
[1] IFSF STANDARD FORECOURT PROTOCOL PART II – COMMUNICATION SPECIFICATION

[2] IFSF STANDARD FORECOURT PROTOCOL PART II.3 – COMMUNICATION SPECIFICATION OVER
REST
[3] IFSF STANDARD FORECOURT PROTOCOL PART III.I – DISPENSER APPLICATION
[4] Conexxus Design Rules for XML.PDF
[5] Google JSON Style Guide
https://google.github.io/styleguide/jsoncstyleguide.xml
[6] Design Beautiful REST + JSON APIs
https://www.youtube.com/watch?v=hdSrT4yjS1g
http://www.slideshare.net/stormpath/rest-jsonapis
[7] http://www.jsonapi.org/
[8] http://www.json-schema.org/
[9] https://labs.omniti.com/labs/jsend
[10] http://docs.oasis-open.org/odata/odata-json-format/v4.0/errata02/os/odata-json-format-
v4.0-errata02-os-complete.html#_Toc403940655
[11] http://semver.org/
[12] http://json-schema.org/
[13] http://www.json.org/

3 Glossary
Internet The name given to the interconnection of many isolated networks into a virtual
single network.
Port A logical address of a service/protocol that is available on a particular computer.
Service A process that accepts connections from other processes, typically called client
processes, either on the same computer or a remote computer.
API Application Programming Interface. An API is a set of routines, protocols, and tools
for building software applications
CHP Central Host Platform (the host component of the web services solution)
EB Engineering Bulletin
IFSF International Forecourt Standards Forum
JSON JavaScript Object Notation; is an open standard format that uses human-readable
text to transmit data objects consisting of attribute-value pairs
REST REpresentational State Transfer) is an architectural style, and an approach to

communications that is often used in the development of Web Services.
TIP IFSF Technical Interested Party
XML Extensible Markup Language is a markup language that defines a set of rules for
encoding documents in a format which is both human-readable and machine-
readable
RAML RAML (RESTful API Modeling Language) is a language for the definition of HTTP-
based APIs that embody most or all of the principles of Representational State
Transfer (REST).

4 Introduction
This document is a guideline for developing IFSF and Conexxus JSON Messages. This guideline helps to
ensure that all data types and the resulting JSON conform to a standard layout and presentation. This
guideline applies to all data types developed by IFSF, Conexxus and their work groups. This document is
based upon the Conexxus "Design Rules for XML" document to encapsulate their knowledge and
practical experience on writing style guidelines and to reflect the differences between how XML and
JSON messages are used by the standards bodies.
4.1 Audience
The intended audiences of this document include, non-exhaustively:

• Architects and developers designing, developing, or documenting RESTful Web Services.
• Standards architects and analysts developing specifications that make use of IFSF and
Conexxus Rest based APIs.
4.2 Background
Representational State Transfer (better known as REST) is a programming philosophy that was
introduced by Roy T. Fielding in his doctoral dissertation at the University of California, Irvine, in 2000.
Since then it has been gaining popularity and is being used in many different areas.
4.3 What is REST?
Representational State Transfer (REST) is an architectural principle rather than a standard or a protocol.
The basic tenets of REST are: simplify your operations, name every resource using nouns, and utilize the
HTTP commands GET, PUT, POST, and DELETE according to how their use is outlined in the original HTTP
RFC (RFC 26163). REST is stateless; does not specify the implementation details, and the interconnection
of resources is done via URIs. REST can also utilize the HTTP HEAD command primarily for checking the
existence of a resource or obtaining its metadata.
4.4 Usage of JSON
JSON is defined in Part II.3 document (see IFSF web site (www.ifsf.org)) as the standard message format
for REST APIs communication.
JSON is a way to represent and transmit data objects between applications, and is much more
lightweight than XML, not including Namespaces, XPath, transformations, etc. JSON was not designed
to have such features, even though some of them are now trying to find their places in the JSON world,
including JSONPath for querying, some tools for transformations, and JSON Schema for validation. But
they are just weak versions compared to what XML offers. Transforming one of the major advantages
of JSON that is its lightweight into more complex messages.
As part of this document, we describe a set of rules (and guidelines) that are to be taken into
consideration when defining the data sets serialized using JSON.

5 Design Objectives
Design objectives of the IFSF and Conexxus Data Type Library include:
• Maximizing component reuse;
• Providing consistent naming conventions for elements of a common nature (date and time,
currency, country, units of measure, counts, volumes, amounts, etc.).
5.1 Overall JSON Design
The use of JSON schemas take advantage of tools such as JSON schemas generators, automatic JSON
syntax validation, and conversion to multiple languages data structures using automated code
generators, etc. Bear in mind that not all tools are fully compatible with the latest JSON Schema draft
version (currently v4). We agreed together with Conexxus TAC team to adopt Altova XML Spy based on
its popularity and specific features. Also, minimal use of custom features is used in order to preserve
interoperability.
5.2 Commercial Messages
All commercial messages in JSON documents SHALL be removed. For example, remove any messages
similar to:
"Edited by <owner> with <JSchema editor> V2.0".
6 Versioning
Versioning of IFSF and Conexxus data types SHALL NOT be tightly coupled with the publication of IFSF
or CONEXXUS REST APIs. This means that all libraries including business-specific libraries and common
libraries SHALL NOT be mandated to hold the same version number.
In the next section, we resolve the following issues with versioning of data types:
• What constitutes a major and a minor version?
• What do we mean by compatibility?
• Do we need to provide for backward/forward compatibility between versions?
An IFSF Administration Bulletin (AB04) describes in detail the IFSF Version Identification (please see
www.ifsf.org).
6.1 Backward Compatibility
Definition: A given data type is backwardly compatible with a prior data type if no document valid under
the prior data type definition is invalid under the later data type definition.
Rule 1. Backward Compatibility for Revisions
Data type definition SHALL support backward compatibility as specified in section 7.3.

6.2 Forward Compatibility
Definition: The ability to design a data type such that even the older data type definition can validate
the instance documents created according to the newer version is called forward compatibility.
Rule 2. Forward Compatibility for Revisions Only
IFSF data type definitions SHALL support forward compatibility for specification revisions.
6.3 Version Numbering
IFSF standards SHALL adhere to the standard semantic versioning (Ref. 11) practice and be numbered
as follows:
• M.m.r (IFSF is R.mr)
• Where M [R] indicates the major release version, m indicates the minor release version, and r
indicates a point release version. In IFSF terminology M is the Release identification, M is the
version identification and r is the point revision. In IFSF terminology a point revision is a
change to the standard thast has no impact on the software code. A revision (major or minor
is a version change because it means software code must be re-written).
• Major versions (IFSF calls “Releases”) contain substantial changes to architectural and/or core
components where backward compatibility is not a constraint.
• Minor versions (IFSF calls “versions” contain updates where backward compatibility must be
preserved.
• Revisions correct errata, annotations, and data type extensions and maintain backward and
forward compatibility with no software code change (adding enumerations/data is not
considered a code change as it is expected data sets are managed outside the code.
Rule 3. Revisions (Versions) are backwardly and

forwardly compatible
All revisions of a data type definition within a major and minor version MUST be backwardly and
forwardly compatible with the all revisions within the same minor version.
Rule 4. Minor versions are backwardly compatible
All minor versions of a data type within a major version MUST be backwardly compatible with the
preceding minor versions for same major version, and with the major version itself.
Rule 5. All data types within a business process

have same version
To ease the ongoing maintenance of data type versioning, all data types within a Business Process (e.g.
the REMC specification) MUST have the same version.

This means that if one data type within a suite of JSON Schema data types that come under a particular
business process needs to be upgraded to the next version number, all the data type definitions within
that business process MUST be upgraded to that version number.
6.3.1 Examples of Changes that can be incorporated in a Revision
• Adding Comments and Errata

• Adding Extensions to Extensible objects.
• Adding or removing elements from a soft enum
6.3.2 Examples of Changes that can be incorporated in a Minor Version
• Adding new optional properties.

• Changing properties from required to optional.
• Adding values to a hard enum.
• Removing the enum facet, converting an enum to a non-enum.
• Removing constraints from a data type.
o Example 1: removing the maxValue facet of a numeric type.
o Example 2: incrementing or removing the maxItems facet of an array
6.3.3 Examples of Changes that Dictate a Major Version (new Release)
• Changing a property from optional to required.

• Adding a required property.
• Eliminating an optional property.
• Eliminating a required property.
• Changing a property or type name.
• Converting a type from non-array to an array (change of cardinality)
• Converting an array type to a non-array (change of cardinality)
• Changing a soft enum to a hard enum.
• Removing values from a hard enum
6.3.4 Reflecting the Version Numbers for Data Types
Rule 6. Versions will be represented using numeric

digits
• Major, minor and revision numbers will be represented using numeric characters only. The
complete representation of the version will be of the format
Majorversion.Minorversion.Revision (1.5.1) where:
o The first release of a major version will be numbered M.0.
o The first minor version of a given major version will be numbered M.1
o The first release of a minor version will be numbered M.m, instead of M.m.0.

o The first revision of a minor version will be numbered M.m.1.
Rule 7. Full version number reflected

in library folders
The complete version number is indicated in the file directory used to group project files by business
requirement.
Library file path examples:

common-v1.3.4/unitsOfMeasure.json
common-v1.3.4/countries.json
wsm-v1.0.0/tankStockReport.json
The chosen approach to indicating the complete version number is to simply change the version number
contained in the folder name referred by the uses clause at the beginning of the relevant JSON file.
There are many advantages to this approach. It’s easy to update since it a part of the header of the
documents, and the developers will have control of the library version in use. If versions were reflected
in the name of the data type, instance documents would not validate unless they were changed to
designate the new target libraries wherever used.
7 The Common Library

The common library consists of JSON Schema libraries that might be used in two or more Business
Documents. Placing shared components in a common library increases interoperability and simplifies
data type maintenance. However, it can also result in some additional complexities, which are addressed
in this chapter.
7.1 Designing the Common Library
Specifically, these areas need to be addressed:
1. Structuring the library documents: breaking down the data type definition documents into
smaller units to avoid the inclusion of document structures not required for a given
specification.
2. Versioning: creating one or more separate object sets data types, which will address the lack
of a separate life cycle.
3. Configuration management: determining a mechanism for storing, managing and distributing
the libraries.
4. Structuring the library documents involves deciding how large each library document should
be, and which components should be included together in a single document.
5. The approach chosen for IFSF documents is to include element declarations for those
elements that are shared across multiple IFSF specifications in shared libraries, commonly
called "dictionaries". Code list enumerations and other shared data may also be defined in
separate shared documents.

Rule 8. Elements and Objects shared by two or

more specifications MUST be defined in a shared
common data type library
Rule 9. Elements and Objects shared by two or

more components within a specification MUST be
defined in a shared data type library
7.2 Guidelines for Structuring Libraries
Some components are more likely to change than others. Specifically, code list types tend to change
frequently and depend on context. For this reason, code list types SHOULD be separated from complex
types that validate the structure of the document.
7.3 Versioning of the Common Library
Several different namespaces are used in the common library. First, one namespace is assigned for the
context-less components, and then common components that are related to a specific business process
have that context in their namespaces. Refer to the section on context for more details.
Rule 10. Common Library Version Changes Require

Version Changes to Business Documents
The individual files that constitute the common library can have minor versions, with backward
compatible changes. However, when the common library has a major version change, all business
documents that use the library MUST be upgraded.
7.4 Code List Management
Third-party code lists used within the IFSF data types SHOULD be defined as soft enum types in individual
library files and assigned to a data type other than the IFSF original type. Additional codes will be added
in a revision by updating the enumerate list in the datatype.
Rule 11. Third Party Code List Enumerations MUST

be implemented as soft enums
7.5 Hierarchy of Data Type Common Library Documents
All common data type libraries are stored under the libraries/common-vM.m.r folder.
All other libraries are stored under the corresponding libraries/group-vM.m.r folder, where group is the
name of the functional purpose of the group of libraries, for example wsm for wet stock management.
An often-used alternative name for a group is collection.

Rule 12. Recommendation – Keep all schemas for a

specification in the same folder (i.e., relative path).
7.6 File Naming Convention
IFSF data type libraries are given a name reflecting the business nomenclature of the types contained in
the library.
Rule 13. Data Type Document Named According to

Functional Purpose
For example, a Purchase Order data type library will be named "B2BPurchaseOrder.json".
8 Data Type Implementation Rules

IFSF and Conexxus data types are created using a specific set of rules to ensure uniformity of definition,
description, type, aliases and usage.
8.1 Documentation
8.1.1 Annotation Requirements
• Every enumeration SHOULD have an annotation.

• Every simple or complex type defined in the IFSF and Conexxus data definition documents
SHOULD have an annotation.
• Every element and attribute, including the root element, defined in the data definition
documents SHOULD have an annotation.
• All data definition annotations MUST be in English language.
JSON Schema has limited annotations support. In case of object description, JSON Schema supports the
description property that can be used to document the usage of the object defined. The other two
default metadata properties, title and default, can also be used as they are implemented by most JSON
schema processors.

Schema definition
{
"title": "User",
"description": "Describe what a User is",
"default": null,
"properties": {
"name": {
"title": "This is the User Name",
"type": "string"
}
},
"additionalProperties": true,
"type": "object",
"required": [ "name" ],
"$schema": "http://js-schema.org/draft-04/schema#"
}
8.1.2 Naming Conventions
Element, Object and type names MUST be in the English language.
Guideline: names SHOULD use standard terminology accepted within the retail fuels industry. Rationale:
Adoption by all parties SHOULD use names well accepted and defined by the industry.
Guideline: Names should be consistently applied regardless of geographical region (e.g. use
driver/passenger instead of left/right when applying to things that could switch sides depending on
right-hand vs left-hand driving standards, use terminology that is not regional-only like British “boot”
(for trunk), etc.,). Use American English spelling and terminology when words have multiple regional
options (e.g. use “Center” instead of “centre”). Rationale: Almost all OEMs provide world-wide
distributions and creating an API that did not allow transparent operation of applications across multiple
geographies is counterproductive.
Guideline: Do not use OEM, Oil Company, C-Store, supplier or Manufacturer specific terminology or
brand names (e.g. AdBlue for diesel additive). Rationale: Names should be consistent across fuel retailing
parties, and so avoid creating areas of conflict or misinterpretation.
Guideline: Create attributes that are independent of vehicle, forecourt equipment and store equipment
capability assumptions. Rationale: We do not want APIs to break when placed in a vehicle, forecourt or
store device that does not have the capability, or that has additional capabilities.
Guideline: Do not use attribute or enumeration names that hard-code assumptions on number. For
example “pumpNumber1”,” OPTNumber2”, or “NozzlesInRow1”..”pinPadNumber2” Rationale: Similar
to the guideline for creating attributes independent of vehicle, forecourt and store capability
assumption, this predisposes knowledge of the maximum value that an attribute may attain. Artificially
low limits constrain the API—what if your vehicle has more than 4 nozzles on a fueling point Artificially
high limits make the API look nonsensical. Both create an API that is not generic and non-orthogonal and
is not flexible for future extension. Data should be restructured such that the numerical information is
independent of the attribute name (perhaps by using multiple independent attributes).

Guideline: Create properties (attributes) that are independent of Mechanism. Rationale: Forecourt and
store equipment buses or technologies change—we don’t want the APIs to be describing obsolete
technologies. For example, don’t build APIs using Lon bus when the same service could be provided by
TCP/IP or HTTP.
8.2 Document Encoding
All JSON interfaces MUST employ UTF-8 encoding as defined in Part 2.3 IFSF document. If UTF-8
encoding is not used, interoperability between trading partners may be compromised and must be
independently evaluated by the trading partners involved.
8.3 Element Tag Names
8.3.1 Attribute and Types Names Use Lower Camel Case
For element attribute names (also called properties), the lower Camel Case (‘LCC’) convention MUST be
used. The first word in an element name begins with a lower-case letter with subsequent words
beginning with a capital letter without using hyphens or underscores between words. Rationale:
Following relatively common and widespread JavaScript practice.
In JSON files LCC convention SHOULD be applied to the Dictionary Entry Name (for both elements and
objects) and any white space (or equivalent) MUST be removed.
Usage of suffixes to denote a type name is not recommended as readability of a JSON Schema data type
is much easier than an XSD. Usage of Suffix enum to denote as soft enumerated data type is
recommended when the enumeration is not defined within the same data definition. See Section 10.7.7
for a description of "hard" vs "soft" enums.
8.3.2 Enumeration Rules
Rule 14. For enumeration values the Lower Camel

Case (‘LCC’) convention MUST be used.
Rule 15. Enumerations imported from other

dictionaries (i.e. states) MAY be used without
modification.
Enumerations are used when the values are from a small set of possible options. Enumerations are
created such that a caller can determine the range of possible responses without requiring this
information in advance. This means that enumerations should use the standard JavaScript
object.defineProperties method to set allowable values. Attribute types should not change (for example
from integer to enumeration, or from percentage to string), unless required for representation of special
values (like “unknown”, or “N/A”).
8.3.3 Acronyms and Identifiers

Rule 16. Acronyms and Identifiers are defined in the

data dictionary. Both SHOULD be written using
uppercase. Word abbreviations should be avoided.
When this rule conflicts with another rule that specifically calls for LCC, that rule requiring LCC SHALL
override. Names containing an acronym contain the uppercase version of the acronym (e.g. HVAC vs
Hvac, VIN vs Vin), as an exception to LCC. Rationale: This is how people expect to encounter the names,
also prevents issues with misunderstanding acronym as a “word”. Identifiers always use the
abbreviation ID; e.g. siteID not siteIdentifer, fuelingPointID not fuelingPointIdentifier.
8.3.4 Attribute value ranges and increments
Guideline: Minimum requirement is to annotate the valid range through the documentation but see also
8.7.3 below for details about numeric values. Rationale: Applications need to know the extent of the
allowable values. However, the range of valid values should be constant for each implementation, and
hence the range does not need to be dynamically accessible through the API. It is common practice in
JavaScript to denote allowable values through documentation. This in turn simplifies the burden of
implementing or adapting the API to each platform, vehicle, forecourt equipment or store equipment.
Guideline: No standard mechanism is provided to query the valid subset of ranges or allowable
increments for a particular attribute. Implementations can provide this feature optionally if they wish
for selected attributes. Rationale: The implementation may not itself know the possible values that an
underlying representation may take. Furthermore, a linear increment may not be possible. For example,
a sensor on the fuel tank may return values from 0 to 15, which represents the position of a physical
float in the tank or a liquid sensor against the side of the tank. The actual volume in the tank would be
dependent on a lookup table and computed by the service layer that receives the raw CAN data and
provides the values into the JavaScript interface. Hence, the possible fuel level values received by
JavaScript might be 0%, 1%, 3%, 5%, 15%, 25%, 40%, 50%, etc. The resulting values are non-linear and
may not be easily determined by the JavaScript API.
It is complicated to generalize the mechanism to supply a valid set of values for any arbitrary attribute.
Simplifying the implementation by allowing attributes to take any value within the range seems a
reasonable solution, especially since the value in providing that increment seems questionable and
would be hard in practice to properly deal with within the application.
8.3.5 Update Frequency
Dictionary elements and objects may change dynamically, e.g. tank temperature, tank stock, nozzle
meter readings. Any API is allowed to silently coalesce (merge) multiple calls to the same attribute if
they occur faster than a reasonable rate. No API is provided to the application that allows the maximum
update frequency to be queried. “Reasonable rate” is defined uniquely against an execution profile,
specific OS+ web platform, bus characteristics and communications and computer technology. E.g. some
dispenser still operating today use 8-bit technology and polling rates faster than once a minute may
overload the processor. Reasonable rate is also determined by how many simultaneous service requests
is received (multiple peers in a peer to peer environment). Rationale: The system needs to prevent
excessive LON/CAN/TCP-IP/HTTP/HTTPS communications bus updates to ensure proper operation of
the system under all conditions. This could be achieved through several mechanisms (adaptive CPU time
partitioning, CAN message traffic monitoring, automatic message folding/caching, strict rate limit, etc.).

It may be extremely difficult in practice to compute a maximum rate that is usable by the application.
This is especially true since that maximum rate may fluctuate and may be invalid by the time the
application attempts to utilize it.
8.4 Reusing data types
Reusing data types is done through the common library, as described in the previous section, or through
inheritance.
8.5 Referencing Data Types from Other Data Type Documents
Rule 17. References to Common Library data Type

documents MUST use a relative path to the
corresponding library.
Using relative paths allows the easy reuse of common libraries in other projects.
8.6 Elements order
In JSON, by definition:
An object is an unordered collection of zero or more name/value pairs, where a

name is a string and a value is a string, number, Boolean, null, object, or array.
An array is an ordered sequence of zero or more values.
Therefore, element order is interchangeable. JSON schema does not include provision of sequence
enforcing. Arrays of objects will maintain order. Note: when property sequence is important (e.g. for
decryption of payment and other sensitive/secret data then the object must clearly state that the
property list is ordered.)
8.7 Data Types
As a rule of thumb types SHOULD be used to convey business information entities, i.e. terms that have
a distinct meaning when used in a specific business context. Type names and descriptions SHOULD be
chosen to accurately reflect the information provided. For example, a "total" may need to include the
word "gross" or "nett" in the name to accurately identify the total. Clarification on the meaning or the
rationale behind the choice of name could be provided in the annotation.
8.7.1 Use of Nillability
API design include appropriate response codes when objects are unavailable.
Rule 18. Null values may be used if appropriate
There are two cases in which nillability may be useful:

 When the sending system cannot provide a value for a required element, the use of nil for that
element may be appropriate, as determined by the schema designers.

 When the sending system must indicate that the value of an optional element has changed from
a non-null value to null, the use of nil is appropriate.
In JSON it allows only JSON's null, (equivalent to XML's xsi:nil). In headers, URI parameters, and
query parameters, the null type only allows the string value "null" (case-sensitive); and in turn an
instance having the string value "null" (case-sensitive), when described with the null type, deserializes
to a null value.
When a non-existing resource is the subject of the request, consider a 404 HTTP error response instead
of returning a null JSON object (check part 2.0.3 - Communications over HTTP REST
In the following example, the type of an object and has two required properties, name and comment,
both defaulting to type string. In example, name is assigned a string value, but comment is null and
this is not allowed because a string is expected.
Schema definition
{
"properties": {
"name": {
"type": "string"
},
"comment": {
"type": "string"
}
},
"required": [ "name", "comment" ],
"$schema": "http://JSon-schema.org/draft-04/schema#"
}
Example: Providing a value or a null value here is required

{
“name”: "fred",
“comment”: null
}
The following example shows how to declare nullable properties using a union:
Schema definition
{
"properties": {
"name": {
"type": "string"
},
"comment": {
"type": ["null", "string"]
}
},
}
Example: Providing a value or a null value here is allowed
{

“name”: "fred",
“comment”: null
}
Declaring the type of a property to be null represents the lack of a value in a type instance.
8.7.2 Boolean values
Rule 19. Boolean values MUST be represented as

enum data types.
Boolean elements and attributes SHOULD use the data type <enum>.
Usage of enumeration codes instead of native Boolean type is recommended as in the future it might
be necessary to change from Boolean to enumeration. E.g. initial authorisation response might be
considered Yes or No but subsequently it became Yes but check signature or No but
local override possible. Use of Boolean might increase maintenance issues in the future.
{
"isMarried": {
"enum": [ "Yes", "No" ]
}
}
8.7.3 Numeric values
Rule 20. Numeric values SHOULD be defined as

positive.
The use of JSON property minimum: 0 for data type number is encouraged but not required. The
type name itself should imply the type of value contained so that a positive value makes sense. As an
example, a bank amount type should be defined as either "Credit" or "Debit" so that the intended type
is explicit.
Example:
{
"credit": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": false
}
}

Rule 21. Data types SHALL NOT use unbounded

numeric data types without proper constraints
Either the minimum and maximum values or the maximum number of digits for elements and attributes
of numeric data types should be specified. Shrinking the boundary conditions for an element or attribute
may only be done in a major version. Enlarging the boundary conditions for an element or an attribute
may be done in minor or major versions.
{
"weight": {
"type": "number",
"minimum": 4,
"maximum": 100,
"exclusiveMinimum": false,
"exclusiveMaximum": false,
"multipleOf": "4",
}
}
Units and types: Guideline: All values of attributes are consistently represented as SI (metric) units,
string, percentage, boolean, or enumerations. Rationale: Using percentages when possible instead of
unit based values allows a calling application to be easily adaptable when value ranges change between
vehicle models. For numeric non-percentage values, SI is a consistent unit system that is globally
understood and used for all scientific endeavours. American units are supported in USA only.
8.7.4 String values
Rule 22. Data types SHALL NOT use elements of

type string without an accompanying constraint on
the overall length of the string.
Shrinking the boundary conditions for an element or attribute may only be done in a major version.
Enlarging the boundary conditions for an element or an attribute may be done in minor or major
versions.
{
"tankLabel": {
"type": "string"
"minLength": 1,
"maxLength": 16
}
}
Note: Data type string also supports a pattern constraint through a regular expression. The JSON
Schema specification recommends the regular expressions to be ECMA 262 compliant.

8.7.5 Arrays
Rule 23. Data types SHOULD NOT use arrays of

elements without an accompanying constraint on the
overall quantity of items.
Shrinking the array boundary conditions may only be done in a major version. Enlarging the boundary
conditions may be done in minor or major versions.
8.7.6 Date time values
Rule 24. IFSF and Conexxus MUST use RFC3339

compliant date and time formats.
Rule 25. Time Offset must be included whenever

possible.
The inclusion of the time offset for Time and Date-Time values provide for easier integration when
devices and servers operate in different time zones.
Example 1: Date and time with time zone

{
"startPeriodDataTime": {
"type": "string",
"format": "date-time"
}
}
Values:
1996-12-19T16:39:57-08:00
1996-12-19T16:39:57
1996-12-19
Example 2: Date and time without time zone

{
"dateAndTime": {
"type": "string",
"pattern": "^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})$"
}
}

Value:
1996-12-19T16:39:57
Example 3: Date only

{
"dateOnly": {
"type": "string",
"pattern": "^(\d{4})-(\d{2})-(\d{2})$"
}
}
Value:
1996-12-19
Example 4: Time only

{
"timeOnly": {
"type": "string",
"pattern": "^(\d{2}):(\d{2}):(\d{2})$"
}
}
Value:
16:39:57
Note: The above regular expressions regulate the format of the text within the field, but it is not
sufficient to ensure a proper date is included. Additional logic must be included when implementing APIs
to ensure valid date values. The JSON Schema specification recommends the regular expressions to be
ECMA 262 compliant.
8.7.7 Hard and Soft Enumerations
Rule 26. When all elements of an enumeration have

the same treatment, soft enums MUST be used.
 A hard enum only accepts values that are in the enum list, because special treatment is required
for one or more values.
 A soft enum is a type that allows values that are not listed in the enum.

Example 1: Currency Soft Enum

{
"currencyCodeSoftEnum": {
"type": "string",
"anyOf": [
{ "type": "string" },
{ "type": "currencyCodeEnum" }
]},
"currencyCodeEnum": {
"type": "string",
"enum": ["USD", "BGP", "EUR"]
}
}
}
Example 2: Card Type Hard Enum

{
"cardTypeHardEnum": {
"enum": [ "CREDIT", "DEBIT" ]
}
}
Example 2: Enums Properties

{
"payment": {
"properties": {
"cardType": {
"type": "cardTypeHardEnum"
},
"currencyCode": {
"type": "currencyCodeSoftEnum"
},
"amount": {
"type": "number"
}
}
}
}
{
"cardType": "CREDIT",
"currencyCode": "USD",
"amount": "1"
}
Note: this rules does not imply that properties defined for these enum types must contain the words
hard or soft.

8.7.7.1 Updating Hard Enumerations
Rule 27. Hard enumerations values MAY be added in

a minor version
Since the addition of a new enumerated value to an existing enumeration is backward compatible with
documents valid under the previous version of the code list, the addition of new code list values MAY
be included in a minor version of a given IFSF schema.
Rule 28. Hard enumerations values MAY only be

removed in a major version
The removal of an enumerated value from an enumeration breaks backward compatibility and MUST
therefore occur in major versions only.
Rule 29. Hard enumerations values MAY be

rescinded in a version revision
"Rescinded" means will be removed at future major release. Until a future release the element MUST
not be used in new implementations and during maintenance of existing applications checked that it is
no longer used.
8.7.7.2 Updating Soft Enumerations
Rule 30. Soft enumerations values MAY be added or

removed in a version revision
Using soft enums allows the enumeration values to be updated in a revision without compromising
compatibility. E.g. When a country has been recognised/unrecognized by United Nations, its country
code can be supported/removed with a revision.

8.7.8 Object Lists
Rule 31. Object lists should be paginated, providing

pagination references through link headers.
Some IFSF API requests might offer results paging. The way to include pagination details is using the
Link header introduced by RFC 5988.
For example:
GET http://api.ifsf.org/ifsf-fdc/v1/sites?zone=Boston&start=20&limit=5
The response should include pagination information in the Link header field as depicted below
{
"start": 1,
"count": 5,
"totalCount": 100,
"totalPages": 20,
"links": [{
"href": "http://api.ifsf.org/ifsffdc/v1/sites?zone=Boston&start=26&limit=5",
"rel": "next"
},
{
"href": "http://api.ifsf.org/ifsffdc/v1/sites?zone=Boston&start=16&limit=5",
"rel": "previous"
}]
}

9 Proprietary Extensions
A proposal to allow all classes to be extensible by the vendors in order to make IFSF web APIS more
attractive to those who want to add features quickly without having to wait for new official API releases.
All classes derive from an extensible class that has an extra property that can contain an array of
extensions.
{
"definitions": {
"extensible": {
"type": "object",
"properties": {
"extensions":{
"type": "array",
"items": {
"$ref": "#/definitions/extension"
}
}
}
}
}
}
Each extension has an ID and a payload that is an array of strings that will conform a JSON.
{
"definitions": {
"extension": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"payload": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [ "id", "payload" ]
}
}
}
Applications must support the existence of an "extensions" object and process only supported
extensions IDs and ignore the rest.

9.1 Extensions Example
An example of extensibility is the case of "tankMovementReport.JSon" where additional data for tank
delivery information for CNG is required. As the CNG is delivered through the gas network, and the
delivered GNC is measured using a device that captures a delivered volume totalizer, then an extension
proposal could be to register the incoming gas measurement device running totals to calculate the gas
delivered by the network.
In this case, the proposed extension could be:
New extension ID: naturalGasMeterTotals
And the extension payload would be the following JSON string:
{
"openingRunningTotal": "123456",
"openingTimestamp": "2005-07-05T13:14Z",
"closingRunningTotal": "144415",
"closingTimestamp": "2005-07-05T13:14Z"
}
As JSON lacks multiline strings support, to ensure readability, the payload is defined as an array of
strings. Endpoints should concatenate the array contents and treat it as a single JSON string.
Hence, the received CNG volume, properly escaped in the tank movement report, and split in on string
per line for improved readability, would be reported as:
{
"deliveryVolumes": [{
"reading": "20959",
"extensions": [{
"id": "naturalGasMeterTotals",
"payload": ["{",
"\"openingRunningTotal\" : \"12345\",",
" \"openingTimeStamp\" : \"2005-07-05T13:14Z\",",
" \"closingRunningTotal\" : \"12777\",",
" \"closingTimeStamp\" : \"2005-07-06T13:01Z\",",
"}"]
}]
}]
}
Once concatenated, the equivalent payload is a properly escaped JSON string in a single line:
"{\"openingRunningTotal\" : \"12345\",\"openingTimestamp\" : \"2005-07-

05T13:14Z\",\"closingRunningTotal\" : \"12777\",\"closingTimestamp\" :
\"2005-07-06T13:01Z\"}"

Note: This implementation also allows a vendor to define the payload to be a base64 encoded string
containing the object or a compressed version of the object. This might become useful in case an
extension is of considerable size, such as a dispenser log or binary content.
9.2 Class extensibility promotion in IFSF:
In order to avoid rework by a company developing an application that requires an extension to the
protocol, our proposal is to:
 Determine the required extension.
 Implement the extension, using a unique label.
 If IFSF approves the extension, for all minor releases of the protocol the extension will be
approved and listed as an EB in IFSF portal.
 Once a new major release is released, the extensions might be promoted as a new object in
the API spec. Although this will need rework from the development company, a major release
will surely contain other changes that will require rework for certification.

10 Rules Summary
Rule 1. Backward Compatibility for Revisions
Rule 2. Forward Compatibility for Revisions Only
Rule 3. Revisions (Versions) are backwardly and forwardly compatible
Rule 4. Minor versions are backwardly compatible
Rule 5. All data types within a business process have same version
Rule 6. Versions will be represented using numeric digits
Rule 7. Full version number reflected in library folders
Rule 8. Elements and Objects shared by two or more specifications MUST be defined in a shared
common data type library
Rule 9. Elements and Objects shared by two or more components within a specification MUST be
defined in a shared data type library
Rule 10. Common Library Version Changes Require Version Changes to Business Documents
Rule 11. Third Party Code List Enumerations MUST be implemented as soft enums
Rule 12. Recommendation – Keep all schemas for a specification in the same folder (i.e., relative
path).
Rule 13. Data Type Document Named According to Functional Purpose
Rule 14. For enumeration values the Lower Camel Case (‘LCC’) convention MUST be used.
Rule 15. Enumerations imported from other dictionaries (i.e. states) MAY be used without
modification.
Rule 16. Acronyms and Identifiers are defined in the data dictionary. Both SHOULD be written using
uppercase. Word abbreviations should be avoided.
Rule 17. References to Common Library data Type documents MUST use a relative path to the
corresponding library.
Rule 18. Null values may be used if appropriate
Rule 19. Boolean values MUST be represented as enum data types.
Rule 20. Numeric values SHOULD be defined as positive.
Rule 21. Data types SHALL NOT use unbounded numeric data types without proper constraints
Rule 22. Data types SHALL NOT use elements of type string without an accompanying constraint on
the overall length of the string.
Rule 23. Data types SHOULD NOT use arrays of elements without an accompanying constraint on the
overall quantity of items.
Rule 24. IFSF and Conexxus MUST use RFC3339 compliant date and time formats.
Rule 25. Time Offset must be included whenever possible.
Rule 26. When all elements of an enumeration have the same treatment, soft enums MUST be used.
Rule 27. Hard enumerations values MAY be added in a minor version
Rule 28. Hard enumerations values MAY only be removed in a major version
Rule 29. Hard enumerations values MAY be rescinded in a version revision
Rule 30. Soft enumerations values MAY be added or removed in a version revision
Rule 31. Object lists should be paginated, providing pagination references through link headers.

Design Rules For JSON V1.0.1

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Design Rules For JSON V1.0.1

Uploaded by

Copyright:

Available Formats

Design Rules for JSON Revision / Date: Page:

Version 1.1 (Draft) / 18 July 2018 1 of 32

DESIGN RULES FOR JSON

This document describes the International Forecourt Standards Forum

Design Rules for JSON V1.0.1 Page 1 of 32

Axel Mammes, OrionTech

Design Rules for JSON V1.0.1 Page 2 of 32

Revision Date Revision Revision Editor(s) Revision Changes

Design Rules for JSON V1.0.1 Page 3 of 32

Design Rules for JSON V1.0.1 Page 4 of 32

Design Rules for JSON V1.0.1 Page 5 of 32

Design Rules for JSON V1.0.1 Page 6 of 32

8.5 REFERENCING DATA TYPES FROM OTHER DATA TYPE DOCUMENTS........................................................ 20

Design Rules for JSON V1.0.1 Page 7 of 32

[1] IFSF STANDARD FORECOURT PROTOCOL PART II – COMMUNICATION SPECIFICATION

Design Rules for JSON V1.0.1 Page 8 of 32

Port A logical address of a service/protocol that is available on a particular computer.

IFSF International Forecourt Standards Forum

REST REpresentational State Transfer) is an architectural style, and an approach to

TIP IFSF Technical Interested Party

Design Rules for JSON V1.0.1 Page 9 of 32

The intended audiences of this document include, non-exhaustively:

4.3 What is REST?

4.4 Usage of JSON

Design Rules for JSON V1.0.1 Page 10 of 32

5.1 Overall JSON Design

5.2 Commercial Messages

"Edited by <owner> with <JSchema editor> V2.0".

6.1 Backward Compatibility

Rule 1. Backward Compatibility for Revisions

Design Rules for JSON V1.0.1 Page 11 of 32

6.2 Forward Compatibility

Rule 2. Forward Compatibility for Revisions Only

6.3 Version Numbering

Rule 3. Revisions (Versions) are backwardly and

Rule 4. Minor versions are backwardly compatible

Rule 5. All data types within a business process

Design Rules for JSON V1.0.1 Page 12 of 32

6.3.1 Examples of Changes that can be incorporated in a Revision

• Adding Comments and Errata

6.3.2 Examples of Changes that can be incorporated in a Minor Version

• Adding new optional properties.

6.3.3 Examples of Changes that Dictate a Major Version (new Release)

• Changing a property from optional to required.

6.3.4 Reflecting the Version Numbers for Data Types

Rule 6. Versions will be represented using numeric

Design Rules for JSON V1.0.1 Page 13 of 32

o The first revision of a minor version will be numbered M.m.1.

Rule 7. Full version number reflected

Library file path examples:

7 The Common Library

7.1 Designing the Common Library

Specifically, these areas need to be addressed:

Design Rules for JSON V1.0.1 Page 14 of 32

Rule 8. Elements and Objects shared by two or

Rule 9. Elements and Objects shared by two or

7.2 Guidelines for Structuring Libraries

7.3 Versioning of the Common Library

Rule 10. Common Library Version Changes Require

7.4 Code List Management

Rule 11. Third Party Code List Enumerations MUST

7.5 Hierarchy of Data Type Common Library Documents

Design Rules for JSON V1.0.1 Page 15 of 32