README.md 4.04 KB
Newer Older
John Carrier's avatar
John Carrier committed
1 2


3
Welcome to the **API Data Dictionary** (“Dictionary”), jointly owned by the IFSF (www.ifsf.org) and Conexxus (www.conexxus.org), and shared in order to assist in the use of our international standards.
John Carrier's avatar
John Carrier committed
4

5
This version is a DRAFT and is for discussion only.  It is improper to attempt to use the definitions herein in live applications or to cite this version other than as a work in progress.
John Carrier's avatar
John Carrier committed
6

7
This Dictionary is created specifically for use in petroleum and convenience retail.  The definitions in the Dictionary have been in wide use for almost two decades.
John Carrier's avatar
John Carrier committed
8

9 10 11 12 13
Ultimately, the dictionary will contain the following directories:
- schemas:  this directory contains the business domain items (elements, types, objects).
- traits: contains definitions useful across the set of all APIs, but outside the business domain.
- utilities: contains definitions useful for messaging, but outside the business domain.
- examples: contains example files conforming to various definitions.
John Carrier's avatar
John Carrier committed
14

15 16 17 18 19 20 21 22 23 24 25 26
In version 0.1, only the "schema" directory is eligible for review.

The Dictionary is made up of 3 kinds of entries:
- Types: these entries provide restraints on number, string, and date types in JSON.  A special subgroup, "Base Types," are non-industry specific, but aid in keeping definitions of other types systematically aligned. Types are analogous to XML Schema Simple Type definitions.
- Elements: these entries bind a property name to a type.  Elements are especially useful for helping to assure that names for things are used consistently in the specifications.  Elements normally appear in lists defined as "allOf:", "anyOf:", or "oneOf:".  Elements are analogous to XML Schema Element Declarations.
- Objects: these entries group property name / type pairs into a set that can be reused.  Objects are analogous to XML Schema Complex Type Definitions. 

The Dictionary is licensed under the Creative Commons Attribution 4.0 International Public License (“Public License”), which can be read in full in the Section 0.1 License. For the purpose of clarity, under this Public License, IFSF and Conexxus jointly shall hold the copyright on the Dictionary and act as Co-Licensors. The License granted by the IFSF and Conexxus applies to the Dictionary, including the owners’ Sui Generis Database Rights (“Database Rights” i.e., rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world). Under the License, users are free to use the Dictionary to create Adapted Material, where all such material is subject to the copyright and Database Rights that are derived from or based upon the Dictionary. Co-Licensors hereby grant a user a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Dictionary to: (a) reproduce and share the Dictionary, in whole or in part, without removing any copyright notice; and (b) produce, reproduce, and share its Adapted Material. Please be aware, however, that if you intend to translate, alter, arrange, transform, or otherwise modify the Dictionary, you must obtain written permission in advance from the Co-Licensors.

The APIs (not enumerated here), which use the types, elements, and objects described, are owned and hosted on "gitlab.openretailing.org" where membership may be necessary to gain access to any specific API definitions, simulators, or other materials.

Members of the public are requested to inform us of missing data elements and objects at the following: support@openretailing.org. Similarly, requests for corrections, additions, improvements, and clarifications of the existing elements and objects are welcome. All proposed changes will be reviewed by work groups within Conexxus and IFSF, and potentially be accepted into the Data Dictionary. Changes and additions are reviewed to assure consistency throughout the dictionary and to avoid duplications of the same name being used for the identical element or object.