Skip to content

Latest commit

 

History

History
144 lines (112 loc) · 7.83 KB

2-Datamodel.md

File metadata and controls

144 lines (112 loc) · 7.83 KB

Section 1: Datamodel

Central to the OpenCannabis project's goals is a unified datamodel for use across functional boundaries. When cultivators talk about flowers with labs, and labs talk about test results with retailers, and so on, they are all talking about the same thing - but in today's legal cannabis industry, they aren't speaking the same language.

Table of Contents

  1. Toolchain
  2. General Guidelines
  3. Message Categories
    • Part 1.1: Core Structures
      • base: Foundational structures used across the spec.
      • temporal: Dates, times, and so on.
      • crypto: Cryptographic primitives and containers.
      • geo: Structures relating to geography.
      • device: Managed and anonymous, operating systems, browsers.
      • content: Narrative and marketing content.
      • person: People, names, birth dates, and so on.
      • contact: Email, phone, and postal addresses.
      • media: Images, video, documents, etc.
      • structs: Utility structures used across the spec.
    • Part 1.2: Extension Structures
      • labtesting: Laboratory testing and QA.
      • pricing: Pricing schemes and structures.
      • proximity: Bluetooth and GPS-related structures.
      • oauth: OAuth2 implementation structures.
      • products: High-level product structures.
      • commerce: Commercial ordering and fulfillment structures.
      • accounting: Bookkeeping, accounting, taxes, and so on.

i. Toolchain

The model put forth by OpenCannabis is specified in a programming language called Protocol Buffers that originated inside Google. Protobuf, as it is referred to colloquially, has numerous strengths that this project leverages to deliver better compatibility and support to spec adopters:

  • Protobuf is an easy language to learn, even for non-technical contributors
  • Models written in Protobuf can be compiled into a ton of languages: all popular ones and quite a few others, too. This means: complete language agnosticism if you are adopting OpenCannabis! 🚀
    • Language support includes, but is not limited to: C/C++, Java, C#, Python Go, Objective-C, Swift, PHP, and R
  • Custom Protobuf plugins can be written to generate custom code, docs, or other materials
  • Compatibility with other Protobuf-authored models, such as OpenRTB and Google APIs

A. Nomenclature

Models implemented in Protobuf are referred to as Messages. Services, which specify Methods, make use of Messages as input and output structures.

ii. General Guidelines

These guidelines govern how OpenCannabis specifications make use of Protobuf.

  1. Models accompanying a specification MUST provide an implementation written in Protobuf.
  2. Source files MUST use the syntax mode proto3.
  3. Source files MUST use the package prefix with opencannabis.
  4. Source files MUST adhere to the policies in 3/OCS- 1.2(A-D).

A. Source file guidelines

These guidelines govern how OpenCannabis protobuf source files must be formatted and specified.

  1. Source files MUST specify a java_package.
  2. Source files MUST specify a objc_class_prefix.
  3. Source files MUST specify a Java package starting with io.opencannabis.
  4. Source files MUST place exactly one newline at the beginning of the file.
  5. Source files MUST place exactly one newline after the syntax = proto3 declaration.
  6. Source files MUST list file-level options immediately after the syntax declaration.
  7. Source files MUST list imports immediately after file-level options, separated by exactly one newline.
  8. Source files MUST place exactly two newlines after the imports.
  9. Source files SHOULD specify an optimize_for value of SPEED.
  10. Source files SHOULD specify a java_outer_classname.
  11. Source files SHOULD make use of the objc_class_prefix value of OCS.
  12. Source files SHOULD place enum specifications at the beginning of the file.
  13. Source files SHOULD place service specifications at the end of the file.
  14. Source files MAY break up many imports into groups, each separated by exactly one newline.

B. Messages

These guidelines govern how OpenCannabis protobuf messages are structured and specified.

  1. Messages MUST begin with a capital letter.
  2. Messages MUST adhere to CamelCase when including multiple words in their name.
  3. Messages MUST include a comment describing their use and purpose, according to 3/OCS-1.2(D).
  4. Messages MUST select or allocate a Message Category according to 3/OCS-1.3.
  5. Messages MUST include exactly one newline between each other.
  6. Messages MUST immediately begin properties without an initial newline.
  7. Messages MUST NOT include a terminal newline before the closing curly bracket.
  8. Messages SHOULD specify required or notable properties first.

C. Properties

These guidelines govern individual message properties.

  1. Properties MUST be specified in all-lowercase, underscored form (i.e., example_property_name).
  2. Properties MUST include exactly one newline after their definition, unless they are the last property specified.
  3. Properties MUST include a comment describing their use and purpose, according to 3/OCS-1.2(D).

D. Commenting

These guidelines govern inline source comments on Messages, Properties, Services and Methods.

  1. Comments MUST begin with a single space.
  2. Comments MUST end with a period.
  3. Comments MUST occur directly above the entry they are commenting on, with no newline below.
  4. Comments MUST wrap lines at 80 characters; no less, no more.
  5. Comments SHOULD describe their subject in simple, easy-to-understand terms.
  6. Comments SHOULD be complete sentences, in present-imperative form (i.e., 'Specifies xyz, in abc circumstances.').

iii. Message Categories

Messages may be grouped or placed adjacently according to their functional purpose. Message categories may either be included in the core specification, (in which case, they are considered Core Message Categories) or they are proposed by an Extension to the OpenCannabis specification, the process for which is specified below in Subsection B. Each Core Message Category and Extension Message Category must include the models and procedures associated with that category.

All categories are to be registered, and listed accordingly in the main specification, in Appendix A: Model Categories, along with their type and maturity status.

These guidelines govern the taxonomic process and interpretation of message categories:

  1. Message categories MUST follow the 1/C4 and 2/COSS guidelines and lifecycle.
  2. Message categories MUST be addressed by a one-word name in all-lowercase.
  3. Message categories MUST align folder structure with Protocol Buffer package structure.
  4. Message categories MUST NOT be coupled to stakeholder boundaries (i.e., cultivation or manufacturing).
  5. Contributors MUST provide a strong rationale for creating a new message category.
  6. Contributors SHOULD make an attempt to use an existing category rather than create one.
  7. Message categories SHOULD be allocated according to functional boundaries (i.e., media or analytics)
  8. Message categories MAY be nested in other message categories.