Table of Content
- New Files
- Reporting Issues
- Contributing a new data model
- Commit new file(s) e.g. data models
- Select "Create a new branch for this commit and start a pull request."
- Name the branch with a descriptive name
- Click on "propose new file"
- Assign at least the workgroup manager responsible for your domain to the pull request
- Assign a descriptive label to the pull request
- Click on "create pull request"
For any issue (suggestion, bug, fix, etc.) there are fundamentally two ways an individual can contribute:
- By helping to triage the issue: This can be done either by providing supporting details (a test case that demonstrates a bug), or providing suggestions on how to address the issue.
- By helping to resolve the issue: Typically this is done either in the form of demonstrating that the issue reported is not a problem after all, or more often, by opening a Pull Request that changes some bit of something in Open Integration Hub in a concrete and reviewable manner.
Definition of Done
An issue is marked as done, if all of the following criteria are fulfilled:
- All acceptance criteria have been fulfilled
- All Workgroup committer approved the content
- Content is Open Source under https://www.github.com/openintegrationhub/data-and-domain-models
Contributing a new data model
The OIH is an open-source platform maintained by the cloud community under the leadership of the Cloud Ecosystem. It can be run with any model which is designed and implemented by the rules and regulations listed so far.
In addition to the OIH platform itself, the OIH community also provides and maintains a number of concrete Master Data Models to be used by any OIH instance, such as models for contacts/addresses or products.
For these models, there are some further rules and regulations to follow in order to be presented in a unified way. This helps to understand and, above all, use them (i.e., implementing OIH Connectors for applications to be integrated with - respectively via - an OIH).
- Create a new folder within the MasterDataModel folder and name it equally to the domain the model is provided for
- The first page of the folder has to follow the structure of the ReadmeTemplate to guarantee a unified description of all master data models
Types and Properties
- All type and property naming has to be in CamelCase:
- Type names are always spelled in upper camel case (e.g., UpperCamelCaseType).
- Property names are always spelled in lower camel case (e.g., lowerCamelCaseProperty).
- All type and property naming has to be done in English language.
- The prefixes OIH and *OIH* (or oih and *oih* for properties) are reserved for types and properties of OIH related Types and fields and may not be used for definitions in concrete models.__
Some attributes are used across multiple models (such as "description"). To ensure consistency across all models, some of these attributes and how they should be named wihtin OIH Data Models are listed in the following:
|OIH Attribute Name||Other frequently used synonyms||Description|
|deleted||deleted, removed||Flag to mark a dataset as deleted or removed|
|type||type, baseType, productType, setType, ...||Used to describe the specifc object. Expection: Two or more types attributes are needed for one object|
|notes||notes, note, additionalInformation, extraInformation, etc.||Used to provide additional information for the specific object (beyond description)|
|url||url, link||Used for all kind of links associated with the specific object|
|value||value, data||Used for the acutal content of a specific object E.g. in classical pair. (Example: Contact Data (Type: Email, Value: ...@example.com"))|
|is...||All boolean attributes without
||Attributes of type boolean. Should be labeled starting with
|tags||flags, labels||Attribute which assigns different descriptive buzzwords to an object|
Schema file names are always lowercase.
As a seperator within file names a hyphen (-) may be used (e.g. some-schema.json).
The schema-ID (the $id property in a JSON-Schema) is always structured as follows:
- The global context is http://openintegrationhub.org/schemas/
- followed by a context directory and the name of the schema file (including the .json suffix)
Every field in a JSON-Schema must have a description property, as long as it's (even potentially) not self-explanatory.
UML Class Diagrams
Every OMDM must be depicted by one or more UML Class Diagrams, which illustrate the static aspect of the model. I.e., amongst others:
- of which different OIH Data Records and entities (types) the OMDM constists,
- how every OIH Data Record itself is composed,
- how the OIH Data Records are related to each other,
- which properties every entity (type) has.
Every OIH Data Record is defined by a Generalization relation (OIHDataRecord is modelled as the superclass of the respective sub-model, s. 5. Example: the Order aggregate).
Property types may, but must not be declared in the diagrams as the main purpose of these diagrams is to clarify the structure of an OMDM.
Following the Domain-Driven-Design all standalone objects (such as person and organization within the address model) should be coloured in yellow
Other attributes should be coloured in blue (See: Address model)
Clarify all further aspects of a model with diagrams and/or textually
Schemas and class diagrams only point out static aspects of a data model. Normally, there are further (e.g. dynamic) aspects of a model, that those descriptions do not point out (e.g. the conscious acceptance of redundancy). To enable ISVs and any other developers to understand and work with an OMDM,
- all relevant aspects of a model, that are not derivable from JSON-Schemas or UML Class Diagrams have to be described textually and by further illustrations of any kind.